feat: Major documentation reorganization and unified Box design updates

## Documentation & Organization - Moved copilot_issues.txt → 00_MASTER_ROADMAP.md (phases folder) - Created Phase 9.79b.1 & 9.79b.2 plans for unified Box implementation - Updated unified-box-design-deep-analysis.md with ChatGPT5 insights - Added P2P documentation and examples (ping-pong, self-ping) ## Code Updates - P2PBox: Reverted to original error state for demonstration - VM: Enhanced BoxCall dispatch for unified approach - Updated box factory, interpreter calls, and transport layer ## Cleanup & Privacy - Removed private/ and private_test/ from git tracking - Added private folders to .gitignore for security - Cleaned root directory: moved backups, removed temp files - Moved consultation files to docs/archive/consultations/ ## Other Improvements - Added object literal syntax improvement idea - Updated CLAUDE.md with master roadmap reference - Updated CURRENT_TASK.md with latest progress 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-26 20:30:07 +09:00
parent 22212aa314
commit 6eda81f5db
41 changed files with 1446 additions and 3132 deletions
--- a/docs/development/roadmap/phases/00_MASTER_ROADMAP.md
+++ b/docs/development/roadmap/phases/00_MASTER_ROADMAP.md
@ -0,0 +1,219 @@
+# 🚀 Nyash開発マスタープラン
+
+Status: Active Development  
+Last Updated: 2025-08-26  
+Purpose: Claude×Copilot×ChatGPT協調開発の総合ロードマップ
+
+## 📍 現在位置
+
+- **現在フェーズ**: Phase 8.6 VM性能改善（進行中）
+- **次フェーズ**: Phase 9 JIT実装
+- **詳細タスク**: [CURRENT_TASK.md](../../current/CURRENT_TASK.md)
+
+## 🗺️ フェーズ概要
+
+| Phase | 状態 | 概要 | 詳細リンク |
+|-------|------|------|------------|
+| 8.4 | ✅完了 | AST→MIR Lowering完全実装 | [phase_8_4_ast_mir_lowering.md](phase-8/phase_8_4_ast_mir_lowering.md) |
+| 8.5 | ✅完了 | MIRダイエット（35→26命令） | [phase_8_5_mir_35_to_26_reduction.md](phase-8/phase_8_5_mir_35_to_26_reduction.md) |
+| 8.6 | 🔄進行中 | VM性能改善（0.9倍→2倍以上） | [phase_8_6_vm_performance_improvement.md](phase-8/phase_8_6_vm_performance_improvement.md) |
+| 9 | 📅予定 | JIT実装 | [phase-9/](phase-9/) |
+| 9.75g-0 | ✅完了 | BID-FFI Plugin System | [Phase-9.75g-0-BID-FFI-Developer-Guide.md](phase-9/Phase-9.75g-0-BID-FFI-Developer-Guide.md) |
+| 9.8 | 📅予定 | BIDレジストリ + 自動コード生成 | [phase_9_8_bid_registry_and_codegen.md](phase-9/phase_9_8_bid_registry_and_codegen.md) |
+| 10 | 📅予定 | Cranelift JIT（主経路） | [phase_10_cranelift_jit_backend.md](phase-10/phase_10_cranelift_jit_backend.md) |
+| 11+ | 🔮将来 | LLVM AOT（研究段階） | 後段検討 |
+
+---
+
+## 🎯 Nyash実行モード併用戦略
+
+### 🌟 インタープリター＋コンパイラ併用の価値
+
+#### 実行モード使い分け
+```
+開発時: インタープリター（デバッグ・即時実行・非同期フル対応）
+本番時: インタープリター（Pythonのように実用的）
+        OR
+        WASM/AOT（性能要求時）
+配布時: AOT native（最高性能）
+Web時:  WASM（ブラウザ対応）
+```
+
+#### インタープリターの強み
+- **即時実行**: コンパイル不要で高速開発
+- **デバッグ容易**: 実行時情報の完全把握
+- **非同期完全対応**: Rust async/awaitで真の並行処理
+- **動的性**: 実行時評価・REPL対応
+- **十分な性能**: 多くのユースケースで実用的（Pythonが証明）
+
+---
+
+## 📊 Phase別詳細
+
+### 🚨 Phase 8.6: VM性能改善 - 最優先課題（進行中）
+
+**Summary**:
+- **緊急問題**: VMがインタープリターより0.9倍遅い（性能回帰！）
+- **目標**: 2倍以上高速化でVM実行を実用レベルに引き上げ
+- **担当**: Copilot主導（GitHub Issue #112）
+
+**技術的課題**:
+```bash
+# 現状のベンチマーク結果
+Interpreter: 110.10ms (ベースライン)
+VM:          119.80ms (0.9倍 - 遅い...)
+Target:       55.00ms (2倍高速化目標)
+```
+
+**推定原因と対策**:
+- **デバッグ出力過多**: `println!`による性能劣化
+- **HashMap操作重い**: ValueId → VM値の変換コスト
+- **命令ディスパッチ非効率**: switch文ベースディスパッチ
+
+---
+
+### 🎊 Phase 9.75g-0: BID-FFI Plugin System - 完全完了！ ✅
+
+**革命的成果**: NyashがプラグインでBox型を動的拡張可能に！
+
+```nyash
+// これが現実になった！
+local file = new FileBox()        // プラグイン提供
+local db = new PostgreSQLBox()    // 将来: プラグイン提供  
+local gpu = new CudaBox()         // 将来: プラグイン提供
+```
+
+**References**:
+- [Phase-9.75g-0-BID-FFI-Developer-Guide.md](phase-9/Phase-9.75g-0-BID-FFI-Developer-Guide.md)
+- tools/plugin-tester/ (プラグイン診断ツール)
+
+---
+
+### 📦 Phase 9.8: BIDレジストリ + 自動コード生成ツール
+
+**Summary**:
+- Phase 9.75g-0完了により準備完了
+- BID→各ターゲットのスタブ生成自動化
+
+**革命的価値**:
+```bash
+# 🎯 1つのプラグインが4バックエンド全対応！
+nyash bid gen --target wasm   bid.yaml  # WASM用import生成
+nyash bid gen --target vm     bid.yaml  # VM用関数テーブル生成  
+nyash bid gen --target llvm   bid.yaml  # AOT用declare生成（LLVM実装時）
+```
+
+---
+
+### 🏆 Phase 10: Cranelift JIT（主経路）
+
+**Summary**:
+- MIR→VMを維持しつつ、ホットパスをCraneliftでJIT化
+- 目標: VM比2倍以上の高速化
+- LLVM AOTは設計資産は維持しつつ、Phase 11以降に検討
+
+**Start Gate（着手前の必須完了）**:
+- ✅ MIRダイエット（26命令）整合完了
+- ✅ VM統計: `--vm-stats` でホット関数抽出可能
+- 🔄 Proof of Concept: MIR→CLIFの最小Lower
+- ❓ BoxCall/Array/MapのJIT最適化
+
+**実装ステップ**:
+1. **Phase 10.1**: Proof of Concept（2週間）
+2. **Phase 10.2**: 基本実装（4週間）
+3. **Phase 10.3**: 非同期の扱い（最小）
+
+---
+
+## 🧠 AI大会議から得られた技術的知見
+
+### Gemini先生の助言
+- ✅ エスケープ解析・ボックス化解除が性能の鍵  
+- ✅ wasmtime compileは短期的に実用的
+- ✅ WASM実行は確実に高速（13.5倍実証済み）
+- 🔄 Cranelift → LLVM段階的アプローチ
+
+### codex先生の助言
+- ✅ MIR前倒し実装推奨（全バックエンドが恩恵）
+- ✅ wasmtime互換性管理が重要
+- ✅ CPU差異対応 (baseline/v3二段ビルド)
+- ✅ 起動時間・割当削減・配布体験がKPI
+
+### Claude統合分析
+- ✅ 実用価値最大化: WASM+AOTで十分な競争力
+- ✅ 開発効率: Cranelift JITの恩恵限定的
+- ✅ Everything is Box最適化が差別化の核心
+- ✅ 時間効率: 2-3ヶ月節約でLLVM集中投資
+
+---
+
+## 💡 協調開発への具体的お願い
+
+### 🔧 Phase 8.6 VM性能改善（最優先）
+- ❓ 命令ディスパッチのボトルネック特定方法は？
+- ❓ HashMap操作の最適化戦略は？  
+- ❓ デバッグ出力削除による性能改善測定は？
+- ❓ Direct threading実装の現実的アプローチは？
+
+### 🚀 長期戦略相談
+- ❓ インタープリターとコンパイラの互換性保証は？
+- ❓ MIR→LLVM IR変換の基本的な実装戦略は？
+- ❓ Box型のLLVM表現として最適なアプローチは？
+- ❓ エスケープ解析によるスタック化判定は？
+
+---
+
+## 📊 進捗管理・コミュニケーション
+
+### 🤝 協調開発ルール
+- ✅ 大きな変更前にはdocs/CURRENT_TASK.mdで情報共有
+- ✅ ベンチマーク機能は最優先で維持
+- ✅ 競合発生時は機能優先度で解決
+
+### 品質保証
+- ✅ cargo check でビルドエラーなし
+- ✅ 既存ベンチマークが regression なし
+- ✅ 新機能のドキュメント整備
+- ✅ テストケース追加・CI通過
+
+---
+
+## 🎯 期待される成果
+
+### 達成済み
+- 🏆 RefNew/RefGet/RefSet WASM完全動作
+- 🏆 26命令MIR階層化完了（Phase 8.5）
+- 🏆 Phase 9.75g-0 BID-FFI Plugin System完全完了
+- 🏆 警告削減100%達成（Phase 9.75j）
+
+### 進行中・予定
+- 🔄 VM性能改善進行中（Phase 8.6）- GitHub Issue #112
+- 📅 Cranelift JIT（Phase 10）: VM比2×以上の高速化
+- 📅 非同期ネイティブ実装: async/await完全対応
+- 📅 インタープリター併用: 開発・本番両対応
+
+---
+
+## 📞 連絡・相談方法
+
+技術的相談や進捗報告は、以下の方法でお気軽にどうぞ：
+
+1. 📝 GitHub Issues・Pull Request
+2. 📋 docs/CURRENT_TASK.md コメント
+3. 🤖 AI大会議 (重要な技術決定)
+4. 💬 コミットメッセージでの進捗共有
+
+どんな小さなことでも相談大歓迎です！
+一緒にNyashを最高の言語にしていきましょう🚀
+
+---
+
+**最終更新**: 2025-08-26 (copilot_issues.txt統合・Markdown化)  
+**作成者**: Claude (ファイル統合・構造整理)
+
+### 🎯 重要な変更点
+- ✅ **Phase 9.75g-0 BID-FFI Plugin System完全完了**
+- 🔄 **Phase 8.6 VM性能改善を最優先** (進行中)
+- 📦 **Phase 9.8 BIDレジストリ** (Phase 8.6完了後の次期重点)
+- 🔍 **Phase 10 Cranelift JIT** (主経路として確定)
+- 🌟 **統一ロードマップ化** (phasesフォルダに集約)
--- a/docs/development/roadmap/phases/phase-9/phase_9_79a_unified_box_dispatch_and_p2p_polish.md
+++ b/docs/development/roadmap/phases/phase-9/phase_9_79a_unified_box_dispatch_and_p2p_polish.md
@ -1,6 +1,6 @@
 # Phase 9.79a: Unified Box Dispatch (Minimal) + P2PBox Polish

-Status: Planned
+Status: Completed
 Last Updated: 2025-08-26
 Owner: core-runtime

@ -37,6 +37,7 @@ Owner: core-runtime
  - VM: universal methods 前置ディスパッチ
  - Interpreter: 同様の前置ディスパッチ
  - スモーク：既存演算子/print動作の回帰なし
+  - 進捗: 2025-08-26 達成（VM/Interpreterともに toString/type/equals/clone を前段で統一。cargo build 成功）
 - M2（Day 3–4）
  - P2PBox unregister安全化（endpoint一致 or refcount）
  - E2E: onOnce/off 追加、two-node ping-pong 安定、asyncデモが確実に出力
@ -44,6 +45,26 @@ Owner: core-runtime
  - VM表示整合：P2PヘルパのtoString/ConsoleをInterpreterと一致
  - Docs更新：言語ガイド/P2Pリファレンス反映

+## Completion Notes (2025-08-26)
+- Universal dispatch (toString/type/equals/clone): Interpreter/VMに前段実装・整合確認済み。
+- P2PBox Polish:
+  - InProcess unregister: endpoint一致時のみunregisterで安全化。
+  - E2E: onOnce/off ユニットテスト追加、two-node ping→pong スモーク、self→selfスモーク追加。
+  - 受信トレース: getLastFrom/getLastIntentName を受信時に更新。
+  - 実用ミニ糖衣: IntentBoxの第2引数に MapBox/JSONBox を直接渡せるよう拡張。
+- Docs: 新規リファレンス追加（P2P）/ 例追加
+  - docs/reference/boxes-system/p2p_box.md
+  - examples/p2p_self_ping.nyash
+  - examples/p2p_ping_pong.nyash
+
+Notes:
+- 非WASM環境のTimerBoxはダミーのため、async出力の確実化はWASM側のガイドで扱う。ネイティブでは同期スモーク（self→self/二者）で安定確認。
+
+## Next (roll-forward)
+- Language sugar: Object literal → MapBox lowering（feature flag `object_literal`で段階導入）
+  - Proposal: docs/ideas/improvements/2025-08-26-object-literal-sugar.md
+- WASMガイドにTimer併用のasyncサンプル追記。
+
 ## リスクと対策
 - VM分岐に触るリスク → 型別分岐の“前段”に追加、既存分岐はフォールバックとして維持
 - unregister回りの退行 → 一致解除テスト/順次Dropテスト（clone/share/Drop順の組み合わせ）を追加
--- a/docs/development/roadmap/phases/phase-9/phase_9_79b_1_unified_registry_ids_and_builder_slotting.md
+++ b/docs/development/roadmap/phases/phase-9/phase_9_79b_1_unified_registry_ids_and_builder_slotting.md
@ -0,0 +1,49 @@
+# Phase 9.79b.1: Unified Registry IDs + Builder Slotting
+
+Status: Planned
+Owner: core-runtime
+Target: Before Phase 10 (Cranelift JIT)
+Last Updated: 2025-08-26
+
+## Goals
+- Introduce `BoxTypeId`/`MethodId` and stable method slot reservation in the unified registry.
+- Resolve method names to slot IDs at MIR builder time when possible.
+- Keep MIR instruction set stable (26) while enabling ID-based BoxCall.
+
+## Scope
+- Registry
+  - Add numeric `BoxTypeId` mapping (type-name → id) and `(type_id, method)` → `slot` table.
+  - Reserve low slots for universal methods: `0=toString`, `1=type`, `2=equals`, `3=clone`.
+  - Provide `reserve_method_slot()`, `resolve_slot()` APIs.
+- MIR Builder
+  - When receiver type can be inferred, emit `BoxCall { method_id }` (slot ID) instead of name.
+  - Add late-bind fallback path for unresolved sites (keeps current behavior).
+- Debug scaffolding
+  - Add `MIRDebugInfo` container types (empty by default) for ID→name mapping (off by default).
+- Docs
+  - Update MIR design note to mention ID-based BoxCall with late-bind fallback.
+
+## Deliverables
+- New IDs and slot APIs in registry
+- Builder emits `method_id` when resolvable
+- Unit tests for slot reservation and universal slot invariants
+
+## Non-Goals
+- VM vtable/thunk dispatch (handled in 9.79b.2)
+- PIC/JIT codegen
+
+## Risks & Mitigations
+- Slot consistency with inheritance: document rule “override keeps parent slot”; add test.
+- Partial resolvability: ensure late-bind remains correct and does not regress semantics.
+
+## Timeline
+- 1–2 days
+
+## Acceptance Criteria
+- Tests pass; builder prints BoxCall with numeric `method_id` for resolvable sites.
+- Universal methods occupy reserved slots across all types.
+- No change to MIR opcode count (26) and existing dumps remain valid except for `method_id` where applicable.
+
+## Roll-forward
+- Proceed to 9.79b.2 (VM vtable/thunk + mono-PIC).
+
--- a/docs/development/roadmap/phases/phase-9/phase_9_79b_2_vm_vtable_thunks_and_pic.md
+++ b/docs/development/roadmap/phases/phase-9/phase_9_79b_2_vm_vtable_thunks_and_pic.md
@ -0,0 +1,51 @@
+# Phase 9.79b.2: VM VTable Thunks + Mono-PIC
+
+Status: Planned
+Owner: core-runtime
+Target: Before Phase 10 (Cranelift JIT)
+Last Updated: 2025-08-26
+
+## Goals
+- Implement unified VM BoxCall path via vtable thunks indexed by `MethodId`.
+- Add monomorphic inline cache (PIC) at call sites; prepare for polymorphic expansion.
+- Keep behavior identical; improve structure and enable JIT lowering.
+
+## Scope
+- VM Dispatch
+  - Add `TypeMeta` with `vtable_base`, `version`.
+  - `execute_boxcall(receiver, method_id, args)`: lookup thunk = `vtable[slot]` and call target.
+- PIC (Monomorphic)
+  - Per call-site cache: `(type_id, version) → target` fast path with fallback.
+  - Counters for hit/miss (debug only) to validate performance wins.
+- Plugin safety (stub)
+  - Provide thunk replacement and type `version++` API (actual unload handled later with plugin mgr).
+- Tests
+  - BoxCall correctness across builtin/user/plugin (plugin mocked if needed).
+  - PIC hit on repeated calls; miss on version change.
+- Docs
+  - Update VM README with unified path and PIC diagram.
+
+## Deliverables
+- Unified VM BoxCall path (vtable + thunk)
+- Monomorphic PIC
+- Test coverage for core scenarios
+
+## Non-Goals
+- Polymorphic PIC (plan only)
+- JIT emission (Phase 10)
+
+## Risks & Mitigations
+- Thunk ABI uniformity: define single target signature usable by builtin/VM/plugin shims.
+- Cache invalidation: bump `version` on thunk replacement; verify miss logic.
+
+## Timeline
+- 2–3 days
+
+## Acceptance Criteria
+- All existing tests pass; new VM dispatch tests pass.
+- Measurable hit rate on hot call-sites in debug stats.
+- No observable behavior change from user code perspective.
+
+## Roll-forward
+- Phase 10: Cranelift JIT lowers BoxCall to the same thunks; add poly-PIC and codegen stubs.
+