tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(phase-9.75g-0): Adopt ChatGPT final BID-FFI design and update specifications

Browse Source 
- Update ffi-abi-specification.md to BID-1 Enhanced Edition
  - Add efficient Handle design (type_id + instance_id)
  - Define BID-1 TLV unified format for arguments/results
  - Add Plugin API with NyashHostVtable and metadata support
  - Include complete FileBox plugin example in C
  - Standardize error codes (NYB_SUCCESS, NYB_E_*)
  - Support 8-byte alignment and platform-dependent usize

- Add phase_9_75g_0_chatgpt_enhanced_final.md as the final design
  - Incorporates all ChatGPT-5 recommendations
  - Confirms 1-week implementation feasibility
  - Aligns with Everything is Box philosophy

- Update CURRENT_TASK.md to reflect Day 1 progress
  - Mark specification finalization as complete
  - Ready to start actual implementation

Everything is Box philosophy meets practical FFI/ABI design\!

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Moe Charm
2025-08-17 18:17:04 +09:00
parent 75d09a89a8
commit 2b738196ca
3 changed files with 663 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

347
docs/予定/native-plan/issues/phase_9_75g_0_chatgpt_enhanced_final.md Normal file
View File

@ -0,0 +1,347 @@
# Phase 9.75g-0 最終決定版: ChatGPT先生の知恵を完全適用
## 🎯 ChatGPT先生の最終判定
> **方向性は正しい**: primitives-by-value + box-by-handle は適切で、Everything is Box哲学を維持している。
> **1週間Phase 1は現実的**（スコープを限定すれば）
## 🌟 修正された型システム設計
### 1. Handle設計の改善（ChatGPT提案）
```rust
// src/bid/types.rs - ChatGPT推奨の効率的設計
#[derive(Clone, Debug, PartialEq)]
pub enum BidType {
// === プリミティブ（FFI境界で値渡し） ===
Bool, // Nyashのbool literal
I32, // 32ビット整数
I64, // Nyashの標準整数
F32, // 32ビット浮動小数点
F64, // Nyashの標準浮動小数点
String, // UTF-8文字列 (ptr: usize, len: usize)
Bytes, // バイナリデータ (ptr: usize, len: usize)
// === ChatGPT推奨: 効率的なHandle設計 ===
Handle {
type_id: u32, // StringBox=1, FileBox=6等
instance_id: u32, // インスタンス識別子
},
// 代替: 単一u64として type_id << 32 | instance_id も可
// === メタ型 ===
Void, // 戻り値なし
// === Phase 2予約（TLVタグ予約済み） ===
Option(Box<BidType>), // TLVタグ=21
Result(Box<BidType>, Box<BidType>), // TLVタグ=20
Array(Box<BidType>), // TLVタグ=22
}
// Everything is Box対応表（修正版）
/*
Handle{type_id: 1, instance_id: 123} → StringBox インスタンス
Handle{type_id: 6, instance_id: 456} → FileBox プラグイン
Handle{type_id: 7, instance_id: 789} → FutureBox（既存活用）
Handle{type_id: 8, instance_id: 101} → P2PBox（既存）
*/
```
### 2. BID-1 TLV統一フォーマット（ChatGPT仕様）
```c
// BID-1 TLV仕様 - 引数・結果の統一フォーマット
struct BidTLV {
u16 version; // 1（BID-1）
u16 argc; // 引数数
// 後続: TLVエントリの配列
};
// TLVエントリ構造
struct TLVEntry {
u8 tag; // 型タグ
u8 reserved; // 将来用（0）
u16 size; // ペイロードサイズ
// 後続: ペイロードデータ
};
// タグ定義（Phase 1）
#define BID_TAG_BOOL 1 // payload: 1 byte (0/1)
#define BID_TAG_I32 2 // payload: 4 bytes (little-endian)
#define BID_TAG_I64 3 // payload: 8 bytes (little-endian)
#define BID_TAG_F32 4 // payload: 4 bytes (IEEE 754)
#define BID_TAG_F64 5 // payload: 8 bytes (IEEE 754)
#define BID_TAG_STRING 6 // payload: UTF-8 bytes
#define BID_TAG_BYTES 7 // payload: binary data
#define BID_TAG_HANDLE 8 // payload: 8 bytes (type_id + instance_id)
// Phase 2予約
#define BID_TAG_RESULT 20 // Result<T,E>
#define BID_TAG_OPTION 21 // Option<T>
#define BID_TAG_ARRAY 22 // Array<T>
```
### 3. メタデータAPI追加（ChatGPT推奨）
```c
// src/bid/plugin_api.h - プラグインAPI完全版
// ホスト機能テーブル
typedef struct {
void* (*alloc)(size_t size); // メモリ確保
void (*free)(void* ptr); // メモリ解放
void (*wake)(u32 future_id); // FutureBox起床
void (*log)(const char* msg); // ログ出力
} NyashHostVtable;
// プラグイン情報
typedef struct {
u32 type_id; // Box型ID
const char* type_name; // "FileBox"等
u32 method_count; // メソッド数
const NyashMethodInfo* methods; // メソッドテーブル
} NyashPluginInfo;
typedef struct {
u32 method_id; // メソッドID
const char* method_name; // "open", "read"等
u32 signature_hash; // 型シグネチャハッシュ
} NyashMethodInfo;
// プラグインAPI（必須実装）
extern "C" {
// ABI版本取得
u32 nyash_plugin_abi(void);
// 初期化（ホスト連携・メタデータ登録）
i32 nyash_plugin_init(const NyashHostVtable* host, NyashPluginInfo* info);
// 統一メソッド呼び出し
i32 nyash_plugin_invoke(
u32 type_id, // Box型ID
u32 method_id, // メソッドID
u32 instance_id, // インスタンスID
const u8* args, // BID-1 TLV引数
size_t args_len, // 引数サイズ
u8* result, // BID-1 TLV結果
size_t* result_len // 結果サイズ（入出力）
);
// 終了処理
void nyash_plugin_shutdown(void);
}
```
### 4. メモリ管理の明確化（ChatGPT推奨）
```c
// 2回呼び出しパターン
i32 call_plugin_method(...) {
size_t result_size = 0;
// 1回目: サイズ取得（result=null）
i32 status = nyash_plugin_invoke(..., NULL, &result_size);
if (status != 0) return status;
// 2回目: ホストがallocateして結果取得
u8* result_buffer = host_alloc(result_size);
status = nyash_plugin_invoke(..., result_buffer, &result_size);
// 結果処理...
host_free(result_buffer);
return status;
}
// エラーコード定義
#define NYB_SUCCESS 0
#define NYB_E_SHORT_BUFFER -1 // バッファ不足
#define NYB_E_INVALID_TYPE -2 // 不正な型ID
#define NYB_E_INVALID_METHOD -3 // 不正なメソッドID
#define NYB_E_INVALID_ARGS -4 // 不正な引数
#define NYB_E_PLUGIN_ERROR -5 // プラグイン内部エラー
```
## 📋 修正された実装計画
### Phase 1実装チェックリスト（ChatGPT提案）
#### Day 1: BID-1基盤実装
- [ ] **BID-1 TLV仕様**とエラーコード定義
- [ ] **Handle{type_id,instance_id}**構造体実装
- [ ] **基本TLVエンコード/デコード**機能
- [ ] テスト: プリミティブ型のTLV変換
#### Day 2: メタデータAPI実装
- [ ] **プラグインinit/abi/shutdown**実装
- [ ] **NyashHostVtable**とホスト機能提供
- [ ] **型・メソッドレジストリ**管理
- [ ] テスト: プラグイン初期化・メタデータ取得
#### Day 3: 既存Box統合
- [ ] **既存StringBox/IntegerBox/FutureBoxブリッジ**
- [ ] **NyashBoxRegistry**でハンドル管理
- [ ] **FutureBox用wake経路**実装
- [ ] テスト: 既存Boxとプラグインの統一操作
#### Day 4: FileBoxプラグイン実装
- [ ] **FileBoxプラグイン**（open/read/close）
- [ ] **BID-1フォーマット**での引数・結果処理
- [ ] **エラー処理**完全実装
- [ ] テスト: ファイル操作e2e動作
#### Day 5: 統合テスト・最適化
- [ ] **適合性テスト**（プリミティブ、ハンドル、エラー）
- [ ] **メモリリーク検証**
- [ ] **性能測定**（FFI呼び出しオーバーヘッド）
- [ ] テスト: 全機能統合動作
#### Day 6-7: ドキュメント・CI
- [ ] **使用例とドキュメント**
- [ ] **Linux x86-64 CI設定**
- [ ] **プラグイン開発ガイド**
- [ ] 予備日（問題対応）
## 🛠️ 具体的な実装例
### FileBoxプラグイン例（ChatGPT仕様準拠）
```c
// plugins/nyash-file/src/lib.c
#include "nyash_plugin_api.h"
#include <stdio.h>
#include <stdlib.h>
// ABI版本
u32 nyash_plugin_abi(void) {
return 1; // BID-1対応
}
// メソッドテーブル
static const NyashMethodInfo FILE_METHODS[] = {
{1, "open", 0x12345678}, // open(path: string, mode: string) -> Handle
{2, "read", 0x87654321}, // read(handle: Handle, size: i32) -> Bytes
{3, "close", 0xABCDEF00}, // close(handle: Handle) -> Void
};
// 初期化
i32 nyash_plugin_init(const NyashHostVtable* host, NyashPluginInfo* info) {
info->type_id = 6; // FileBox
info->type_name = "FileBox";
info->method_count = 3;
info->methods = FILE_METHODS;
// ホスト機能保存
g_host = host;
return NYB_SUCCESS;
}
// メソッド実行
i32 nyash_plugin_invoke(u32 type_id, u32 method_id, u32 instance_id,
const u8* args, size_t args_len,
u8* result, size_t* result_len) {
if (type_id != 6) return NYB_E_INVALID_TYPE;
switch (method_id) {
case 1: return file_open(args, args_len, result, result_len);
case 2: return file_read(args, args_len, result, result_len);
case 3: return file_close(args, args_len, result, result_len);
default: return NYB_E_INVALID_METHOD;
}
}
// ファイルオープン実装
static i32 file_open(const u8* args, size_t args_len,
u8* result, size_t* result_len) {
// BID-1 TLV解析
BidTLV* tlv = (BidTLV*)args;
if (tlv->version != 1 || tlv->argc != 2) {
return NYB_E_INVALID_ARGS;
}
// 引数抽出: path, mode
const char* path = extract_string_arg(tlv, 0);
const char* mode = extract_string_arg(tlv, 1);
// ファイルオープン
FILE* fp = fopen(path, mode);
if (!fp) return NYB_E_PLUGIN_ERROR;
// ハンドル生成
u32 handle_id = register_file_handle(fp);
// BID-1結果作成
if (!result) {
*result_len = sizeof(BidTLV) + sizeof(TLVEntry) + 8; // Handle
return NYB_SUCCESS;
}
// Handle{type_id: 6, instance_id: handle_id}をTLVで返す
encode_handle_result(result, 6, handle_id);
return NYB_SUCCESS;
}
```
## ⚠️ リスク対策（ChatGPT指摘）
### 実装時の注意点
1. **ハンドル再利用/ABA**: generation追加で回避
2. **スレッド前提**: シングルスレッド前提を明記
3. **メソッドID衝突**: ビルド時固定で回避
4. **エラー伝播**: トランスポート/ドメインエラー分離
5. **文字列エンコード**: UTF-8必須、内部NUL禁止
### 安全性確保
```rust
// Rust側での安全な実装例
pub struct SafeHandle {
type_id: u32,
instance_id: u32,
generation: u32, // ABA対策
}
impl SafeHandle {
pub fn new(type_id: u32) -> Self {
let instance_id = HANDLE_COUNTER.fetch_add(1, Ordering::SeqCst);
Self { type_id, instance_id, generation: 0 }
}
}
```
## 🚀 期待される成果
### Phase 1完了時
- [ ] **Everything is Box哲学の技術的実現**
- [ ] **既存FutureBox等との完全統合**
- [ ] **効率的なBID-1 TLVフォーマット**
- [ ] **拡張可能なメタデータシステム**
- [ ] **1つのFileBoxプラグインが完全動作**
### 将来への基盤
- [ ] **gRPC/RESTへの明確な拡張パス**
- [ ] **P2P（NyaMesh）統合の技術的基盤**
- [ ] **他言語プラグインへの拡張可能性**
## 📝 最終まとめ
**ChatGPT先生の結論**:
> **箱理論設計は技術的に妥当！**
> **具体的で実装可能な修正案を完全適用**
> **1週間実装の現実性を確認**
> **将来拡張への明確な道筋を提示**
### 成功の鍵
1. **Handle設計のバイナリ化** - 効率性向上
2. **TLV統一フォーマット** - 拡張性確保
3. **メタデータAPI** - プラグイン管理強化
4. **既存Box活用** - 二重実装回避
**結論**: Nyashの独特な哲学を技術的に実現する、最適化された実装計画の完成！
---
**最終確定日**: 2025-08-17
**設計者**: Claude + ChatGPT-5の知恵
**ステータス**: 実装準備完了 🚀
**キーワード**: Everything is Box, Efficient, Extensible, Practical