hakorune/docs/reference/plugin-system/nyash-toml-v2_1-spec.md

nyash.toml v2.1 拡張仕様（最小）

目的: プラグインBoxのメソッド引数として、他のBoxを不透明参照（BoxRef）で安全に受け渡す。

変更点（v2 → v2.1）

• メソッド引数型に kind = "box" を追加（当面は category = "plugin" のみ）
• TLVに BoxRef（Handle）を追加（tag = 8）
  • payload: type_id: u32 (LE), instance_id: u32 (LE)（合計8バイト）
• 既存タグは不変：1=Int64, 2=String(UTF-8), 3=Bool

例: libraries セクション

[libraries]
[libraries."libnyash_filebox_plugin.so"]
boxes = ["FileBox"]
path = "./target/release/libnyash_filebox_plugin.so"

[libraries."libnyash_filebox_plugin.so".FileBox]
type_id = 6
abi_version = 1

[libraries."libnyash_filebox_plugin.so".FileBox.methods]
# 既存
birth = { method_id = 0 }
open  = { method_id = 1 }
close = { method_id = 4 }

# 追加例: Box引数を1つ受け取る
copyFrom = { method_id = 7, args = [ { kind = "box", category = "plugin" } ] }

備考:

• args を省略した場合は引数なし（ゼロ引数）とみなす（v2互換）
• 複数引数は配列で列挙（例: 2引数なら2要素）
• ユーザー定義Boxや複雑なビルトインBoxは当面対象外（将来のvtable/retain-release設計で拡張）

呼び出し時のTLVエンコード

• 先頭ヘッダ [ver:1, argc:1, rsv:2] の後、各引数を tag + payload で列挙
• tag=8 (Handle/BoxRef): payload = type_id(4) + instance_id(4) （LE）
• 未対応Box種別に対してはエラーを返す（開発時のみ toString フォールバックを許容可能）

戻り値（v2.1→v2.2）

• v2.1: Int/String/Bool（1/6/3）とVoid(9)
• v2.2: BoxRef(Handle, tag=8) の「返り値」対応を追加（同一/別Box型どちらも可）
  • payload: type_id:u32 + instance_id:u32
  • Loaderは type_id から lib_name/box_name を逆引きし、PluginBoxV2 を生成して返す

互換性

• args 宣言がない既存v2設定はそのまま利用可
• BoxRefを使わないメソッドは従来通り Int/String/Bool のみで動作

実装メモ（参考）

• Loader: invoke時の引数エンコードに tag=4 を追加（category=plugin のみ）
• プラグイン側: 受領した type_id と期待型を照合し、不一致ならエラー
• 所有権: 呼び出し中の一時借用（保持は将来の retain/release で対応）