bid-ffi-v1-actual-specification.md - 主要仕様書
- 実際に動作している実装をベースとした正確な仕様
- FileBoxプラグインで実証済み
- プラグイン開発者はここから始める
../architecture/dynamic-plugin-flow.md - 動的プラグインシステムの全体フロー 🆕
- MIR→VM→Registry→プラグインの動的解決フロー
- コンパイル時決め打ちなし、実行時動的判定の仕組み
- nyash.tomlによる透過的な切り替え
vm-plugin-integration.md - VM統合仕様書 🆕
- VMバックエンドとプラグインシステムの統合
- BoxRef型による統一アーキテクチャ
- パフォーマンス最適化とエラーハンドリング
plugin-tester.md - プラグイン診断ツール
- プラグインの動作確認とデバッグに使用
- tools/plugin-testerツールの使用方法
plugin_lifecycle.md - ライフサイクル/RAII/シングルトン/ログ
- 共有ハンドル、scope終了時の扱い、shutdown_plugins_v2() の動作
- NetPlugin（HTTP/TCP）の並列E2E時の注意点
net-plugin.md - Netプラグイン（HTTP/TCP PoC）
- GET/POST、ヘッダ、Content-Length、環境変数によるログ
returns-result.md - 可選のResultBox正規化
- returns_result = true で成功/失敗を Ok/Err に統一（段階導入推奨）

⚙️ 戻り値のResult化（B案サポート）

nyash.toml のメソッド定義に returns_result = true を付けると、
- 成功: Ok(value) の ResultBox に包んで返す
- 失敗（BID負エラー）: Err(ErrorBox(message)) を返す（例外にはしない）

[libraries."libnyash_example.so".ExampleBox.methods]
dangerousOp = { method_id = 10, returns_result = true }

未指定の場合は従来通り（成功=生値、失敗=例外として伝播）。

filebox-bid-mapping.md - 参考資料
- FileBox APIとプラグイン実装の対応表
- API設計の参考として有用

🔄 Migration & Reference

migration-guide.md - 移行ガイド
- 古いドキュメントから現在の実装への移行方法
- ドキュメント状況の整理

⚠️ Deprecated - 非推奨

ffi-abi-specification.md - ❌ 理想案、未実装
plugin-system.md - ❌ 将来構想
nyash-toml-v2-spec.md - ⚠️ 部分的に古い

🚀 For Plugin Developers

1. Read the Specification

# 主要仕様書を読む
cat docs/説明書/reference/plugin-system/bid-ffi-v1-actual-specification.md

2. Study Working Example

# FileBoxプラグインを参考にする
cd plugins/nyash-filebox-plugin
cat src/lib.rs

3. Configure Your Plugin

# 新スタイル（推奨）: 中央=nyash.toml（レジストリ最小） + 各プラグイン=nyash_box.toml（仕様書）
cat nyash.toml
cat plugins/<your-plugin>/nyash_box.toml

中央の nyash.toml 例（抜粋）

[plugins]
"libnyash_filebox_plugin" = "./plugins/nyash-filebox-plugin"

[plugin_paths]
search_paths = ["./plugins/*/target/release", "./plugins/*/target/debug"]

[box_types]
FileBox = 6

各プラグインの nyash_box.toml 例（抜粋）

[box]
name = "FileBox"
version = "1.0.0"
description = "File I/O operations Box"

[provides]
boxes = ["FileBox"]

[FileBox]
type_id = 6

[FileBox.methods.open]
id = 1
args = [ { name = "path", type = "string" }, { name = "mode", type = "string", default = "r" } ]
returns = { type = "void", error = "string" }

ロード時は nyash_box.toml が優先参照され、OS差（.so/.dll/.dylib、libプリフィックス）は自動吸収されます。従来の [libraries] 設定も当面は後方互換で有効です。

4. Test Your Plugin

# プラグインテスターで確認
cd tools/plugin-tester
cargo build --release
./target/release/plugin-tester check path/to/your/plugin.so

5. nyash_box.toml テンプレ & スモーク 🆕

テンプレート: docs/reference/plugin-system/nyash_box.toml.template
スモーク実行（VM・厳格チェックON）:

bash tools/smoke_plugins.sh

実行内容: Python デモと Integer デモを NYASH_PLUGIN_STRICT=1 で起動し、nyash_box.toml 経路のロードと実行を確認
事前条件: cargo build --release --features cranelift-jit 済み、各プラグインも release ビルド済み

6. プラグイン優先（ビルトイン上書き）設定 🆕

既定では、ビルトインの実装が優先されます（安全第一）。
プラグインで置き換えたい型（ConsoleBox など）がある場合は環境変数で上書き可能:

export NYASH_USE_PLUGIN_BUILTINS=1
export NYASH_PLUGIN_OVERRIDE_TYPES="ArrayBox,MapBox,ConsoleBox"

上記により、new ConsoleBox() などの生成がプラグイン経路に切替わります。
後方互換のため [libraries] にも対象プラグインを登録しておくと、解決の一貫性が高まります。

🔧 For Nyash Core Developers

Implementation Files

plugin_loader_v2.rs - プラグインローダー実装
nyash_toml_v2.rs - 設定パーサー
tlv.rs - TLVエンコーダー/デコーダー

Next Steps

Phase 3: MIR ExternCall → plugin system 接続実装
Future: HTTP系ボックスのプラグイン化

📞 Support & Issues

Working Examples: plugins/nyash-filebox-plugin/
Issues: Report at GitHub Issues
Configuration: nyash.toml in project root

Status: Phase 2 Documentation Reorganization - Completed
Last Updated: 2025-08-20

README.md Unescape Escape

Nyash Plugin System Documentation

🎯 Quick Start

📚 Documentation Index

🟢 Current & Accurate