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

Phase 11-12: LLVM backend initial, semantics layer, plugin unification

Browse Source 
Major changes:
- LLVM backend initial implementation (compiler.rs, llvm mode)
- Semantics layer integration in interpreter (operators.rs)
- Phase 12 plugin architecture revision (3-layer system)
- Builtin box removal preparation
- MIR instruction set documentation (26→Core-15 migration)
- Cross-backend testing infrastructure
- Await/nowait syntax support

New features:
- LLVM AOT compilation support (--backend llvm)
- Semantics layer for interpreter→VM flow
- Tri-backend smoke tests
- Plugin-only registry mode

Bug fixes:
- Interpreter plugin box arithmetic operations
- Branch test returns incorrect values

Documentation:
- Phase 12 README.md updated with new plugin architecture
- Removed obsolete NYIR proposals
- Added LLVM test programs documentation

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Moe Charm
2025-09-01 23:44:34 +09:00
parent fff9749f47
commit 11506cee3b
196 changed files with 10955 additions and 380 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/development/proposals/mir_reduction_detailed_analysis.md
View File

@ -1,10 +1,11 @@
# MIR 35→26命令削減: 詳細分析・移行戦略
# MIR 35→26→15命令削減: 詳細分析・移行戦略
*実装ベース完全マッピング - 2025年8月17日版*
*実装ベース完全マッピング - 2025年8月17日版*
**注意**: このドキュメントは35→26命令への移行計画を記録しています。現在はさらに15命令に削減済みです。
## 🔍 **現在実装35命令 vs ChatGPT5仕様26命令の完全マッピング**
## 🔍 **過去の実装35命令 vs 26命令仕様の完全マッピング（歴史的記録）**
### **維持する命令 (既存実装 → 26命令仕様)**
### **維持する命令 (35命令実装 → 26命令仕様への移行計画）**
| 現在実装 | 26命令仕様 | 効果 | 変更 |
|----------|------------|------|------|

10
docs/development/proposals/nyir/README.md
View File

@ -1,10 +0,0 @@
# NyIR ドキュメント索引
- 仕様（骨子）: `spec.md`
- フェーズ計画（Phase 9.10）: `../予定/native-plan/issues/phase_9_10_nyir_spec.md`
- BIDサンプル: `bid_samples/`（console.yaml / canvas.yaml）
- 計画全体（Copilot用フルテキスト 9.7以降）: `../予定/native-plan/copilot_issues.txt`
- 関連: ABI/BIDドラフトは `../予定/native-plan/box_ffi_abi.md`
補足:
- NyIR Core（25命令）は凍結。拡張は NyIR-Ext（exceptions/concurrency/atomics）で段階導入。

26
docs/development/proposals/nyir/bid_samples/canvas.yaml
View File

@ -1,26 +0,0 @@
version: 0
interfaces:
- name: env.canvas
box: Canvas
methods:
- name: fillRect
params:
- { string: canvas_id }
- { i32: x }
- { i32: y }
- { i32: w }
- { i32: h }
- { string: color }
returns: void
effect: io
- name: fillText
params:
- { string: canvas_id }
- { string: text }
- { i32: x }
- { i32: y }
- { string: font }
- { string: color }
returns: void
effect: io

10
docs/development/proposals/nyir/bid_samples/console.yaml
View File

@ -1,10 +0,0 @@
version: 0
interfaces:
- name: env.console
box: Console
methods:
- name: log
params:
- { string: msg }
returns: void
effect: io

70
docs/development/proposals/nyir/phase_9_10_nyir_spec.md
View File

@ -1,70 +0,0 @@
# Phase 9.10: NyIR v1 仕様・フォーマット・検証器（公開IRの確立）
目的
- NyashのMIRを公開IR（NyIR v1）として凍結し、あらゆるフロントエンド/バックエンドの共通契約とする。
- 仕様・テキスト/バイナリフォーマット・厳格検証器・ツール群を整備し、移植性と一貫性を保証する。
成果物（Deliverables）
- 仕様書: `docs/nyir.md`（命令仕様/効果/未定義なし/検証ルール/等価変換指針）
- フォーマット: `.nyir`（テキスト）, `.nybc`（バイナリ）
- 検証器: `nyir-verify`（CLI/ライブラリ）
- 変換/実行ツール:
- `nyashel -S`（Nyash→NyIRダンプ）
- `nyir-run`（NyIRインタプリタ）
- 参考: `nyir-ll`（NyIR→LLVM IR、Phase 10で拡張）
- Golden NyIR: `golden/*.nyir`（代表サンプルを固定、CIで全バックエンド一致を検証）
仕様の要点（NyIR v1）
- 命令セット: 25命令（Tier-0/1/2）を凍結
- Tier-0: Const, BinOp, Compare, Branch, Jump, Phi, Call, Return
- Tier-1: NewBox, BoxFieldLoad, BoxFieldStore, BoxCall, Safepoint, RefGet, RefSet, WeakNew, WeakLoad, WeakCheck, Send, Recv
- Tier-2: TailCall, Adopt, Release, MemCopy, AtomicFence
- 効果（Effects）: pure / mut / io / control（再順序化規則を明文化）
- 所有フォレスト: 強参照の森（strong in-degree ≤ 1）、強循環禁止、weakは非伝播
- Weak: 失効時の挙動を決定（WeakLoad=null / WeakCheck=false）、世代タグ設計を想定
- Bus: ローカルは順序保証、リモートは at-least-once（または選択可能）
- 未定義動作なし: 各命令の事前条件/失敗時挙動を明示
- バージョニング: `nyir{major.minor}`、featureビットで拡張告知
テキスト形式（.nyir）
- 人間可読・差分レビュー向け
- 構造: moduleヘッダ / const pool / functions（blocks, instrs）
- コメント/メタデータ/featureビットを扱える簡潔な構文
バイナリ形式（.nybc）
- セクション化: header / features / const pool / functions / metadata
- エンコード: LEB128等の可変長を採用、識別子はstring table参照
- 将来の後方互換に備えた保守的設計
検証器（Verifier）
- 検査: 所有森/強循環/weak規則/効果整合/到達性/終端性/Phi入力整合
- 失敗時は明確なエラーを返し、ロード拒否
- CLI/ライブラリの二態（コンパイラ/実行系どちらからも利用）
Golden / Differential テスト
- `golden/*.nyir` を固定し、interp/vm/wasm/jit/llvm（順次）で出力一致をCIで検証
- 弱失効/分割fini/境界条件系を重点的に含める
タスク（Copilot TODO）
1) 仕様スケルトン: `docs/nyir.md` ひな形生成（命令/効果/検証/等価変換の目次）
2) `.nyir` パーサ/プリンタ（最小）
3) `.nybc` エンコーダ/デコーダ（最小）
4) `nyir-verify`（所有森/効果/Phi/到達/終端の基本チェック）
5) `nyashel -S` をNyIR出力対応に（既存MIRダンプ経路から移行）
6) Goldenサンプル作成（3〜5本）＋CIワークフロー雛形
受け入れ基準（Acceptance）
- 代表サンプルが `.nyir` で表現・検証・実行可能（`nyir-run`）
- `.nybc` 読み書き往復で等価
- CIでinterp/vm/wasmの結果一致（最小ケース）
依存/関連
- 8.5: 25命令の確定仕様
- 9.7: ExternCall/ABI（NyIRにもmethodノードor外部呼を表現）。v1ではExternCallは拡張セクションで可
- 10.x: NyIR→LLVM IR（別Phase）
リスク
- 仕様凍結の硬直化 → 拡張はfeatureビット＋拡張セクションへ
- 実装の重複 → Verifier/フォーマットは共有ライブラリ化
最終更新: 2025-08-14

126
docs/development/proposals/nyir/spec.md
View File

@ -1,126 +0,0 @@
# NyIR v1 Specification (Draft Skeleton)
Purpose
- Define NyIR (public intermediate representation) as the portable contract for all frontends/backends.
- Freeze the 25-instruction set, effects, ownership forest, weak semantics, and bus contract.
Status
- Version: nyir1.0 (draft)
- Change policy: backward-compatible extensions via feature bits; no undefined behavior.
1. Instruction Set (26) — Semantic Summary
- Tier-0: Const, BinOp, Compare, Branch, Jump, Phi, Call, Return
- Tier-1: NewBox, BoxFieldLoad, BoxFieldStore, BoxCall, ExternCall, Safepoint, RefGet, RefSet, WeakNew, WeakLoad, WeakCheck, Send, Recv
- Tier-2: TailCall, Adopt, Release, MemCopy, AtomicFence
For each instruction (to be filled):
- Semantics: preconditions, side-effects, failure behavior
- Effects: pure/mut/io/control
- Verification: structural/formal checks
- Example: minimal snippet
2. Effects Model
- pure: no observable side effects; can reorder with pure
- mut: mutates owned state; preserve order per resource
- io: interacts with outside world; preserve program order
- control: affects control flow/terminators
3. Ownership Forest
- Strong edges form a forest (strong in-degree ≤ 1).
- No strong cycles.
- Weak edges do not propagate ownership.
- Adopt/Release rules; Safepoint and split-fini notes.
4. Weak Semantics
- Representation: {ptr, generation}
- WeakLoad: returns null if generation mismatch
- WeakCheck: returns false if invalid
- O(1) on-access validation
5. Bus Contract
- Local: in-order delivery
- Remote: at-least-once (or selectable); specify ordering/dup policy
6. Formats
- Text .nyir: human-readable; module header, features, const pool, functions (blocks, instrs)
- Binary .nybc: sectioned; header, features, const pool, functions, metadata; varint encodings
- Feature bits and extension sections for evolution
7. Verification
- Program well-formedness: reachability, termination, dominance
- Phi input consistency
- Effects ordering constraints
- Ownership forest & weak/generation rules
- Bus safety checks
8. External Calls (Core)
- ExternCall: Interface to external libraries as Everything is Box principle
- Format: ExternCall { dst, iface_name, method_name, args }
- Effect annotation required (pure/mut/io/control)
- BID (Box Interface Definition) provides external API contracts
9. Mapping Guidelines
- WASM: imports, memory rules, (ptr,len) strings
- VM: function table mapping
- LLVM: declare signatures; effect to attributes (readonly/readnone, etc.)
10. Golden/Differential Testing
- Golden .nyir corpus; cross-backend consistency (interp/vm/wasm/llvm)
11. Versioning & Compatibility
- nyir{major.minor}; feature negotiation and safe fallback
12. Glossary
- Box, Effect, Ownership forest, Weak, Safepoint, Bus, Feature bit
Appendix
- Minimal examples (to be added)
- Rationale notes
------------------------------------------------------------
NyIR-Ext（拡張セット）
------------------------------------------------------------
目的
- NyIR Core（26命令）は基本セマンティクス凍結。外部世界接続（ExternCall）を含む基本機能確立。
- 拡張は言語固有機能に限定：「例外」「軽量並行/非同期」「アトミック」の3領域を段階追加。
- Core機能: すべての言語で必要な基本セマンティクス（制御フロー・Box操作・外部呼び出し）
- Extension機能: 特定言語でのみ必要な高級機能（例外処理・並行処理・アトミック操作）
Ext-1: 例外/アンワインド（exceptions）
- 命令（案）：
- Throw(value)
- TryBegin
- TryEnd(handlers=[type:block])
- 効果: control（脱出）。mut/io と混在する場合は当該効果も従属。
- 検証: Try の整合（入れ子/終端）、未捕捉 Throw のスコープ明示、no-throw 関数属性の尊重。
- バックエンド指針:
- LLVM: 言語EH or setjmp/longjmp 系へ lower
- WASM: v0は例外未使用なら「エラー戻り値」へ降格（no-exception モード）
Ext-2: 軽量並行/非同期（concurrency）
- 命令（案）：
- Spawn(fn, args...)
- Join(handle)
- Await(task|event) // または Wait
- 効果: io（スケジューラ相互作用）＋ control（待機・解除）。
- 検証: Join/Spawn のライフサイクル均衡、待機の整合（任意でデッドロック静的ヒント）。
- バックエンド指針:
- LLVM: pthread/std::thread/独自ランタイム
- WASM: スレッド未使用ならランループ/Promise/MessageChannel 等で近似
Ext-3: アトミック（atomics）
- 命令（案）：
- AtomicRmw(op, addr, val, ordering=seq_cst)
- CAS(addr, expect, replace, ordering=seq_cst)
- 既存の AtomicFence は維持。
- 効果: mut（アトミック副作用）。必要に応じて atomic/volatile フラグを effect/属性で付与。
- バックエンド指針:
- LLVM: `atomicrmw`, `cmpxchg`
- WASM: Threads 提案が前提。未サポート環境では未実装 or 疑似ロック（デモ用途）
備考
- 可変引数は slice 表現で代替（IR 追加不要）。
- クロージャ捕捉は Box + env フィールド + BoxCall で表現（IR 追加不要）。
- 動的言語（辞書/配列/プロトタイプ）は標準Box（std）で受ける（IR 追加不要）。
- 関数属性に「エラー戻り値モード/no-exception」などのメタを付与し、例外禁止環境へも対応する。

44
docs/development/proposals/nyir/vision_universal_exchange.md
View File

@ -1,44 +0,0 @@
# NyIR を共通交換フォーマットにする計画（All Languages → NyIR → All Targets）
目的（Goal）
- あらゆる言語のプログラムを NyIR（= Nyash MIR の公開版）へ落とし、そこから任意の実行形態（WASM/LLVM/VM/他言語）に変換する。
- 最適化は二の次。まずは意味保存（semantics-preserving）を最優先で実現し、可搬性と一貫性を担保する。
中核方針（Core Policy）
- NyIR Core（26命令）は基本セマンティクス凍結。ExternCallによる外部世界接続を含む。
- 拡張は NyIR-Ext（exceptions/concurrency/atomics）で言語固有機能を段階導入。
- Everything is Box哲学: 外部ライブラリもBIDによりBox統一インターフェースで利用。
- 仕様の正本は `docs/nyir/spec.md` に集約（Core＋Ext）。
必要拡張（Minimal Additions）
- 例外/アンワインド（Throw/TryBegin/TryEnd）
- 軽量並行/非同期（Spawn/Join/Await）
- アトミック（AtomicRmw/CAS + ordering）
→ 詳細は `docs/nyir/spec.md` の NyIR-Ext 参照
フロントエンド指針（Language → NyIR）
- C/C++/Rust: 既存IR（LLVM IR）経由または専用パーサでサブセットから対応
- 例外→NyIR-Ext exceptions or エラー戻り値
- スレッド→Spawn/Join、atomic→CAS/RMW
- Java/Kotlin: JVM bytecode から構造復元→NyIR（例外/スレッド/同期をExtへ）
- Python/JS/TS: AST→NyIR。辞書/配列/プロトタイプは標準Boxへ写像、例外/非同期はExtへ
- Go: panic/recover→exceptions、goroutine→Spawn/Join へ写像（将来）
バックエンド指針（NyIR → Target）
- WASM: 同期・非例外・非スレッドの最小路線から段階対応（Exceptions/Threads提案に合わせ拡張）
- LLVM: 例外/スレッド/アトミックが揃っているため先行実装が容易
- VM: 仕様の正しさ検証の基準（簡易実装でも良い）
- 他言語（ソース生成）: 可読性/慣用性は課題だが、機械的変換は可能（優先度低）
検証計画（Golden/Diff）
- Cサブセット→NyIR→C/WASM（例外なし・CASあり）
- Python/JSサブセット→NyIR→WASM（辞書/例外/非同期のサブセット）
- JVM系→NyIR→JVM bytecode（例外/スレッド）
- Rustサブセット→NyIR→LLVM（所有・weakの温存）
→ Golden NyIR を用い、interp/vm/wasm/llvm で出力一致をCI検証
関連リンク
- NyIR 仕様: `spec.md`
- ABI/BID: `../予定/native-plan/box_ffi_abi.md`
- 9.10 タスク（Copilot向け）: `../予定/native-plan/issues/phase_9_10_nyir_spec.md`

6
docs/development/roadmap/phases/00_MASTER_ROADMAP.md
View File

@ -15,7 +15,7 @@ Purpose: Claude×Copilot×ChatGPT協調開発の総合ロードマップ
| 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.5 | ✅完了 | MIRダイエット（35→26→15命令） | [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) |
@ -114,7 +114,7 @@ nyash bid gen --target llvm bid.yaml # AOT用declare生成（LLVM実装時）
- **🌟 NEW: GC切り替え可能ランタイム（世界初の柔軟なメモリ管理）**
**Start Gate（着手前の必須完了）**:
- ✅ MIRダイエット（26命令）整合完了
- ✅ MIRダイエット（15命令）整合完了
- ✅ VM統計: `--vm-stats` でホット関数抽出可能
- 🔄 Proof of Concept: MIR→CLIFの最小Lower
- ❓ BoxCall/Array/MapのJIT最適化
@ -185,7 +185,7 @@ nyash bid gen --target llvm bid.yaml # AOT用declare生成（LLVM実装時）
### 達成済み
- 🏆 RefNew/RefGet/RefSet WASM完全動作
- 🏆 26命令MIR階層化完了（Phase 8.5）
- 🏆 MIR命令削減完了（35→26→15命令、Phase 8.5）
- 🏆 Phase 9.75g-0 BID-FFI Plugin System完全完了
- 🏆 警告削減100%達成（Phase 9.75j）

41
docs/development/roadmap/phases/phase-11.7_jit_complete/CURRENT_TASK.md Normal file
View File

@ -0,0 +1,41 @@
# CURRENT TASK – Phase 11.7（JIT Complete / Semantics Layer）
Focus Window: Semantics導入＋jit-direct安定化の確定報告 → GC/Sync/非同期のJIT降下着手
合意事項（要約）
- LLVM AOT は一旦クローズ。Windows 依存と重量を回避し、Cranelift に集中。
- 単一意味論層（Semantics）を導入し、Nyashスクリプト/VM/JIT(exe)を同一動作に揃える。
- VM は参照実装。JIT は実行/生成を担い、VM→JITのランタイムフォールバックは行わない。
現状ステータス（2025-09-01）
- jit-direct 分岐/PHI 合流：単一出口＋BlockParam合流で安定化を確認。
- テスト: `mir-branch-ret`, `mir-phi-min`, `mir-branch-multi`, `mir-nested-branch`, `mir-phi-two` で VM/JIT 一致（tag=201/200 一致）。
- Semantics 層：`src/semantics/{mod.rs, eval.rs}` にトレイトとPoCインタプリタの骨組みを追加済（未配線）。
- C ABI（NyRT）：`crates/nyrt` の `libnyrt.a` に必要シンボル実装済（console/array/string/plugin_invoke/checkpoint/gc_barrier 等）。
- VM 側：Safepoint/書込バリア/簡易スケジューラ（SingleThread）連携は稼働。
- JIT 側：Safepoint/バリア/await はまだスタブまたは未emit（要降下）。
直近タスク（このフェーズでやること）
1) Semantics 実用化配線（VM/JITの動作一致の“芯”）
- `SemanticsVM`（VM実行での実装）と `SemanticsClif`（LowerCore+IRBuilder委譲）を用意。
- `semantics::MirInterpreter` で両者を同一MIRへ適用し、差分検出の土台を作る。
2) JIT へ GC/Sync/非同期の降下
- Safepoint: `I::Safepoint` を `nyash.rt.checkpoint` emit。`nyrt` 側で `gc.safepoint()` と `scheduler.poll()` に橋渡し。
- Write Barrier: Array/Map の set/push 等をlowerする箇所で `nyash.gc.barrier_write` を emit（CountingGc で検証）。
- Await: PoC として FutureBox の同期 get にlower（動作一致優先）。
3) パリティ検証
- `NYASH_GC_COUNTING=1` で VM/JIT ともに safepoint/barrier カウントが増えることを確認。
- 既存 smokes（分岐/PHI/配列/外部呼び出し）で一致を継続監視。
実行メモ
- Build（JIT）: `cargo build --release --features cranelift-jit`
- jit-direct: `NYASH_JIT_THRESHOLD=1 ./target/release/nyash --jit-direct <app>`
- 追跡: `NYASH_JIT_TRACE_RET/SEL/BLOCKS=1`、GC: `NYASH_GC_COUNTING=1`（必要時）
備考
- LLVM AOT のドキュメント/ツールは維持するが、Windows 前提の依存導入は行わない。Cranelift で“がっちり作る”。

46
docs/development/roadmap/phases/phase-11.7_jit_complete/MEETING_NOTES.md Normal file
View File

@ -0,0 +1,46 @@
# Design Notes – Phase 11.7 JIT Complete (Meeting Summary)
Date: 2025-09-01
Key Decisions
- Single Semantics Source: Introduce a MIR semantics layer (trait) as the single source of truth. All backends (VM/Cranelift/LLVM/WASM) implement this interface.
- No Runtime Fallback: Remove VM→JIT fallback complexity. VM becomes the reference executor; codegen backends handle execution/AOT. JIT is compile-only/AOT‑assist when needed.
- Handle‑First ABI: Unify handle/i64/ptr conversions, tag classification, concat/extern/boxcall via shared helpers; call into NyRT shims from backends.
- GC Hooks: Insert sync barriers and async safepoints as MIR‑level hooks that each backend lowers appropriately.
- Backends Roadmap: LLVM AOT は一旦アーカイブ。Cranelift を主線（JIT/軽量AOT）とし、WASM は同一セマンティクスで後段。Windows DX を軽く保つ。
Architecture Sketch
- MIR → Semantics<E>
- VmSem: executes values (reference)
- ClifSem: builds Cranelift IR (JIT/AOT)
- LlvmSem: builds LLVM IR (AOT)
- WasmSem: builds Wasm (future)
- Shared ABI utilities: handle↔i64/ptr, to_bool, compare, tags, invoke variants, NyRT shims.
Implementation Plan (Progressive)
- Phase 1: Skeleton + minimal lowering (Const/Return/Add) → echo-lite returns 0 via Cranelift JIT skeleton.
- Phase 2: Control (Jump/Branch/Phi), Load/Store, Compare, String concat via NyRT, Box/Extern by-id (fixed/vector).
- Phase 3: GC barriers/safepoints; parity with VM（CountingGc での観測を含む）。
- Phase 4: Stability, logs, strict/legacy guards; optional AOT via cranelift-object + link scripts.
Notes from Review
- Using Semantics trait enables zero‑cost abstractions with static dispatch.
- Add optional debug hooks (location/value) and optimization hints (likely_branch, pure_function_hint) later.
- Testing: MockSemantics for unit tests; parity tests VM vs CLIF.
Action Items
- Land Semantics trait + minimal MirInterpreter (skeleton added).
- Implement ClifSem minimal lowering; wire Runner `--backend cranelift`.
- Centralize ABI helpers; migrate existing scattered logic to shared module.
- Emit `nyash.rt.checkpoint` and `nyash.gc.barrier_write` from LowerCore at appropriate sites; wire Await (PoC: blocking get).
- Add build_cl scripts for AOT when ready.
Links
- PLAN.md – milestones and coverage
- CURRENT_TASK.md – immediate focus

81
docs/development/roadmap/phases/phase-11.7_jit_complete/PLAN.md Normal file
View File

@ -0,0 +1,81 @@
# Phase 11.7 – JIT Complete Plan (Cranelift)
Goal
- Ship a complete JIT backend (Cranelift) for MIR Core‑15 with Semantics layer as the single source of truth, GC sync/async support, and full Box/Extern integration. Keep DX simple and cross‑platform.
Milestones
1) Bootstrap (Infra + Skeleton)
- Add backend module: `src/backend/cranelift/{mod.rs,context.rs,lower.rs,jit.rs,object.rs}`
- Context: host ISA, FunctionBuilder, Module (JIT/Object) setup helpers
- Runner: `--backend cranelift` execution path; feature flag reuse (`cranelift-jit`)
- Minimal ops: Const i64/f64/bool/null/string → CLIF values; Return; straight‑line add/sub
- Smoke: `apps/tests/ny-echo-lite` returns 0 via JIT
2) Core MIR‑15 Lowering (Parity with VM)
- Control: Jump/Branch/Phi, Load/Store (alloca on entry; i1↔i64 widen/narrow)
- Unary/Binary/Compare: int/float/ptr eq/ne; logical and/or via to_bool
- TypeOp (when needed) + pointer/int casts (handle→i64/i8* via ABI helpers)
- Strings: concat via NyRT shims (`nyash.string.concat_*`)
- BoxCall (by‑id): fixed/tagged args (<=4) + vector path; handle‑first returns (i64/ptr)
- ExternCall: `env.console.*`, `env.debug.trace`, `console.readLine` via NyRT shims
- Smokes: array/map/vinvoke(size/ret), echo; compare outputs with VM
3) GC Cooperation
- Sync barriers: insert read/write barriers at Load/Store & NewBox as per VM semantics
- Async safepoints: at call sites/loop backedges; NyRT entry glue to yield if required
- Tests: targeted barrier smoke (array/map mutations) + perf sanity (no excessive barriers)
4) Parity + Stability
- UnsupportedLegacyInstruction: maintain strict mode; allow env override for debug
- Error reporting: source op pretty‑print, MIR value ids in error messages
- Logging: `NYASH_CLI_VERBOSE=1` shows JIT compile stages + object sizes (optional)
- Doc/Doctor script: `tools/doctor.ps1`/`.sh` for quick env checks (optional nice‑to‑have)
5) AOT (Optional within 11.7 if time)
- `cranelift-object` emit: `.o` for main; link with NyRT → exe (`tools/build_cl.*`)
- Windows: clang/lld link; Linux: cc link; parity with LLVM’s scripts
Instruction Coverage (MIR Core‑15)
- Const, UnaryOp, BinOp, Compare, TypeOp
- Load, Store, Phi, Jump, Branch, Return
- Call, NewBox, BoxCall, ExternCall
ABI & Shims
- Handle‑first: receiver/values normalized to i64; ptr/int casts via helpers
- NyRT shims used: `nyash.console.*`, `nyash.debug.trace`, `nyash.console.readline`,
`nyash_string_new`, `nyash.string.concat_*`, `nyash_array_*_h`, `nyash.instance.*_h`,
plugin invoke (by‑id tagged, vector variants)
Semantics Integration (new in 11.7)
- Add `Semantics` trait as unified MIR semantics API.
- Provide `SemanticsVM` (exec) and `SemanticsClif` (lower) so the same MIR walks yield identical behavior across VM and JIT.
- Use `semantics::MirInterpreter` for parity tests; prefer zero‑cost abstractions with static dispatch.
Status Notes (2025‑09‑01)
- LLVM AOT: closed for now due to Windows dependency weight; Cranelift is the mainline.
- VM: safepoint/barrier/scheduler wired and observable (CountingGc).
- JIT: `nyash.rt.checkpoint`/`nyash.gc.barrier_write` symbols are available via NyRT; LowerCore needs to emit safepoints and barriers; Await lowering pending.
Deliverables
- Code: Cranelift backend files + runner integration
- Tools: build/run scripts for JIT/AOT; updated smokes to exercise CL route
- Docs: this plan + CURRENT_TASK.md; brief README how to run JIT
Risks & Mitigations
- Pointer/int mismatch → normalize via i64/ptr helpers in one place; add asserts
- Barrier placement overhead → start with conservative placement; measure; trim if safe
- Windows toolchain variance → Cranelift avoids external LLVM; keep MSVC only
Timeline (indicative)
- Week 1: Milestone 1 + 2 (most ops) → basic smokes green
- Week 2: GC barriers + safepoints, full parity sweep; docs/tools polish
- Optional: AOT via cl‑object emit & link scripts

19
docs/development/roadmap/phases/phase-11.7_jit_complete/README.md Normal file
View File

@ -0,0 +1,19 @@
# Phase 11.7 – JIT Complete (MIR-15 + Semantics + Sync/Async GC)
Scope: Implement a production‑ready JIT backend for Nyash that fully supports the MIR Core‑15 instruction set, synchronous/async GC cooperation, and delivers a simple, reproducible developer experience across platforms (WSL/Linux/Windows).
Why now:
- LLVM AOT は一度実装を進めたが、Windows 依存が重くサイズも大きい。Cranelift に回帰して、純Rustで“Just Works”のDXを取り戻し、高速な反復開発を実現する（AOT/LLVMは資料として保持）。
Outcomes (Definition of Done):
- All MIR‑15 ops compile and execute via JIT with behavioral parity to VM.
- BoxCall/ExternCall are handled through NyRT shims (handle‑first ABI) safely.
- Sync GC barriers in place (read/write), async safepoints wired at call/loop edges.
- Smokes: echo/array/map/vinvoke/extern pass; parity checks vs VM/JIT (logs included).
- 1‑command setup and run on WSL + Windows Dev PowerShell; no external LLVM needed.
Backends Strategy:
- LLVM AOT はアーカイブ（参照は可）。主線は Cranelift（JIT/軽量AOT）。
- JIT 既定は Cranelift（feature: `cranelift-jit`）。AOT は必要に応じ `cranelift-object` を併用。
This folder contains the living plan (PLAN.md) and the rolling snapshot of the current task focus (CURRENT_TASK.md). Semantics 層の導入により、Nyash スクリプト／VM／JIT（exe）の動作を一致させる。

176
docs/development/roadmap/phases/phase-12/README.md
View File

@ -1,115 +1,107 @@
# Phase 12: Nyashスクリプトプラグインシステム革命
# Phase 12: Nyashコード共有エコシステム - Everything is Box の実現
## 🚀 概要
## 🎯 重要な変更 (2025-09-01)
Nyashスクリプト自体でプラグインを作成できる革命的発見！ビルド不要で、既存のネイティブプラグインを組み合わせて新機能を作成可能。
Phase 12の議論とビルトインBox廃止により、プラグインシステムが進化：
## 💡 発見の経緯
include/export仕様の検討中に、以下の重要な気づきが：
**新しい3層プラグインシステムが確立されました！**
```nyash
# custom_math_plugin.ny
export box CustomMathPlugin {
init {
_math = new MathBox() # 既存プラグイン活用
_cache = new MapBox() # 結果キャッシュ
# Nyashスクリプトプラグイン（ユーザー定義Box）
box DataProcessor {
init {
me.file = new FileBox() # C ABIプラグイン使用
me.math = new MathBox() # C ABIプラグイン使用
me.cache = new MapBox() # これもC ABIプラグイン（ビルトイン廃止）
}
// カスタム拡張
cached_sin(x) {
local key = x.toString()
if me._cache.has(key) {
return me._cache.get(key)
}
local result = me._math.sin(x)
me._cache.set(key, result)
process(data) {
local result = me.math.sin(data)
me.file.write("log.txt", result.toString())
return result
}
}
# 使用例
local processor = new DataProcessor()
processor.process(3.14) # すべてプラグインで動作！
```
これにより、Rust/C++のビルドなしでプラグイン開発が可能に！
## 📝 なぜ誤解が生まれたのか
## 🎯 統一Box ABI設計
「プラグイン」という言葉から、特別な仕組みが必要だと考えてしまいましたが、Nyashの「Everything is Box」哲学により、ユーザー定義Boxこそが最高のプラグインシステムでした。
### 基本インターフェース
詳細な分析：[なぜ天才AIたちは間違えたのか](./WHY-AIS-FAILED.md)
```rust
// Rust側の統一インターフェース
trait BoxInterface {
fn invoke(&self, method_id: u32, args: NyashValue) -> NyashValue;
fn get_methods(&self) -> Vec<MethodInfo>;
fn init(&mut self, ctx: Context);
fn drop(&mut self);
}
## 🚀 Phase 12の真の価値：コード共有エコシステム
### 本当に必要なもの
1. **export/import構文**
```nyash
# math_utils.ny
export box MathUtils {
factorial(n) { ... }
fibonacci(n) { ... }
}
# main.ny
import { MathUtils } from "math_utils.ny"
local utils = new MathUtils()
```
2. **パッケージマネージャー**
```bash
nyash install awesome-math-utils
nyash publish my-cool-box
```
3. **ドキュメント生成**
```nyash
# @doc 素晴らしい数学ユーティリティ
# @param n 計算したい数値
# @return 階乗の結果
export box MathUtils { ... }
```
## 📊 新しい3層プラグインシステム
```
Nyashエコシステム（ビルトインBox廃止後）：
├── Nyashスクリプトプラグイン（ユーザー定義Box）← .nyashファイル
├── C ABIプラグイン（既存のまま使用）← シンプル・高速・安定
└── Nyash ABIプラグイン（必要時のみ）← 言語間相互運用・将来拡張
└── MIR命令は増やさない（BoxCallにabi_hint追加のみ）
```
### Nyashスクリプトプラグインの要件
### プラグイン選択の指針
- **C ABIで済むなら、C ABIを使う**（シンプルイズベスト）
- Nyash ABIは以下の場合のみ：
- 他言語（Python/Go等）からの呼び出し
- 複雑な型の相互運用が必要
- 将来の拡張性を重視する場合
```nyash
export box MyPlugin {
// 必須：初期化
init { ... }
// 推奨：FFI互換インターフェース
invoke(method_id, args) {
// method_idに基づいてディスパッチ
}
// オプション：メソッド情報
get_methods() {
return [
{ name: "method1", id: 1 },
{ name: "method2", id: 2 }
]
}
}
```
## 🛣️ 実装ロードマップ（修正版）
## 📊 エコシステムへの影響
### Phase 12.1: export/import構文（2週間）
- [ ] exportキーワードのパーサー実装
- [ ] importステートメントの実装
- [ ] モジュール解決システム
- 📄 **[詳細仕様書](./export-import-spec.md)**
### 開発の民主化
- **参入障壁の劇的低下**: Rust/C++環境不要
- **即座の開発**: ビルド待ち時間ゼロ
- **コミュニティ拡大**: より多くの開発者が参加可能
### Phase 12.2: パッケージ管理（3週間）
- [ ] nyash.tomlのdependencies対応
- [ ] 中央リポジトリ設計
- [ ] CLIツール（install/publish）
- 📄 **[パッケージマネージャー設計書](./package-manager-design.md)**
### 新しい開発パターン
1. **プラグインの合成**: 複数のネイティブプラグインを組み合わせ
2. **ラピッドプロトタイピング**: アイデアを即座に実装
3. **ホットリロード**: 実行中の更新が可能
## 🛣️ 実装ロードマップ
### Phase 12.1: 基盤構築
- [ ] Box ABI仕様の最終決定
- [ ] export box構文のパーサー実装
- [ ] 基本的なPluginRegistry実装
### Phase 12.2: 統一インターフェース
- [ ] FFIプラグインのBoxInterface対応
- [ ] NyashスクリプトのBoxInterface実装
- [ ] 相互運用テスト
### Phase 12.3: 動的機能
- [ ] 動的ロード/アンロード機能
- [ ] ホットリロード対応
- [ ] プラグイン間依存関係管理
### Phase 12.4: セキュリティと最適化
- [ ] サンドボックス実装
- [ ] ケイパビリティベース権限
- [ ] パフォーマンス最適化
## 📚 関連ドキュメント
- [Gemini先生の分析](./gemini-analysis-script-plugins.md)
- [Codex先生の技術提案](./codex-technical-proposal.md)
- [統合分析まとめ](./synthesis-script-plugin-revolution.md)
## 🎯 次のアクション
1. Box ABI仕様書の作成
2. export box構文の実装開始
3. 既存FFIプラグイン1つを統一インターフェースに移行
### Phase 12.3: 開発者体験向上（継続的）
- [ ] ドキュメント生成ツール
- [ ] VSCode拡張（補完・定義ジャンプ）
- [ ] サンプルパッケージ作成
---
*Everything is Box - そしてプラグインもBoxになる！*
### 🗄️ 議論の過程
AIたちがなぜ複雑な解決策を提案したのか、その議論の過程は `archive/` ディレクトリに保存されています。良い教訓として残しておきます。

112
docs/development/roadmap/phases/phase-12/WHY-AIS-FAILED.md Normal file
View File

@ -0,0 +1,112 @@
# なぜ天才AIたちは間違えたのか - Phase 12の教訓
## 🤔 根本的な誤解
### AIたちの誤解
```
「スクリプトプラグイン」という特別な仕組みが必要
→ JIT/AOTから呼び出せない問題がある
→ 複雑な解決策が必要
```
### 実際の真実
```
Nyashスクリプト = 普通のユーザー定義Box
→ すでに動いている
→ 何も問題ない
```
## 💡 なぜこんな誤解が生まれたのか
### 1. 「プラグイン」という言葉の罠
- AI思考：「プラグイン = 外部DLL/SO = 特別な仕組み」
- 実際：「プラグイン = 再利用可能なBox = 普通のユーザー定義Box」
### 2. 実装レイヤーの混同
```
AIの頭の中：
┌─────────────────────┐
│ JIT/AOT (最適化層) │ ← ここに固執
├─────────────────────┤
│ C ABI プラグイン │
├─────────────────────┤
│ スクリプトプラグイン │ ← 新しい層を作ろうとした
└─────────────────────┘
実際のNyash：
┌─────────────────────┐
│ Nyash VM/インタープリター │
├─────────────────────┤
│ すべてがBox（統一層）│
│ - ビルトインBox │
│ - C ABIプラグイン │
│ - ユーザー定義Box │ ← これだけで十分！
└─────────────────────┘
```
### 3. 過度な最適化思考
- AI：「JIT/AOTで高速化しなければ！」
- 実際：「インタープリター言語として十分高速」
### 4. Everything is Boxの哲学を忘れた
```nyash
# これが既に「スクリプトプラグイン」！
box DataProcessor {
init {
me.file = new FileBox() # C ABIプラグイン
me.math = new MathBox() # C ABIプラグイン
me.cache = new MapBox() # ビルトインBox
}
process(data) {
# 全部普通に動く！
local result = me.math.sin(data)
me.file.write("log.txt", result.toString())
return result
}
}
```
## 🎓 教訓
### 1. シンプルな解決策を見逃すな
- 複雑な問題に見えても、既存の仕組みで解決できることが多い
- 「Everything is Box」は強力な統一原理
### 2. 言葉に惑わされるな
- 「プラグイン」→「特別な仕組み」という連想を避ける
- 本質を見る：「再利用可能なコード」
### 3. ユーザー視点を忘れるな
```nyash
# ユーザーから見れば、これで十分！
local processor = new DataProcessor()
local result = processor.process(3.14)
```
### 4. AIの弱点
- 技術用語から過度に複雑な解釈をしがち
- 既存の解決策より新しい仕組みを作りたがる
- レイヤーを増やしたがる傾向
## 📝 Phase 12の本当の価値
### 実は必要なのは
1. **export/import構文**（ファイル間でBoxを共有）
2. **パッケージマネージャー**（Boxの配布・インストール）
3. **ドキュメント生成**（Boxの使い方を共有）
### 必要ないもの
- 特別な「スクリプトプラグイン」層
- JIT/AOT統合
- 複雑なトランスパイル
## 🚀 結論
**Nyashは最初から正しかった。Everything is Boxだから、すべてが統一的に動く。**
AIたちは「プラグイン」という言葉に惑わされて、存在しない問題を解決しようとしていた。
---
*時に、最も賢い解決策は「何もしないこと」である。*

87
docs/development/roadmap/phases/phase-12/abi-strategy-discussion/README.md Normal file
View File

@ -0,0 +1,87 @@
# Nyash ABI戦略議論まとめ (2025-09-01)
## 📋 概要
Phase 12のプラグインシステム実装において、C ABIとNyash ABIの選択について、AI先生方と深い技術議論を行いました。
## 🗂️ ドキュメント一覧
1. **[gemini-abi-analysis.md](gemini-abi-analysis.md)**
- Gemini先生の長期エコシステム視点
- ABI安定性の重要性
- 段階的進化戦略（C ABI → SDK → WASM）
2. **[codex-abi-implementation.md](codex-abi-implementation.md)**
- Codex先生の実装最適化視点
- C呼出規約×Nyash値表現の提案
- VM/JIT最適化の具体策
3. **[deep-analysis-synthesis.md](deep-analysis-synthesis.md)**
- なぜ正解が難しいのかの深い分析
- 時間軸のジレンマ
- 「正解がない」ことが答え
## 🎯 結論：BoxCall拡張による統合案
### 最終的な実装方針
```rust
// MIRレベル：BoxCallをちょっと拡張
MirInstruction::BoxCall {
receiver: Value,
method: String,
args: Vec<Value>,
abi_hint: Option<AbiType>, // ← これだけ追加
}
```
### 利点
1. **MIR命令数は15個のまま**（美しさ維持）
2. **既存コードは変更不要**（後方互換）
3. **プラグインごとにABI選択可能**（段階的移行）
4. **Everything is Box哲学の体現**
### 実装計画
```yaml
Week 1: 基盤整備
- PluginABI enum定義
- nyash.tomlのabi field追加
- NyashValue構造体作成
Week 2: VM統合
- プラグインローダー拡張
- VM実行時のABI分岐
- pack/unpack実装
Week 3: 検証
- 比較ベンチマーク
- ドキュメント作成
- 方向性判断
```
## 🔑 重要な洞察
1. **両ABI共存が現実的**
- C ABI：既存資産・高速・安定
- Nyash ABI：型安全・拡張性・将来性
2. **適応的戦略の採用**
- 3ヶ月ごとに測定・評価
- データに基づく進化
3. **箱理論による差し替え可能性**
- 実装を箱に切り出す
- いつでも戻せる安心感
## 📊 次のステップ
1. このREADMEを起点に実装開始
2. 最小限のプロトタイプ作成
3. 性能・開発体験の比較データ収集
4. Phase 12本実装への反映
---
*「間に挟むだけ」が最も難しい設計判断だった。しかし、BoxCall拡張という自然な解決策にたどり着いた。*

124
docs/development/roadmap/phases/phase-12/abi-strategy-discussion/codex-abi-implementation.md Normal file
View File

@ -0,0 +1,124 @@
# Codex先生のNyash ABI実装戦略 (2025-09-01)
## 質問内容
Nyashプラグインシステムの ABI戦略について技術的相談です。
【背景】
Phase 12でNyashスクリプトプラグインシステムを実装中です。現在、プラグインインターフェースの設計で重要な判断が必要です。
【現状】
- 既存: C ABI（シンプル、高速、実績あり）
- 提案: Nyash ABI（3×u64構造体、型情報付き、拡張性高い）
【トレードオフ】
C ABI:
- 利点: ゼロオーバーヘッド、既存資産活用、シンプル
- 欠点: 型情報なし、拡張性限定、エラー処理が原始的
Nyash ABI:
- 利点: 型安全、メタデータ活用、将来性（async等）
- 欠点: pack/unpackのオーバーヘッド、新規学習コスト
【具体的な選択肢】
1. Nyash ABIのみ（統一性重視）
2. C ABI + Nyash ABI両方（実用性重視）
3. その他の革新的アプローチ？
【質問】
1. どちらの戦略が長期的に見て賢明でしょうか？
2. 両方サポートする場合の複雑性は管理可能でしょうか？
3. 他の言語での成功例・失敗例から学べることは？
4. VM/JIT最適化の観点から、どちらが有利でしょうか？
実装の実践的観点から、C ABIとNyash ABIの選択について深く分析してください。特にVM/JIT最適化や実装の複雑性を考慮して。
## Codex先生の回答
**結論**
- 長期的には「C呼出規約 × Nyash値表現（3×u64）」を中核に、C ABIとNyash ABIの両方をサポートする二層戦略が最も堅実。
- まずは二者併存で運用し、JIT/VMでの最適化余地と実用性を確保しながら、将来的にNyash ABIを第一級に育てるのが現実的。
**推奨戦略**
- 両対応（2）を採用。ただし"呼出規約はC、値表現はNyash"を共通土台にする。
- 共通の値ABI: `#[repr(C)] struct NyValue { u64 tag; u64 payload; u64 aux; }`
- C ABI関数でもNyValueを受け渡しできるため、型安全・メタデータ拡張の道を確保しつつ、Cの安定性・高速性を得る。
- プラグイン初期化は「バージョン付き関数テーブル（vtable）＋機能フラグ」の交渉型にする。
- 例: `NyPluginInitV1(NyRtFnsV1* rt, NyPluginV1* out)` → `NyPluginV1 { u32 abi_mask; u32 size; NyFnDesc* fns; ... }`
- `abi_mask`で `NY_ABI_C` と `NY_ABI_NYV1` の両方可否を示す。将来の `NY_ABI_NYV2` も追加可能。
- エラーモデルは二段階:
- 速経路: `NyStatus`（enum, small int）を戻す。失敗時は`NyValue`でエラーオブジェクトをout-param返却。
- 詳細情報は`NyError`ヘルパ（`NyValue`として表現）に格納。FFI境界でpanic禁止・例外横断なし。
- メモリ/所有権はハンドル/関数テーブル経由で統一（NyRTのalloc/free、string/slice作成API）。内部構造体への直接依存は不可。
**複雑性と管理**
- 追加コストは主にローダとアダプタ（トランポリン）実装＋テスト行列の増加。ただし次の工夫で管理可能:
- 機能交渉を一本化（init関数とマニフェスト/nyash.tomlで表明）。ロード時に一度だけ決定。
- 呼出アダプタをテンプレート化／JIT時に生成・キャッシュ（型配列→シグネチャ→thunkアドレス）。
- 型表（`NyFnDesc`に引数/戻りの型ID配列、純関数/readonly/aliasing属性）を持ち、最適化と検証を兼用。
- 見積り：ローダ＋vtable＋アダプタの骨格は数百行〜千行弱で収まり、以降は関数種別追加が足し算。
**他言語の事例からの学び**
- 成功例
- Node N-API: バージョン化された関数テーブルでABIを安定化。実装側の進化と互換の両立に有効。
- Lua C API: C呼出規約＋独自値表現で長期安定。ただしstackベースは学習コストあり。
- 反省点
- CPython C API: 内部構造体露出で進化の足枷に。HPyはハンドル化で再設計。
- JNI: 汎用だが冗長・低速傾向。最適化しづらい。
- 教訓
- 内部レイアウト非公開（ハンドル/関数経由）・バージョン化vtable・拡張フラグが長期安定の鍵。
- 値ABIは固定サイズ・レジスタ渡し最適化可能な形が吉（3×u64は合理的）。
**VM/JIT最適化の観点**
- 呼出オーバーヘッド
- 3×u64はSysV/Win64いずれもレジスタ渡しが効きやすく、C ABIと同等のコールコストに収束。
- 本質的ボトルネックは間接呼出ミス予測と型検査。JITで型が既知ならチェックを埋め込み/削減可能。
- 直呼 vs トランポリン
- 署名が一致する場合は直接呼出（JITに外部シンボルとして登録）。
- 型昇降/借用が必要な時のみthunkを噛ませる。JITでモノモーフィック化・デッドパス除去。
- 最適化ヒント（Cranelift/LLVM）
- 関数属性: `nounwind`, `readonly`/`readnone`, `nocapture`, `nonnull`, `cold`（エラーパス）
- 戻り値はout-paramにしてtailcall最適化（`musttail`適用可否は要検証）。
- シンボルはAOT時`dso_local`、JITは`CallConv::SystemV/WindowsFast`で3×i64に整合。
- ホットループ対策
- スカラー跨ぎは避け、スライス/バルクAPIを定義（例: vector add）。boundary跨ぎ回数を削減。
- 将来は静的リンクモード（first-party plugins）でLTO許可→AOTでインライン・DCE可。
**Nyash ABIのみ vs 併存の比較**
- Nyash ABIのみ（1）
- 一貫性と将来性は高いが、既存C資産/ツール連携コストと立上げ摩擦が大きい。
- 併存（2, 推奨）
- 早期エコシステム拡大と最適化の両取り。複雑性はvtable＋アダプタの設計で抑え込み可能。
- その他（3）
- N-API風ハンドル専一は安定するが、オーバーヘッド/冗長性が増える。Nyashのパフォーマンス志向には過剰。
**実装メモ（具体）**
- 値ABI
- `tag`: 上位ビットに種別・フラグ（own/borrow、small/heap、nullable等）
- `payload`: ポインタor即値、`aux`: len/stride/arena_id等
- `NySlice`: `tag=SLICE`で`payload=ptr`, `aux=len`。borrow時は生存期間制約、必要なら`nyrt_clone_slice`で所有権取得。
- 初期化/交渉
- `NyPluginInitV1(NyRtFnsV1*, NyPluginV1*) -> NyStatus`
- `NyRtFnsV1`: alloc/free、string/slice/future、log、error造作API。
- `NyPluginV1`: `abi_mask`, `size`, `features`, `fn_count`, `NyFnDesc*`.
- エラー/非同期
- `NyStatus` + `NyValue err_out`。非同期は `NyFuture*`を返却、`NyRtFnsV1`で`poll/wake`を橋渡し。
- VMのスケジューラとWakerのブリッジはvtableで隠蔽（ABI非依存）。
- 安定性
- すべての公開構造体に`size`を先頭フィールドに持たせ将来拡張。未理解フィールドは無視。
- ABIバージョンは数値＋機能フラグで条件分岐（ビルド時にも`#[cfg(feature)]`で絞る）。
**質問への回答**
- 1) 長期的に賢明か: 併存＋共通値ABIが最善。Cの互換性とNyashの型安全/拡張性を両立。
- 2) 複雑性は管理可能か: はい。vtableの一本化、JIT生成thunk、機能交渉で抑制できる。
- 3) 学び: 内部構造体を外部に晒さない・ハンドル経由・バージョン化テーブル・豊富な属性メタデータ。CPythonの反省とN-APIの成功を取り込む。
- 4) VM/JIT最適化: 3×u64のNyash値はレジスタ渡しでC ABIと同等に速く、型既知箇所はJITで直呼/チェック省略可能。最適化の自由度はNyash ABIの方が高い。
**次のアクション**
- 値ABIと関数テーブル仕様を`crates/nyrt/include/nyrt.h`に最小ドラフト化（`NyValue`, `NyStatus`, `NyRtFnsV1`, `NyPluginV1`, `NyFnDesc`）。
- ローダにinit/交渉実装（`nyash.toml`のabi種別・型情報読み込み→関数登録）。
- JIT/VMに外部関数署名登録とthunk生成を追加（Cranelift/LLVM兼用）。
- バルク演算プラグインのスモークを作成（C ABI版とNyash ABI版を比較ベンチ）。
- ドキュメント化（`docs/plugins/abi.md`）とサンプル（`plugins/`、`apps/`）追加。
必要なら、ドラフトの`NyValue`と`NyPluginInitV1`の最小Cヘッダ案もすぐ出します。

188
docs/development/roadmap/phases/phase-12/abi-strategy-discussion/codex-boxcall-extension-analysis.md Normal file
View File

@ -0,0 +1,188 @@
# Codex先生のBoxCall拡張分析 (2025-09-01)
## 質問内容
Nyash ABI実装の具体的アプローチについて技術相談です。
【背景】
前回の議論で、C ABIとNyash ABIの両方をサポートする方向性が見えました。実装方法について新しいアイデアがあります。
【BoxCall拡張による統合案】
MIR命令を増やさず、既存のBoxCallを自然に拡張する案です：
```rust
// 現在のBoxCall
MirInstruction::BoxCall {
receiver: Value,
method: String,
args: Vec<Value>,
}
// 提案：最小限の拡張
MirInstruction::BoxCall {
receiver: Value,
method: String,
args: Vec<Value>,
abi_hint: Option<AbiType>, // 追加
}
```
【実装の流れ】
1. MIRビルダー：プラグインBoxならABIヒント付与
2. VM実行時：receiver.type_idから適切なABI選択
3. プラグインローダー：nyash.tomlでABI指定可能
【この案の利点】
- MIR命令数は15個維持（Everything is Box哲学）
- 既存コード無変更（後方互換）
- プラグインごとに段階的移行可能
- JITでABI別最適化も可能
【質問】
1. このBoxCall拡張案は設計として健全でしょうか？
2. abi_hintは本当に必要？VM実行時の型判定で十分？
3. 将来的な拡張（WASM等）にも対応できる設計か？
4. パフォーマンス影響をどう評価すべきか？
実装の観点から、MIR層でのabi_hint追加とVM層でのABI判定について深く分析してください。特に既存実装への影響を最小化する方法を考慮して。
## Codex先生の回答
### コードベース分析
まず、現在のMIR/VM実装を確認：
```rust
// 現在のMirInstruction::BoxCall定義
BoxCall {
dst: Option<ValueId>,
box_val: ValueId,
method: String,
method_id: Option<u16>, // Universal method用
args: Vec<ValueId>,
effects: EffectMask,
}
```
プラグインローダーはすでにnyash.tomlから型情報を読み込んでおり、VM実行時に利用可能。
### 核心的な洞察
**abi_hintは実は不要かもしれない！**
理由：
1. VM実行時にreceiver.type_idから型情報を取得可能
2. プラグインローダーが既にABI情報を保持している
3. MIR層を変更せずに済む（15命令維持）
### 実装提案
#### Option A: 最小限実装（MIR無変更）
```rust
// VM層での実装
fn execute_boxcall(&mut self, dst: Option<ValueId>, box_val: ValueId, method: &str, args: &[ValueId]) -> Result<ControlFlow, VMError> {
let receiver = self.get_value(box_val)?;
let type_id = receiver.get_type_id();
// プラグインローダーから型情報取得
if let Some(plugin_info) = self.runtime.get_plugin_info(type_id) {
match plugin_info.abi.as_str() {
"c" => self.call_c_abi_plugin(plugin_info, method, args),
"nyash" => self.call_nyash_abi_plugin(plugin_info, method, args),
_ => self.call_c_abi_plugin(plugin_info, method, args), // fallback
}
} else {
// ビルトインBox処理（既存のまま）
self.execute_builtin_method(receiver, method, args)
}
}
```
#### Option B: 将来の拡張性を考慮
```rust
// MIRに汎用メタデータ追加（ABIに限定しない）
MirInstruction::BoxCall {
receiver: Value,
method: String,
args: Vec<Value>,
metadata: Option<u32>, // 汎用的な最適化ヒント
}
```
### JIT/AOT最適化の観点
```rust
// JIT時の特化
match type_info.abi {
Some("c") => {
// 直接call命令生成
builder.emit_direct_call(symbol, args);
}
Some("nyash") => {
// NyashValue pack/unpackを含めてインライン化
let packed = builder.emit_pack_nyash_values(args);
builder.emit_call_with_abi(symbol, packed);
}
_ => {
// 汎用パス（VM呼び出し）
builder.emit_vm_boxcall(receiver, method, args);
}
}
```
### パフォーマンス評価方法
```rust
// ベンチマーク設計
fn benchmark_abi_comparison() {
// 1. 高頻度呼び出し（math operations）
measure_time("C ABI", || {
for _ in 0..1_000_000 {
math_add_c_abi(1.0, 2.0);
}
});
measure_time("Nyash ABI", || {
for _ in 0..1_000_000 {
math_add_nyash_abi(pack(1.0), pack(2.0));
}
});
// 2. 複雑な型（string operations）
// 3. プラグイン初期化コスト
}
```
### 結論と推奨事項
1. **abi_hintは不要** - VM実行時の型判定で十分
2. **MIR層は無変更** - 15命令の美しさ維持
3. **将来拡張は型システム経由** - WASMもプラグイン型として追加
4. **段階的実装**：
- Week 1: nyash.toml拡張 + VM分岐
- Week 2: ベンチマーク + 最適化
- Week 3: JIT特化（必要なら）
### 実装の具体的ステップ
```yaml
Step 1: nyash.toml拡張
- LibraryDefinition に abi: Option<String> 追加
- デフォルトは "c"
Step 2: プラグインローダー
- PluginInfo 構造体に abi フィールド追加
- ロード時に保存
Step 3: VM execute_boxcall
- 型判定でABI分岐
- call_c_abi / call_nyash_abi メソッド追加
Step 4: テスト
- 同一機能の C/Nyash 両実装
- 性能比較測定
```
この最小限アプローチなら、既存コードへの影響を最小化しつつ、将来の拡張性も確保できます。

164
docs/development/roadmap/phases/phase-12/abi-strategy-discussion/deep-analysis-synthesis.md Normal file
View File

@ -0,0 +1,164 @@
# Nyash ABI戦略の深い分析 - なぜ正解が難しいのか (2025-09-01)
## 🤔 両先生の回答から見えた根本的な難しさ
### 1. 時間軸のジレンマ
**Gemini先生の視点**（長期エコシステム）：
- 10年後も動くプラグインを作りたい
- 破壊的変更は絶対避けたい
- 開発者の信頼が最重要
**Codex先生の視点**（現実的最適化）：
- 今すぐ高速に動かしたい
- JIT/VMの最適化余地を残したい
- 実装の複雑性を抑えたい
→ **この2つは本質的に矛盾する！**
### 2. 抽象化レベルの選択
```
高レベル抽象化（Gemini案）
↑
SDK層
↑
C ABI（安定境界）
vs
低レベル統合（Codex案）
↓
共通値表現（3×u64）
↓
C呼出規約で統一
```
どちらが正解？ **状況による！**
### 3. 隠れた複雑性の罠
**表面的には単純に見える選択**：
- C ABI only → シンプル！
- Nyash ABI only → 統一的！
- 両方サポート → 柔軟！
**実際の複雑さ**：
- C ABI only → 型情報なし、拡張困難
- Nyash ABI only → 既存資産切り捨て
- 両方サポート → **複雑性が2倍...ではなく4倍！**
### 4. なぜ複雑性が爆発するのか
```
組み合わせ爆発：
- 2つのABI ×
- 3つのバックエンド（Interpreter/VM/JIT） ×
- N個のプラグイン型 ×
- M個の最適化レベル
= 指数関数的複雑性
```
## 🎯 深い洞察：本当の問題は何か
### 技術的正解 vs ビジネス的正解
**技術的に美しい解**：
- Nyash ABI一本化
- 型安全、拡張可能、統一的
**ビジネス的に賢い解**：
- C ABI + 段階的移行
- 既存資産活用、リスク分散
→ **どちらも「正解」であり「不正解」**
### 隠れた第3の選択肢
両先生が暗黙的に示唆している：
```
時期による使い分け：
Phase 1: C ABIで素早くエコシステム立ち上げ
Phase 2: SDK層で開発体験向上
Phase 3: Nyash ABIで技術的優位性確立
Phase 4: 統合または選択的廃止
```
## 💡 究極の洞察：「正解がない」ことが答え
### なぜ正解が難しいのか
1. **未来は予測不可能**
- NyashがRustを超えるか？
- WASMが世界標準になるか？
- 新しいABI標準が生まれるか？
2. **トレードオフは価値観次第**
- 速度 vs 安全性
- シンプル vs 機能性
- 互換性 vs 革新性
3. **成功の定義が人による**
- 多くのプラグイン？
- 高速な実行？
- 美しいコード？
## 🚀 実践的な答え：適応的戦略
### 推奨アプローチ
```rust
// 初期実装：両対応だが内部統一
enum PluginABI {
C(CPlugin), // 既存資産
Nyash(NyashPlugin), // 新規開発
}
// 共通インターフェース
trait Plugin {
fn invoke(&self, args: &[Value]) -> Result<Value>;
}
// 将来の拡張ポイント
impl PluginABI {
fn optimize_for_jit(&self) -> Option<DirectCall> {
// JIT時に最適化可能なら直接呼び出しに変換
}
}
```
### 段階的進化の道筋
1. **観察期間**（6ヶ月）
- 両ABI並行運用
- 使用パターン分析
- パフォーマンス測定
2. **最適化期間**（次の6ヶ月）
- 頻出パターンの高速化
- SDK層の洗練
- ドキュメント充実
3. **判断期間**（1年後）
- データに基づく選択
- 片方を非推奨に？
- それとも永続的共存？
## 🌟 結論：「正解がない」を受け入れる勇気
**Nyashの哲学**：
- Everything is Box → Everything has Trade-offs
- 完璧より進捗（80/20ルール）
- 箱理論で差し替え可能に
**最終提案**：
1. 両方実装するが、**内部アーキテクチャは統一**
2. **測定可能な成功指標**を先に定義
3. **3ヶ月ごとに振り返り**、方向修正
正解がないからこそ、**適応し続けることが正解**。
---
*「間に挟むだけ」のABI層が、実は最も難しい設計判断の一つだった。*

115
docs/development/roadmap/phases/phase-12/abi-strategy-discussion/final-implementation-decision.md Normal file
View File

@ -0,0 +1,115 @@
# BoxCall拡張によるABI戦略 - 最終実装決定 (2025-09-01)
## 🎯 両先生の回答から得た重要な洞察
### Gemini先生の誤解が示す重要な点
- 先生は「BoxCall = Box<dyn Trait>を渡す」と誤解
- しかし、この誤解が**abi_stable**の重要性を教えてくれた
- 将来的にRustトレイトオブジェクトを扱う際の指針に
### Codex先生の実践的分析
1. **abi_hintは実は不要かもしれない**
- VM実行時にtype_idから判定可能
- プラグインローダーが型情報を保持
- MIR層を汚さない
2. **既存実装への影響最小化**
- TypeMetaにABI情報を含める
- nyash.tomlから読み込み済み
- VM側で判定するだけ
## 🚀 最終実装方針
### Option A: 最小限実装（推奨）
```rust
// MIR層：変更なし！
MirInstruction::BoxCall {
receiver: Value,
method: String,
args: Vec<Value>,
// abi_hint不要！
}
// VM層：型判定でABI選択
fn execute_boxcall(...) {
let type_id = receiver.get_type_id();
// プラグインローダーから型情報取得
if let Some(plugin_info) = get_plugin_info(type_id) {
match plugin_info.abi {
"c" => call_c_abi(...),
"nyash" => call_nyash_abi(...),
_ => fallback_to_c_abi(...),
}
}
}
```
### Option B: 明示的ヒント（将来の拡張性）
```rust
// MIR層：最小限の拡張
MirInstruction::BoxCall {
receiver: Value,
method: String,
args: Vec<Value],
metadata: Option<u32>, // 汎用メタデータ（ABIヒント含む）
}
```
## 📊 比較表
| 観点 | Option A（最小限） | Option B（ヒント付き） |
|------|------------------|---------------------|
| MIR変更 | なし ✅ | 最小限 |
| 実装工数 | 1週間 | 2週間 |
| JIT最適化 | VM時判定 | ビルド時判定可能 |
| 将来拡張 | 型情報経由 | メタデータ活用 |
## 🎯 結論：Option Aで始める
### 理由
1. **80/20ルール**: まず動くものを作る
2. **MIR無変更**: 15命令の美しさ維持
3. **段階的進化**: 必要になったらOption Bへ
### 実装ステップ（1週間）
```yaml
Day 1-2: nyash.toml拡張
- abi: "c" | "nyash" field追加
- プラグインローダー対応
Day 3-4: VM実行時分岐
- execute_boxcall内でABI判定
- NyashValue pack/unpack実装
Day 5-6: テスト・ベンチマーク
- 同一機能の2種類プラグイン
- 性能比較測定
Day 7: 判断
- データに基づく方向性決定
- Option B移行の必要性評価
```
## 💡 深い洞察
**「abi_hintは不要」という発見が示すもの**：
- 型システムが既に十分な情報を持っている
- MIRは純粋な意図の表現で良い
- 実行時の賢い判断に任せる
これこそ「Everything is Box」の真髄 - Boxが自分の実装方法を知っている！
## 🚀 次のアクション
1. nyash.tomlパーサーに`abi` field追加
2. プラグインローダーでABI情報保持
3. VM execute_boxcallで分岐実装
4. 最小限のテストプラグイン作成
---
*最小限から始めて、データで判断する。これがNyashの道。*

179
docs/development/roadmap/phases/phase-12/abi-strategy-discussion/gemini-abi-analysis.md Normal file
View File

@ -0,0 +1,179 @@
# Gemini先生のNyash ABI戦略分析 (2025-09-01)
## 質問内容
Nyashプラグインシステムの ABI戦略について技術的相談です。
【背景】
Phase 12でNyashスクリプトプラグインシステムを実装中です。現在、プラグインインターフェースの設計で重要な判断が必要です。
【現状】
- 既存: C ABI（シンプル、高速、実績あり）
- 提案: Nyash ABI（3×u64構造体、型情報付き、拡張性高い）
【トレードオフ】
C ABI:
- 利点: ゼロオーバーヘッド、既存資産活用、シンプル
- 欠点: 型情報なし、拡張性限定、エラー処理が原始的
Nyash ABI:
- 利点: 型安全、メタデータ活用、将来性（async等）
- 欠点: pack/unpackのオーバーヘッド、新規学習コスト
【具体的な選択肢】
1. Nyash ABIのみ（統一性重視）
2. C ABI + Nyash ABI両方（実用性重視）
3. その他の革新的アプローチ？
【質問】
1. どちらの戦略が長期的に見て賢明でしょうか？
2. 両方サポートする場合の複雑性は管理可能でしょうか？
3. 他の言語での成功例・失敗例から学べることは？
4. VM/JIT最適化の観点から、どちらが有利でしょうか？
## Gemini先生の回答
### NyashプラグインシステムにおけるABI戦略の技術的考察
Nyashプラグインシステムの長期的なエコシステム発展を見据えたABI（Application Binary Interface）戦略について、深く技術的に考察します。
### 1. ABI安定性の重要性：エコシステム成功の礎
プラグインシステムの成功は、**ABIの鉄壁の安定性**にかかっています。ホストアプリケーション（Nyash）とプラグインは、別々にコンパイル・配布されるバイナリです。両者が正しく協調動作できるのは、関数呼び出し規約、データ型表現、メモリアロケーションといった低レベルな規約、すなわちABIが厳密に一致しているからです。
もしNyashのバージョンアップでABIに破壊的変更が生じれば、既存の全プラグインは動作しなくなり、再コンパイルが必要になります。これはエコシステムにとって致命的です。開発者は追従を諦め、ユーザーはプラグインが使えなくなることを恐れてNyashのアップデートをためらうでしょう。
したがって、ABI戦略の最優先目標は**「前方互換性（新しいNyashが古いプラグインを動かせる）と、可能な限りの後方互換性（古いNyashが新しいプラグインの機能を限定的にでも利用できる）」**を保証することです。
### 2. 現状の分析と潜在的リスク
現在のNyashのコードベースを調査し、プラグイン関連の実装を特定する必要があります。`Cargo.toml`やソースコードから、おそらくRustのダイナミックライブラリ（`.so`, `.dll`, `.dylib`）を動的に読み込む形式が採用されていると推測されます。
ここで最も警戒すべきは、**Rust固有のABIに依存することのリスク**です。Rustコンパイラは、パフォーマンス最適化のために、構造体のメモリレイアウトや関数呼び出し規約をバージョン間で予告なく変更します。したがって、`extern "Rust"`（デフォルト）の関数をプラグイン境界として公開するのは、エコシステムの観点からは**絶対に避けなければなりません**。
素晴らしい！検索結果から、Nyashはすでに `extern "C"` を広範囲に利用していることが明確にわかります。これは非常に良い出発点です。`plugin_loader_v2.rs` や `bid/plugin_api.rs` などを見ると、プラグインの初期化（`nyash_plugin_init`）や関数呼び出し（`invoke_fn`）のシグネチャがC ABIで定義されています。
これは、ABI安定性に対する基本的な理解がプロジェクトに既に存在することを示しています。しかし、長期的なエコシステムを築くには、これをさらに推し進め、より洗練された戦略を立てる必要があります。
### 3. 長期的な発展のためのABI戦略提案
現在の `extern "C"` ベースのアプローチを基礎としつつ、以下の戦略を段階的に導入することを提案します。
#### 戦略1：C ABIを「公式な安定境界」として厳格に定義・文書化する
これは最も重要です。`extern "C"` を使っているというだけでは不十分で、それを**公式な規約**として確立する必要があります。
**具体的なアクション:**
1. **ABI仕様書の作成:**
- `nyash-abi.h`のようなCヘッダーファイル形式で、プラグインが実装すべき関数シグネチャと、Nyashが提供するホスト関数（コールバック）をすべて定義します。
- `invoke_fn` で使われている `*const u8`, `*mut u8` のようなバイトポインタが、具体的にどのようなデータを指すのか（シリアライズ形式、レイアウトなど）を厳密に文書化します。
- `NyashHostVtable` のような構造体は、フィールドの順序と型が未来永劫変わらないことを保証しなければなりません。新しいホスト関数を追加する場合は、末尾にのみ追加します。
- エラー報告の規約（戻り値の `i32` が何を意味するのか）を定義します。
2. **FFI（Foreign Function Interface）層の明確化:**
- Nyash内部のRustコードと、C ABI境界を明確に分離します。`plugin_loader_v2.rs` はこの役割を担っているようですが、この層は「ABI変換」にのみ責任を持つべきです。内部的なリファクタリングがABIに影響を与えないようにします。
**利点:**
- **言語非依存:** C ABIはあらゆる主要言語（C++, Zig, Go, Python, etc.）から利用可能で、プラグイン開発者の裾野を広げます。
- **究極の安定性:** C ABIは数十年にわたり安定しています。
**欠点:**
- **表現力の低さ:** Rustの`Result`や`Option`、ライフタイムといった豊かな型情報を直接渡せず、`i32`のエラーコードやポインタのNULLチェックといったプリミティブな方法に頼らざるを得ません。
- **手作業と`unsafe`:** データのシリアライズ・デシリアライズやポインタ操作が必須となり、`unsafe`コードが増え、バグの温床になりやすいです。
#### 戦略2：高レベルな「Rust向けラッパーSDK」を提供する
C ABIの欠点を補うため、プラグイン開発者が直接C ABIを触らなくても済むように、公式のRust製SDK（クレート）を提供します。
**具体的なアクション:**
1. **`nyash-plugin-sdk` クレートの作成:**
- このSDKは、低レベルなC ABIのやり取りをすべてカプセル化します。
- プラグイン開発者は、`Result<MyData, MyError>` のような自然なRustの型を扱うだけで、SDKが自動的にC ABI準拠のデータ（バイト列やエラーコード）との相互変換を行います。
- 定型的なコードを自動生成するマクロ（例: `#[nyash_plugin]`）を提供し、開発体験を向上させます。
**SDK利用者のコード（イメージ）:**
```rust
// プラグイン開発者が書くコード
use nyash_plugin_sdk::{plugin, NyashResult, NyashError};
struct MyPlugin;
#[plugin]
impl Plugin for MyPlugin {
fn handle_request(&self, input: &str) -> NyashResult<String> {
if input == "hello" {
Ok("world".to_string())
} else {
Err(NyashError::new("Invalid input"))
}
}
}
```
**SDK内部の実装（イメージ）:**
```rust
// #[plugin] マクロが生成するコード
#[no_mangle]
pub unsafe extern "C" fn nyash_plugin_invoke(
/* C ABI引数 */
) -> i32 {
// 1. C ABIのバイト列から &str へデシリアライズ
// 2. MyPlugin::handle_request を呼び出し
// 3. 結果の Result<String, NyashError> をC ABIのエラーコードとバイト列にシリアライズ
// 4. 結果を返す
// ... この部分はSDKが隠蔽する ...
}
```
**利点:**
- **高い開発者体験:** Rust開発者は、安全で慣用的なRustコードを書くことに集中できます。
- **安全性の向上:** `unsafe`コードをSDKに集約させることで、プラグイン開発者がメモリ安全性を破壊するリスクを大幅に低減できます。
#### 戦略3：データ交換フォーマットの標準化
`invoke_fn` でやり取りされる `*const u8` の中身を標準化します。これにより、堅牢性と前方互換性が向上します。
**候補:**
- **Protocol Buffers / FlatBuffers:**
- **利点:** スキーマ定義が明確で、前方・後方互換性を考慮した設計が容易。多言語対応のコード生成ツールが豊富。パフォーマンスも高い。
- **欠点:** ビルドプロセスに一手間加わる。
- **JSON / MessagePack:**
- **利点:** 動的で柔軟。デバッグが容易。
- **欠点:** スキーマがないため、実行時エラーになりやすい。シリアライズ・デシリアライズのオーバーヘッドが比較的多きい。
**推奨:**
長期的なエコシステムの安定性を考えると、スキーマベースの **Protocol Buffers** または **FlatBuffers** が最適です。
#### 戦略4：WebAssembly (Wasm) の採用検討
究極の目標として、プラグインをWebAssemblyモジュールとして実行する方式を検討する価値があります。
**利点:**
- **サンドボックス化:** Wasmランタイム（Wasmtimeなど）上でプラグインを実行することで、Nyash本体から完全に隔離された安全な環境を提供できます。悪意のあるプラグインやバグのあるプラグインがホストをクラッシュさせるのを防ぎます。
- **真の言語非依存:** C ABIよりもさらに多くの言語（コンパイルターゲットにWASIを持つもの）がプラグイン開発に利用可能になります。
- **WASIとコンポーネントモデル:** WASI（WebAssembly System Interface）やWasm Component Modelの標準化が進むことで、ファイルアクセスやネットワークなどのホスト機能へのアクセスが標準化され、より洗練されたABIを構築できます。
**欠点:**
- **パフォーマンスオーバーヘッド:** C ABIのダイナミックライブラリ呼び出しに比べ、Wasmランタイムを介在させることによるオーバーヘッドが存在します。
- **実装の複雑さ:** Wasmランタイムの組み込みと、ホスト・ゲスト間のデータ共有（特に複雑なデータ構造）の実装は複雑になります。
### まとめと提言
Nyashは `extern "C"` の採用により、ABI安定化への正しい一歩を踏み出しています。長期的なエコシステムの繁栄のため、以下のロードマップを提案します。
1. **短期（すぐ着手すべき）:**
- **C ABIの公式化:** `nyash-abi.h`相当の仕様を定義し、文書化する。
- **データフォーマットの選定:** `invoke_fn` で交換されるデータのシリアライズ形式としてProtocol Buffers等を導入する。
2. **中期（エコシステムの成長期）:**
- **Rust向けSDKの提供:** `nyash-plugin-sdk` クレートを開発し、Rust開発者の体験を向上させる。
- **他言語向けSDKの提供:** 需要に応じて、PythonやGo向けのラッパーライブラリを提供する。
3. **長期（未来のビジョン）:**
- **WebAssemblyへの移行:** パフォーマンス要件とセキュリティ要件を天秤にかけ、プラグイン実行環境をWasmに移行することを検討する。これにより、究極の安全性と移植性を獲得できる。
この戦略により、Nyashは安定性、開発者体験、安全性を段階的に向上させ、活発で持続可能なプラグインエコシステムを構築できると確信します。

0
docs/development/roadmap/phases/phase-12/IMPLEMENTATION-ROADMAP.md → docs/development/roadmap/phases/phase-12/archive/01_roadmap_final.md
View File

0
docs/development/roadmap/phases/phase-12/SOLUTION-EMBEDDED-VM.md → docs/development/roadmap/phases/phase-12/archive/02_spec_embedded_vm.md
View File

0
docs/development/roadmap/phases/phase-12/BOX-AS-ARGUMENT-SUPPORT.md → docs/development/roadmap/phases/phase-12/archive/03_spec_box_arguments.md
View File

15
docs/development/roadmap/phases/phase-12/CRITICAL-ISSUE.md → docs/development/roadmap/phases/phase-12/archive/CRITICAL-ISSUE.md
View File

@ -1,8 +1,17 @@
# 🚨 重大な設計問題：スクリプトプラグインとMIR/EXEの非互換性
# 🚨 AI議論の誤解：存在しない問題を解決しようとした記録
## 問題の本質
## 誤解の本質
**MIR/JIT/AOT（EXE）は、C ABIの関数しか呼び出せない。**
**この文書は、AIたちが「スクリプトプラグイン」という存在しない問題を作り出し、複雑な解決策を提案した記録です。**
### 実際の事実
- Nyashスクリプト = 普通のユーザー定義Box
- ユーザー定義Boxは既に完璧に動作している
- 特別な仕組みは一切不要
## なぜこんな誤解をしたのか
**「プラグイン」という言葉に引っ張られて、C ABIの外部DLLのような特別な仕組みが必要だと思い込んでしまった。**
```
現実のフロー:

0
docs/development/roadmap/phases/phase-12/EMBEDDED-VM-BOX-HANDLING.md → docs/development/roadmap/phases/phase-12/archive/EMBEDDED-VM-BOX-HANDLING.md
View File

48
docs/development/roadmap/phases/phase-12/archive/OLD-README.md Normal file
View File

@ -0,0 +1,48 @@
# Phase 12 Archive - AIたちの誤解の記録
## 🚨 重要：このフォルダの内容について
このフォルダには、Phase 12の議論で生まれた**誤解に基づいたドキュメント**が保存されています。
### なぜ誤解が生まれたのか
AIたちは「プラグイン」という言葉から、以下のような複雑な仕組みが必要だと考えました：
- トランスパイル（Nyash→C）
- 埋め込みVM
- 特別なABI変換
- JIT/AOT統合
### 実際の真実
**Nyashスクリプト = 普通のユーザー定義Box**
```nyash
# これで十分！特別な仕組みは不要
box MyPlugin {
init {
me.file = new FileBox() # C ABIプラグイン使える
}
process(data) {
return me.file.read(data)
}
}
```
### 教訓として
これらのドキュメントは、以下の教訓を示すために残しています：
1. シンプルな解決策を見逃してはいけない
2. 技術用語に惑わされてはいけない
3. Everything is Boxの哲学を忘れてはいけない
## 📁 アーカイブ内容
- `CRITICAL-ISSUE.md` - 存在しない問題を解決しようとした記録
- `01_roadmap_final.md` - 不要なトランスパイル実装計画
- `02_spec_embedded_vm.md` - 不要な埋め込みVM仕様
- `03_spec_box_arguments.md` - 不要なBox受け渡し仕様
- その他、AI会議での誤解に基づく提案
---
*「時に、最も賢い解決策は何もしないことである」*

0
docs/development/roadmap/phases/phase-12/PLUGIN-BOX-ARG-DECLARATION.md → docs/development/roadmap/phases/phase-12/archive/PLUGIN-BOX-ARG-DECLARATION.md
View File

0
docs/development/roadmap/phases/phase-12/PLUGIN-BOX-HANDLE-SUPPORT.md → docs/development/roadmap/phases/phase-12/archive/PLUGIN-BOX-HANDLE-SUPPORT.md
View File

230
docs/development/roadmap/phases/phase-12/archive/README.md Normal file
View File

@ -0,0 +1,230 @@
# Phase 12: プラグインシステムの進化 - 既存C ABIとの共存戦略
## 🚀 概要
**重要**: 既存のC ABIプラグインはそのまま使い続けられます！その上で、以下の2つの新機能を追加：
1. **Nyash ABIサポート** - より型安全で拡張性の高い新しいABI（オプション）
2. **Nyashスクリプトプラグイン** - ビルド不要でプラグイン作成可能
### なぜ既存C ABIを残すのか？
- **実績と安定性**: 現在動いているFileBox、NetBox等はそのまま
- **ゼロオーバーヘッド**: 高頻度呼び出しには最速のC ABI
- **段階的移行**: 必要に応じて選択的にNyash ABIへ移行可能
## 💡 発見の経緯
include/export仕様の検討中に、以下の重要な気づきが：
```nyash
# custom_math_plugin.ny
export box CustomMathPlugin {
init {
_math = new MathBox() # 既存プラグイン活用
_cache = new MapBox() # 結果キャッシュ
}
// カスタム拡張
cached_sin(x) {
local key = x.toString()
if me._cache.has(key) {
return me._cache.get(key)
}
local result = me._math.sin(x)
me._cache.set(key, result)
return result
}
}
```
これにより、Rust/C++のビルドなしでプラグイン開発が可能に！
## 🎯 ABI共存戦略 - 適材適所の選択
### 三層構造のプラグインエコシステム
```
1. C ABIプラグイン（既存・継続）
- FileBox, NetBox, MathBox等
- 高速・安定・実績あり
- 変更なし！そのまま使える
2. Nyash ABIプラグイン（新規追加）
- 型安全・拡張性重視の新規開発向け
- async/await対応などの将来機能
3. Nyashスクリプトプラグイン（革命的）
- ビルド不要・即座に開発
- 上記1,2を組み合わせて利用可能
```
### 使い分けの指針
| 用途 | 推奨ABI | 理由 |
|------|---------|------|
| 数値計算（高頻度） | C ABI | ゼロオーバーヘッド |
| ファイルI/O | C ABI | 既存実装が安定 |
| 複雑な型操作 | Nyash ABI | 型安全性重視 |
| プロトタイプ | Nyashスクリプト | 即座に試せる |
### 設定例（nyash.toml v2.1）
```toml
# nyash.toml v2.1
[plugin.math]
path = "plugins/math.so"
abi = "c" # 高速・安定（デフォルト）
[plugin.advanced_math]
path = "plugins/advanced_math.so"
abi = "nyash" # 型安全・拡張性
```
### BoxCall拡張による実装
**重要な発見**：MIR層の変更は不要！VM実行時の型判定で十分。
```rust
// MIR層：変更なし（15命令維持）
MirInstruction::BoxCall {
receiver: Value,
method: String,
args: Vec<Value>,
}
// VM層：賢い判定
fn execute_boxcall(...) {
let type_info = get_plugin_info(receiver.type_id);
match type_info.abi {
"c" => call_c_abi(...), // 既存プラグイン
"nyash" => call_nyash_abi(...), // 新プラグイン
}
}
```
### Nyash ABI仕様
```c
// 3×u64構造体による型安全な値渡し
typedef struct NyashValue {
uint64_t type_id; // 型識別子
uint64_t box_handle; // Boxハンドル
uint64_t metadata; // 拡張用（async flag等）
} NyashValue;
// 統一関数シグネチャ
typedef NyashValue (*NyashFunc)(
uint32_t argc,
NyashValue* args,
void* context
);
```
### 基本インターフェース（内部）
```rust
// Rust側の統一インターフェース
trait BoxInterface {
fn invoke(&self, method_id: u32, args: NyashValue) -> NyashValue;
fn get_methods(&self) -> Vec<MethodInfo>;
fn init(&mut self, ctx: Context);
fn drop(&mut self);
}
```
### Nyashスクリプトプラグインの要件
```nyash
export box MyPlugin {
// 必須：初期化
init { ... }
// 推奨：FFI互換インターフェース
invoke(method_id, args) {
// method_idに基づいてディスパッチ
}
// オプション：メソッド情報
get_methods() {
return [
{ name: "method1", id: 1 },
{ name: "method2", id: 2 }
]
}
}
```
## 📊 エコシステムへの影響
### 開発の民主化
- **参入障壁の劇的低下**: Rust/C++環境不要
- **即座の開発**: ビルド待ち時間ゼロ
- **コミュニティ拡大**: より多くの開発者が参加可能
### 新しい開発パターン
1. **プラグインの合成**: 複数のネイティブプラグインを組み合わせ
2. **ラピッドプロトタイピング**: アイデアを即座に実装
3. **ホットリロード**: 実行中の更新が可能
## 🛣️ 実装ロードマップ（2025-09-01更新）
**重要**: 既存のC ABIプラグインは一切変更不要！追加機能として実装します。
### Phase 12.1: ABI共存基盤（1週間）
- [ ] nyash.toml v2.1仕様（abi fieldサポート、デフォルト="c"）
- [ ] プラグインローダーのABI判定実装（後方互換性保証）
- [ ] VM execute_boxcallのABI分岐追加（C ABIは現状維持）
- [ ] 同一機能のC ABI / Nyash ABI比較ベンチマーク
### Phase 12.2: Nyash ABI基盤（2週間）
- [ ] NyashValue構造体定義（crates/nyrt/include/nyash_abi.h）
- [ ] pack/unpack関数実装
- [ ] 既存プラグイン1つをNyash ABI移行（実証実験）
- [ ] JIT最適化（型既知時の特化コード生成）
### Phase 12.3: スクリプトプラグイン対応（3週間）
- [ ] export box構文のパーサー実装
- [ ] BoxInterface trait実装
- [ ] NyashスクリプトのVM内実行環境
- [ ] 相互運用テスト（C/Nyash/Script混在）
### Phase 12.4: 動的機能とエコシステム（継続的）
- [ ] ホットリロード対応
- [ ] プラグイン間依存関係管理
- [ ] プラグインマーケットプレイス構想
- [ ] セキュリティサンドボックス
### 実装優先順位（短期）
1. **Week 1**: nyash.tomlのabi field + VM分岐（動作確認）
2. **Week 2**: 性能測定 + 方向性判断
3. **Week 3**: 本格実装 or 方針転換
## 📚 関連ドキュメント
### 初期設計
- [Gemini先生の分析](./gemini-analysis-script-plugins.md)
- [Codex先生の技術提案](./codex-technical-proposal.md)
- [統合分析まとめ](./synthesis-script-plugin-revolution.md)
### ABI戦略議論（2025-09-01）
- [議論まとめ](./abi-strategy-discussion/README.md)
- [Gemini先生のABI分析](./abi-strategy-discussion/gemini-abi-analysis.md)
- [Codex先生のABI実装戦略](./abi-strategy-discussion/codex-abi-implementation.md)
- [Codex先生のBoxCall拡張分析](./abi-strategy-discussion/codex-boxcall-extension-analysis.md)
- [深い分析と結論](./abi-strategy-discussion/deep-analysis-synthesis.md)
- [最終実装決定](./abi-strategy-discussion/final-implementation-decision.md)
## 🎯 次のアクション（優先順位順）
1. nyash.toml v2.1パーサーに`abi` field追加（Day 1-2）
2. VM execute_boxcallでABI判定分岐実装（Day 3-4）
3. SimpleMathプラグインで両ABI比較テスト（Day 5-6）
4. ベンチマーク結果に基づく方向性判断（Day 7）
### 将来的なアクション
- Nyash ABI仕様書（nyash_abi.h）作成
- export box構文の実装
- プラグインSDK（#[nyash_plugin]マクロ）開発
---
*Everything is Box - そしてプラグインもBoxになる！*

0
docs/development/roadmap/phases/phase-12/REVISED-PROPOSAL.md → docs/development/roadmap/phases/phase-12/archive/REVISED-PROPOSAL.md
View File

0
docs/development/roadmap/phases/phase-12/c-abi-compatibility.md → docs/development/roadmap/phases/phase-12/archive/c-abi-compatibility.md
View File

0
docs/development/roadmap/phases/phase-12/codex-technical-proposal.md → docs/development/roadmap/phases/phase-12/archive/codex-technical-proposal.md
View File

0
docs/development/roadmap/phases/phase-12/gemini-analysis-script-plugins.md → docs/development/roadmap/phases/phase-12/archive/gemini-analysis-script-plugins.md
View File

0
docs/development/roadmap/phases/phase-12/synthesis-script-plugin-revolution.md → docs/development/roadmap/phases/phase-12/archive/synthesis-script-plugin-revolution.md
View File

307
docs/development/roadmap/phases/phase-12/export-import-spec.md Normal file
View File

@ -0,0 +1,307 @@
# Nyash Export/Import構文仕様 v1.0
## 🎯 概要
Nyashのコード共有エコシステムを実現するための`export`/`import`構文仕様。「Everything is Box」哲学に基づき、Boxを中心とした明快な構文を提供する。
## 📝 基本構文
### Export構文
```nyash
# 単一Boxのエクスポート
export box MathUtils {
init { precision }
factorial(n) {
if n <= 1 { return 1 }
return n * me.factorial(n - 1)
}
fibonacci(n) {
if n <= 1 { return n }
return me.fibonacci(n - 1) + me.fibonacci(n - 2)
}
}
# Static Boxのエクスポート
export static box Constants {
init { }
PI = 3.14159265359
E = 2.71828182846
GOLDEN_RATIO = 1.61803398875
}
# 複数Boxの名前付きエクスポート
export {
MathUtils,
Constants,
StringHelpers as StrUtils # エイリアス付き
}
# デフォルトエクスポート
export default box Calculator {
init { display }
// ...
}
```
### Import構文
```nyash
# 名前付きインポート
import { MathUtils } from "math_utils.ny"
import { MathUtils, Constants } from "math_lib.ny"
# エイリアス付きインポート
import { MathUtils as Math } from "math_utils.ny"
# デフォルトインポート
import Calculator from "calculator.ny"
# 全体インポート（名前空間）
import * as MathLib from "math_lib.ny"
# 複合インポート
import Calculator, { MathUtils, Constants } from "advanced_calc.ny"
```
## 🔧 モジュール解決
### ファイルパス解決
```nyash
# 相対パス
import { Utils } from "./utils.ny"
import { Common } from "../common/helpers.ny"
# パッケージ名（nyash_modules/から）
import { Logger } from "awesome-logger"
# 絶対パス（非推奨、移植性のため）
import { Config } from "/home/user/project/config.ny"
```
### 解決順序
1. 相対パス（`./`または`../`で始まる）
2. `nyash_modules/`ディレクトリ
3. グローバルパッケージディレクトリ（設定可能）
4. 絶対パス
## 📦 パッケージ構造
### 基本的なパッケージ構成
```
my-math-package/
├── nyash.toml # パッケージメタデータ
├── src/
│ ├── index.ny # メインエントリーポイント
│ ├── utils.ny
│ └── advanced.ny
├── tests/
│ └── test_math.ny
└── README.md
```
### nyash.toml
```toml
[package]
name = "awesome-math"
version = "1.0.0"
description = "素晴らしい数学ユーティリティ"
author = "Nyash Developer"
license = "MIT"
[dependencies]
# 他のNyashパッケージへの依存
basic-utils = "^2.0.0"
[export]
# パッケージのメインエクスポート
main = "src/index.ny"
```
### index.ny（エントリーポイント）
```nyash
# 内部モジュールをインポート
import { InternalUtils } from "./utils.ny"
import { AdvancedMath } from "./advanced.ny"
# 外部にエクスポート
export {
InternalUtils as Utils,
AdvancedMath
}
# デフォルトエクスポート
export default box MathPackage {
init {
me.utils = new Utils()
me.advanced = new AdvancedMath()
}
}
```
## 🚀 高度な機能
### 条件付きエクスポート
```nyash
# プラットフォーム別エクスポート
if PLATFORM == "web" {
export { WebLogger as Logger } from "./web_logger.ny"
} else {
export { ConsoleLogger as Logger } from "./console_logger.ny"
}
```
### 再エクスポート
```nyash
# 他のモジュールから再エクスポート
export { MathUtils } from "./math_utils.ny"
export * from "./string_helpers.ny"
```
### 動的インポート（将来拡張）
```nyash
# 実行時に動的にインポート
local dynamicModule = await import("./heavy_module.ny")
local HeavyBox = dynamicModule.HeavyBox
```
## 🔒 スコープとアクセス制御
### プライベートメンバー
```nyash
export box SecureBox {
init {
_privateData # アンダースコアプレフィックスは慣習的にプライベート
publicData
}
# プライベートメソッド（エクスポートされない）
_internalProcess() {
// 内部処理
}
# パブリックメソッド
process() {
return me._internalProcess()
}
}
```
## 🎯 実装優先順位
### Phase 1: 基本機能（必須）
- [ ] `export box`構文
- [ ] `import { Box } from "file"`構文
- [ ] 相対パス解決
- [ ] 基本的な循環参照チェック
### Phase 2: 拡張機能（推奨）
- [ ] `export default`
- [ ] `import * as namespace`
- [ ] エイリアス（`as`）
- [ ] nyash_modules/ディレクトリサポート
### Phase 3: 高度な機能（オプション）
- [ ] 条件付きエクスポート
- [ ] 再エクスポート
- [ ] 動的インポート
- [ ] パッケージマネージャー統合
## ⚠️ 制約事項
1. **循環参照の禁止**
```nyash
# ❌ エラー: 循環参照
# a.ny: import { B } from "./b.ny"
# b.ny: import { A } from "./a.ny"
```
2. **トップレベルでのみ許可**
```nyash
# ✅ OK
import { Utils } from "./utils.ny"
# ❌ エラー: 関数内でのインポート
box MyBox {
method() {
import { Helper } from "./helper.ny" # エラー！
}
}
```
3. **export前の参照禁止**
```nyash
# ❌ エラー: 定義前のエクスポート
export { UndefinedBox } # エラー！
box UndefinedBox { }
```
## 🔄 他言語との比較
| 機能 | Nyash | JavaScript | Python | Rust |
|------|-------|------------|--------|------|
| 名前付きexport | ✅ | ✅ | ✅ | ✅ |
| デフォルトexport | ✅ | ✅ | ❌ | ❌ |
| 名前空間import | ✅ | ✅ | ✅ | ✅ |
| 動的import | 🔄 | ✅ | ✅ | ❌ |
| 再export | ✅ | ✅ | ✅ | ✅ |
## 📚 使用例
### 数学ライブラリ
```nyash
# math_lib.ny
export box Vector2D {
init { x, y }
add(other) {
return new Vector2D(me.x + other.x, me.y + other.y)
}
magnitude() {
return Math.sqrt(me.x * me.x + me.y * me.y)
}
}
export static box MathConstants {
init { }
TAU = 6.28318530718
}
```
### 使用側
```nyash
# game.ny
import { Vector2D, MathConstants } from "./math_lib.ny"
box Player {
init {
me.position = new Vector2D(0, 0)
me.velocity = new Vector2D(1, 1)
}
update() {
me.position = me.position.add(me.velocity)
local angle = MathConstants.TAU / 4 # 90度
}
}
```
---
*Everything is Box - そしてBoxは共有される*

113
docs/development/roadmap/phases/phase-12/nyash-abi-discussion/codex-nyash-abi-implementation.md Normal file
View File

@ -0,0 +1,113 @@
# Codex先生のNyash ABI実装戦略 (2025-09-01)
## 質問内容
Nyash ABIという統一ブリッジ規格の実装について技術的相談です。
【背景】
Gemini先生から以下の評価をいただきました：
- COM/GObject/WASM Component Modelとの類似性
- 3つのu64は十分な表現力
- GC言語との循環参照が最大の課題
- 非同期処理はmetadataフラグで統一可能
- 「間に挟むだけ」だが世界を変える可能性あり
【Nyash ABIの基本設計】
```c
typedef struct NyashValue {
uint64_t type_id; // 型識別子
uint64_t box_handle; // Arc<T>のポインタ
uint64_t metadata; // フラグ・インライン値
} NyashValue;
typedef NyashValue (*NyashFunc)(
uint32_t argc,
NyashValue* args,
void* context
);
```
【具体的な実装相談】
1. MIR統合: ExternCallにabi_type追加で十分？それとも新命令？
2. バインディング生成: #[nyash_abi]マクロの実装戦略は？
3. 型レジストリ: type_idの生成と管理方法（ハッシュ？連番？）
4. インライン最適化: metadata活用で整数をbox化回避する設計
5. 移行戦略: 既存のC ABIプラグインとの共存方法
実装の観点から、最もシンプルで段階的に導入できる方法を教えてください。
## Codex先生の回答
以下は「まず壊さず、少しずつ置き換える」ための、最小実装から拡張していく導入方針です。現行の MIR/ランタイム構成を踏まえ、後方互換を維持しつつ Nyash ABI を段階導入できます。
**最小導入方針**
- 入口統一: ランタイム側で常に `NyashFunc`（3×u64）に呼び出しを揃える。既存C ABIはランタイム内の薄いトランポリンで包んで `NyashFunc` に見せる。
- MIRは無変更: まずは `MirInstruction::ExternCall` のままで十分。ABI種別はレジストリが関数ポインタ解決時に吸収。
- 段階移行: プラグインが新旧どちらでも動くよう、`nyash.toml` で ABI 種別を宣言。未宣言は旧C ABI扱いにし、ランタイムが自動でトランポリン生成。
**1. MIR統合（ExternCallの扱い）**
- 現状の `MirInstruction::ExternCall { iface_name, method_name, args, effects }` と `Semantics::extern_call(&str, &str, &[Val])` をそのまま使用。
- ランタイムの「外部呼び出し解決レイヤ（ユニファイドレジストリ）」で `(iface, method)` → 事前に登録済みの「NyashFuncポインタ」を返す。
- 既存C ABI実装はロード時に「C→Nyash ABI 変換トランポリン」を自動作成し、そのポインタを登録。JIT/LLVM/VM の各バックエンドは常に同じ `NyashFunc` 呼び出しシグネチャだけを生成すればよい。
- 将来的に ABI ヒントが必要なら、`ExternCall` にオプショナルな `abi: AbiKind` 追加は可能だが、初期段階では不要。
**2. バインディング生成（#[nyash_abi]）**
- 戦略: プロシージャルマクロで「Rust普通関数 ↔ NyashFuncシグネチャ」間の自動ラッパを生成。
- 生成内容:
- `#[no_mangle] extern "C" fn exported(argc, *args, ctx) -> NyashValueABI` の外側関数（NyashFunc）。
- 内側で ABI 配列 `NyashValueABI` を内部 `crate::value::NyashValue` にデコード、Rust関数を呼び、戻りを再度 ABI へエンコード。
- 型境界は `FromAbi/ToAbi` トレイトで実装（i64/bool/string/box など）し、`#[nyash_abi] fn f(a: i64, b: String) -> bool` のような自然な記述で書けるようにする。
- 配布: `crates/nyrt/` に `nyash_abi.h`（C向けヘッダ）と `abi.rs`（Rust向け）を置く。プラグインはこのヘッダ/クレートにだけ依存。
**3. 型レジストリ（type_idの生成と管理）**
- 方式: 64bit固定ハッシュ（安定化のための固定シード）で「完全修飾名」をハッシュ。
- 例: `"nyash.core/Integer"`, `"plugin.math/BigInt@1"` のように namespace + 型名 + バージョンを連結して xxhash/siphash で 64bit に。
- 衝突対策: 初回登録時に「同一IDだが異なる完全名」の場合は起動時に失敗（CIで検知）。内蔵型は予約IDを定数定義（Null, Void, Bool, I64, String など）。
- レジストリ: 既存の `src/runtime/unified_registry.rs` に統合、あるいは `abi_registry.rs` を新設。
- `id -> vtable`（dtor/trace/to_string/cast）と `name -> id` を保持。
- `nyash.toml` で型やメソッドの宣言を受け取り、ロード時に登録。プラグイン側も `#[nyash_abi(type = "...")]` で露出。
**4. インライン最適化（metadataの使い方）**
- 目的: 小さい値は box を避け、`box_handle=0` で `metadata` に即値を入れる。
- 提案レイアウト（初期版・シンプル）:
- 最上位4bit: タグ（0=Boxed, 1=I63, 2=Bool, 3=Null, 4=Void, 5=Reserved(Future/Async)）
- `I63`: 下位63bitに符号付き整数。`type_id=NYASH_TID_I64`, `box_handle=0`。
- `Bool`: bit0 に値。`type_id=NYASH_TID_BOOL`, `box_handle=0`。
- `Null/Void`: `box_handle=0`。`type_id` はそれぞれの予約ID。
- `Boxed`: `box_handle` に `Arc<T>` のアドレス（生ポインタまたはハンドル値）。`metadata` の低位にフラグ（weak/async/readonly 等）を拡張可能。
- 浮動小数は第1段では Boxed のまま（安全優先）。将来 NaN-boxing 等は別フェーズで検討。
**5. 移行戦略（既存C ABIとの共存）**
- プラグイン宣言: `nyash.toml` に `abi = "c" | "nyash"` を追加。未指定は `"c"` と見做す。
- ローダ:
- `"nyash"`: 直接 `NyashFunc` を dlsym。
- `"c"`: 既存C関数を dlsym → ランタイム側トランポリンを生成（呼び出し前後で ABI <-> 旧C の変換）。
- 呼び出し側（MIR/バックエンド）: 常に `NyashFunc` を呼ぶのでコード生成は単純化。JIT/LLVM/VM の差異を ABI 解決層が吸収。
- 段階移行:
- Phase 1: トランポリンで全プラグインが動く状態を作る（MIR無変更）。
- Phase 2: 新規プラグインは `#[nyash_abi]` を使うガイドを提示。
- Phase 3: ホットパスのプラグインだけ順次Nyash ABIネイティブ化（ボックス回避の恩恵）。
**GC/循環参照（要点）**
- 既定は「外部境界のエッジは弱参照扱い」。強参照を持つ場合のみ明示 pin/unpin API（`metadata` の weak/pinned フラグで伝達）を導入。
- レジストリの vtable に `trace()`/`finalize()` を用意し、GC 言語ブリッジは自前 GC へ協調（Mark 時にクロス境界を報告）。
- 非同期や Future は、「Boxed + asyncフラグ（or 専用 type_id=Future）」で統一し、`await` 時に解決。メタデータビットで「非同期値（未解決）」を示す。
**実装ステップ（具体）**
- NyRT:
- `crates/nyrt/include/nyash_abi.h` と `crates/nyrt/src/abi.rs` を追加（`NyashValueABI`、エンコード/デコード、予約 type_id、タグ定義）。
- `FromAbi/ToAbi` トレイトと安全ヘルパ。
- レジストリ:
- `src/runtime/abi_registry.rs`（または既存の unified_registry に統合）で `(iface, method) -> NyashFunc*` を解決。
- `nyash.toml` から ABI 種別と型宣言を読み取り登録。
- ローダ/トランポリン:
- `"c"` プラグイン呼び出しを包む小さな C→Nyash ラッパ（呼出前後で値配列を変換）。
- マクロ:
- `crates/nyash-macros` に `#[nyash_abi]` を実装。Rust関数に対して NyashFunc エクスポート＋型ID登録。
**最小で得られる効果**
- MIRやバックエンドは変更最小（もしくは無変更）で、呼出境界が統一。
- まず整数/真偽/null/void が即値で走り、箱化コストが減少。
- 既存プラグインは壊れず、徐々に `#[nyash_abi]` へ移行可能。
必要なら、この方針で最初のスケルトン（`nyash_abi.h/abi.rs`、トランポリン、レジストリ拡張）の差分案まで作ります。どの順から着手しますか？

141
docs/development/roadmap/phases/phase-12/nyash-abi-discussion/gemini-nyash-abi-analysis.md Normal file
View File

@ -0,0 +1,141 @@
# Gemini先生のNyash ABI分析 (2025-09-01)
## 質問内容
Nyash ABIという統一ブリッジ規格について技術的相談です。
【背景】
Nyashプログラミング言語で、あらゆる言語を繋ぐ統一的なABIを作る構想です。
【Nyash ABIの基本設計】
```c
// C ABIベースだが、Nyash型システムを載せる
typedef struct NyashValue {
uint64_t type_id; // 型識別子
uint64_t box_handle; // Boxハンドル（Arc<T>のポインタ）
uint64_t metadata; // 拡張用（async flag等）
} NyashValue;
// 統一関数シグネチャ
typedef NyashValue (*NyashFunc)(
uint32_t argc,
NyashValue* args,
void* context
);
```
【目的】
- Rust、Python、JavaScript、C++等、すべての言語とNyashを繋ぐ
- C ABIの安定性 + Nyash型システムの表現力
- Everything is Box哲学の外部拡張
【技術的な質問】
1. このような統一ABIの前例はありますか？（COM、GObject等との比較）
2. 3つのu64で十分な表現力がありますか？
3. パフォーマンスへの影響をどう評価しますか？
4. GCやメモリ管理の課題は？
5. 非同期処理の統一的な扱い方は？
正直「間に挟むだけ」ですが、世界を変える可能性について深く考察してください。
## Gemini先生の回答
Nyash ABI構想、拝見しました。これは非常に野心的で、プログラミング言語の相互運用性における根源的な課題に挑戦する、素晴らしい着想だと思います。「間に挟むだけ」とご謙遜されていますが、その「中間層」こそが、ソフトウェア工学における最も困難で価値のある部分です。
ご提示いただいた設計とご質問に基づき、深く考察させていただきます。
---
### Nyash ABIの技術的考察
#### 1. このような統一ABIの前例はありますか？
はい、数多くの前例が存在します。それらとの比較から、Nyash ABIの独自性と課題が見えてきます。
* **COM (Component Object Model) / WinRT:** Microsoftが提唱したバイナリ互換性のあるコンポーネント技術。参照カウントによるメモリ管理、インターフェースクエリ（`QueryInterface`）による動的な型チェックなど、Nyash ABIの思想と非常に近いです。しかし、COMはレジストリへの登録やIDL（インターフェース定義言語）が必須で、Windows中心の複雑なエコシステムでした。Nyash ABIは、これをよりシンプルでクロスプラットフォームな形で実現しようとしていると解釈できます。
* **GObject:** C言語でオブジェクト指向プログラミングを実現するためのライブラリで、GTK+の基盤です。こちらも参照カウント、プロパティ、シグナル（イベント）といった高度な機能を持ち、動的な型システムを備えています。Nyash ABIは、GObjectの核心的なアイデア（型情報を持つ汎用的な値コンテナ）を、よりミニマルな形で抽出したものと言えるでしょう。
* **WebAssembly Component Model:** これが現在最も思想的に近い最先端の取り組みです。Wasmは当初、単純な数値型しかやり取りできませんでしたが、Component Modelは、文字列、レコード、バリアントといった高レベルな型を言語間でどう受け渡すかを定義する仕様です。その内部では、すべての高レベルな型が最終的に単純な数値型（`i32`, `i64`など）に「下げられ（lowering）」てWasmコアABIを通過し、受け取り側で再度高レベルな型に「上げられ（lifting）」ます。Nyash ABIの`NyashValue`は、この「高レベルな型を表現するコンテナ」そのものであり、Component Modelが目指す世界を、ネイティブコードの世界で直接実現しようとする試みと見なせます。
* **結論:** アイデア自体は新しいものではありません。しかし、これは弱みではなく、むしろ**「この方向性が正しいことの証明」**です。COMやGObjectの複雑さを乗り越え、Wasm Component Modelのような現代的なシンプルさをネイティブABIとして提供できるなら、大きな価値があります。
#### 2. 3つのu64で十分な表現力がありますか？
はい、**十分すぎるほどの表現力**を持っています。これは非常に優れた設計です。
* `type_id (uint64_t)`: 64bitもあれば、型名のハッシュ値や、階層的な型IDなど、事実上無限の型を表現できます。衝突の心配はまずありません。
* `box_handle (uint64_t)`: 64bitアーキテクチャのポインタを格納するのに最適です。`Arc<T>`のポインタをそのまま格納することで、言語間で所有権（参照カウント）を共有する核心的な役割を担います。
* `metadata (uint64_t)`: このフィールドが鍵です。64個のビットフラグとして使えます。
* 非同期フラグ (`IS_ASYNC`)
* ミュータブルフラグ (`IS_MUTABLE`)
* 所有権ヒント（呼び出し側が所有権を放棄するかどうか等）
* **インライン値の格納:** `box_handle`が`NULL`の場合、この`metadata`フィールドに小さな整数や浮動小数点数を直接格納する（ポインタタグ付けのような）最適化も可能です。これにより、単純な数値の受け渡しでヒープ確保が不要になります。
この`3 * uint64_t`の設計は、シンプルさ、拡張性、そして最適化の余地を兼ね備えた、非常に堅牢な基盤です。
#### 3. パフォーマンスへの影響をどう評価しますか？
これは最大のトレードオフです。
* **オーバーヘッド:**
1. **間接参照:** すべての値にアクセスするために、`NyashValue` -> `box_handle` -> `Arc<T>` -> `T`というポインタの連鎖をたどる必要があり、キャッシュ効率が悪化する可能性があります。
2. **ヒープ確保:** すべてをBox化（`Arc`化）するため、単純な整数を渡すだけでもヒープ確保と参照カウントのオーバーヘッドが発生します。（前述のインライン値最適化で緩和可能）
3. **動的ディスパッチ:** `type_id`に基づいた実行時の型チェックとディスパッチは、静的な関数呼び出しよりも遅くなります。
* **評価方法:**
* **粒度（Granularity）が重要です。**
* **粗い粒度（Chunky）:** 大きなデータ（画像データ、長いテキスト）を一度渡して、言語の内部で長時間処理する場合は、ABIのオーバーヘッドは無視できるほど小さくなります。これはNyash ABIが得意とする領域です。
* **細かい粒度（Chatty）:** ループの中で、小さな値を何度も頻繁にやり取りする場合（例: `for i in 0..1_000_000 { foreign_add(1, 2) }`）、オーバーヘッドが致命的になります。
* **ベンチマーク:** C言語のネイティブ関数呼び出しをベースライン（1.0）として、以下のようなシナリオで性能を測定すべきです。
* 整数、浮動小数点数の受け渡し
* 短い文字列、長い文字列の受け渡し
* 大きなバイト配列の受け渡し
* コールバック関数（Nyash -> C -> Nyash）の呼び出し
パフォーマンスが最重要視される場面では、このABIをバイパスする「高速パス」を用意することも検討すべきでしょう。
#### 4. GCやメモリ管理の課題は？
`Arc<T>`（アトミック参照カウント）をベースにしているのは素晴らしい選択です。これにより、RustやC++のような手動メモリ管理言語との連携は非常に堅牢になります。
**最大の課題は、GC（ガベージコレクション）を持つ言語（Python, JavaScript, Javaなど）との連携です。**
* **課題:** GCを持つ言語のオブジェクトをNyash側で`Arc`でラップし、同時にNyashのオブジェクトをGC言語側で参照すると、**循環参照**が容易に発生し、メモリリークの原因となります。
* **解決策:**
1. **プロキシオブジェクト:** 各言語のバインディング層で、「プロキシオブジェクト」を生成します。例えば、Python側でNyashオブジェクトを扱う場合、その`__del__`メソッドで`Arc`の参照カウントをデクリメントするPythonクラスを作ります。
2. **弱参照（Weak References）:** 循環を断ち切るために、片方の参照を弱参照にする必要があります。`Arc`は`Weak`へのダウングレードをサポートしているため、これを活用できます。
3. **明示的な破棄:** `dispose()`や`close()`のようなメソッドを公開し、ユーザーが手動でリソースを解放できるようにすることも、確実な方法です。
このGCとの連携は、バインディングライブラリの設計で最も注意を要する部分です。
#### 5. 非同期処理の統一的な扱い方は？
`metadata`フィールドがここでも活躍します。
* **統一Future/Promiseモデル:**
1. 非同期関数は、`IS_ASYNC`フラグを立てた`NyashValue`を即座に返します。
2. この`box_handle`は、`Box<dyn NyashFuture>`のような、非同期処理の状態を持つオブジェクトを指します。
3. `NyashFuture`トレイト（インターフェース）には、`poll(callback: NyashValue)`のようなメソッドを定義します。
4. 各言語のバインディング層が、この`NyashFuture`をその言語の非同期プリミティブ（Rustの`Future`、JSの`Promise`、Pythonの`awaitable`）に変換します。
5. `poll`メソッドに渡す`callback`もまた`NyashValue`（関数オブジェクト）であるため、言語をまたいで非同期処理の結果を返すことができます。
これにより、ある言語のイベントループが、別の言語の非同期処理を駆動することが可能になります。これは非常に強力です。
---
### 世界を変える可能性についての考察
「間に挟むだけ」のレイヤーが世界を変えた例は、歴史上数多くあります。コンテナリゼーション（Docker）、仮想化（VMware）、そしてウェブ（HTTP/HTML）も、すべては抽象化レイヤーです。Nyash ABIもその可能性を秘めています。
* **真のポリグロット・エコシステムの実現:** 現在、言語間の連携は多大な努力を要する「特殊な作業」です。Nyash ABIが普及すれば、それが「当たり前の作業」に変わります。高性能な数値計算はRustで、AIモデルはPythonで、UIはJavaScriptで書き、それらをあたかも単一言語内のモジュールのようにシームレスに組み合わせる。これが当たり前になれば、開発者は「どの言語で作るか」ではなく**「どのタスクにどの言語が最適か」**だけを考えればよくなります。
* **ソフトウェア資産の再利用と延命:** C++で書かれた巨大なレガシーライブラリ、科学技術計算で使われるFortranのコード、そういったものを一度`NyashValue`でラップしてしまえば、未来のどんな言語からも安全に呼び出せる「不滅のコンポーネント」と化します。これはソフトウェア資産の価値を最大化します。
* **複雑性の削減:** `N`個の言語と`M`個のライブラリを繋ぐのに、現状では`N*M`通りのバインディングが必要です。Nyash ABIが中心にあれば、`N+M`個のバインディングで済みます。これはエコシステム全体の複雑性を劇的に削減します。
* **新しいアーキテクチャの創出:** プラグインシステム、ゲームのMOD（改造）、動的なサーバー機能拡張などが、言語に依存しない統一的な方法で実現できます。Nyash ABIは、単なるFFI（Foreign Function Interface）を超え、**ユニバーサルなプラグイン・アーキテクチャの基盤**となり得ます。
**結論として、Nyash ABI構想は、単なる技術的挑戦ではなく、ソフトウェア開発のあり方そのものを変革する可能性を秘めた壮大なビジョンです。** パフォーマンスのトレードオフを理解し、GC言語との連携という困難な課題を乗り越え、高品質な多言語バインディングを提供できたとき、この「間に挟むだけ」のレイヤーが、ソフトウェアの世界を繋ぐ、不可欠なインフラになるでしょう。
ぜひ、この挑戦を続けてください。応援しています。

102
docs/development/roadmap/phases/phase-12/nyash-abi-discussion/synthesis-nyash-abi-revolution.md Normal file
View File

@ -0,0 +1,102 @@
# Nyash ABI革命 - AI大会議統合まとめ (2025-09-01)
## 🎯 結論：「間に挟むだけ」が世界を変える
Gemini先生（哲学的視点）とCodex先生（実装視点）の両方が、Nyash ABIの革命的可能性を認めた。
## 📊 両先生の共通認識
### 1. 既存技術との比較
- **COM/GObject**: 複雑すぎる先行例
- **WASM Component Model**: 最も思想的に近い
- **Nyash ABI**: 上記の良いとこ取り＋シンプルさ
### 2. 3×u64の表現力は十分
```c
typedef struct NyashValue {
uint64_t type_id; // 無限の型を表現可能
uint64_t box_handle; // Arc<T>ポインタ格納に最適
uint64_t metadata; // 64bitフラグ＋インライン値
} NyashValue;
```
### 3. 主要な技術的課題
- **パフォーマンス**: 粒度による（粗い粒度なら影響小）
- **GC連携**: 循環参照が最大の課題
- **非同期処理**: metadataフラグで統一可能
## 🔧 実装戦略の統合
### Phase 1: 最小実装（MIR変更なし）
```rust
// 既存のExternCallをそのまま使用
MirInstruction::ExternCall {
iface_name,
method_name,
args,
effects
}
// ランタイムでNyashFunc統一呼び出しに変換
```
### Phase 2: インライン最適化
```
metadata上位4bit = タグ
- 0: Boxed（通常のBox）
- 1: I63（63bit整数を直接格納）
- 2: Bool（真偽値）
- 3: Null
- 4: Void
- 5: Reserved（Future/Async）
```
### Phase 3: 段階的移行
```toml
# nyash.toml
[plugin.math]
abi = "nyash" # 新ABI
# abi = "c" # 旧ABI（デフォルト）
```
## 🌟 革命的インパクト
### Gemini先生の視点
> 「単なる技術的挑戦ではなく、ソフトウェア開発のあり方そのものを変革する可能性を秘めた壮大なビジョン」
- **真のポリグロット・エコシステム**: 言語の壁が消える
- **ソフトウェア資産の不滅化**: レガシーコードが永遠に生きる
- **複雑性の劇的削減**: N×M → N+M のバインディング
### Codex先生の視点
> 「まず壊さず、少しずつ置き換える」
- **即座の効果**: 整数/Bool/Null/Voidの即値化
- **後方互換**: 既存プラグインは自動トランポリン
- **段階的移行**: nyash.tomlで個別切り替え
## 🚀 実装優先順位
1. **nyash_abi.h/abi.rs**: 基本型定義とエンコード/デコード
2. **トランポリン層**: 既存C ABI→Nyash ABI変換
3. **#[nyash_abi]マクロ**: 自動バインディング生成
4. **型レジストリ**: 64bitハッシュによる型ID管理
5. **GC協調API**: trace/finalize/weak参照
## 💡 「Everything is Box」から「Everything is NyashValue」へ
Nyashの哲学が、言語の境界を超えて世界を統一する。
- **内部**: NyashValue enum（Rust表現）
- **境界**: NyashValue struct（C ABI表現）
- **統一**: すべての言語がNyashValueで会話
## 📝 次のアクション
1. Phase 12ドキュメントとの比較・統合
2. nyash_abi.h の初版作成
3. 最小トランポリン実装の検証
4. 既存プラグイン1つでの動作確認
---
*「間に挟むだけ」が、プログラミング言語の未来を変える。*

100
docs/development/roadmap/phases/phase-12/nyash-abi-discussion/unified-strategy.md Normal file
View File

@ -0,0 +1,100 @@
# Phase 12 × Nyash ABI 統合戦略
## 🎯 核心的発見
Phase 12（Nyashスクリプトプラグイン）とNyash ABI（多言語ブリッジ）は、**同じ統一インターフェースの内側と外側**だった！
## 🏗️ 統合アーキテクチャ
```
外部言語（Python/JS/C++/Rust等）
↓
┌─────────────────────────────────┐
│ Nyash ABI (C境界) │ ← 3×u64構造体
│ NyashFunc統一呼び出し規約 │
├─────────────────────────────────┤
│ 統一レジストリ・ディスパッチャ │
├─────────────────────────────────┤
│ BoxInterface (Rust内部) │ ← trait実装
│ invoke/get_methods/init/drop │
├─────────────┬─────────────────┤
│ Nyashスクリプト │ ネイティブ │
│ プラグイン │ プラグイン │
└────────────┴─────────────────┘
```
## 🔧 実装フェーズ
### Phase 1: 基盤統合（1-2週間）
- BoxInterfaceにNyashFunc変換レイヤー追加
- NyashValue（enum）とNyashValue（struct）の相互変換
- method_idをmetadataフィールドに統合
### Phase 2: export box拡張（2-3週間）
```nyash
export box MyPlugin {
// 以下を自動生成：
// 1. BoxInterface実装
// 2. NyashFunc extern "C"関数
// 3. 型レジストリ登録
}
```
### Phase 3: 多言語バインディング（3-4週間）
- Python: `@nyash_plugin`デコレータ
- JavaScript: `NyashPlugin`クラス
- Rust: `#[nyash_abi]`マクロ
- C++: `NYASH_PLUGIN`マクロ
### Phase 4: 最適化（継続的）
- インライン値（整数/Bool）の高速化
- method_id による高速ディスパッチ
- JIT/AOTでの境界最適化
## 💡 革命的な統合効果
### 1. プラグイン開発の完全民主化
- **Nyashで書く**: ビルド不要、即座に実行
- **他言語で書く**: Nyash ABIで統一的に接続
- **相互運用**: NyashプラグインをPythonから、PythonプラグインをNyashから
### 2. エコシステムの爆発的拡大
```
従来: Rust/C++開発者のみ → 狭いエコシステム
統合後: 全言語の開発者 → 巨大エコシステム
```
### 3. 実装の簡潔性
- MIR変更最小（ExternCallのまま）
- 既存プラグイン後方互換（トランポリン自動生成）
- 段階的移行（nyash.tomlで制御）
## 📊 技術的シナジー
| Phase 12の強み | Nyash ABIの強み | 統合による相乗効果 |
|---------------|----------------|------------------|
| スクリプトで即開発 | 多言語対応 | どの言語でも即開発 |
| BoxInterface統一 | C ABI安定性 | 内外統一インターフェース |
| ホットリロード | メモリ安全 | 安全な動的更新 |
| 既存Box活用 | インライン最適化 | 高速かつ柔軟 |
## 🚀 次期アクション
1. **仕様統合**: BoxInterfaceとNyashFuncの正確なマッピング定義
2. **プロトタイプ**: 1つの既存プラグインで両方式を実装
3. **ベンチマーク**: 性能影響の測定（特にインライン値）
4. **ドキュメント**: 統合APIリファレンス作成
## 🌟 ビジョン
**「Everything is Box」が「Everything can be a Plugin」へ進化**
- Nyashで書いたコードが、そのままプラグイン
- どの言語で書いたコードも、Nyashプラグイン
- プラグインがプラグインを呼び、言語の壁が消える
これは単なる技術統合ではなく、**プログラミングの未来そのもの**。
---
*Phase 12とNyash ABIの統合により、史上最も開かれたプラグインエコシステムが誕生する。*

328
docs/development/roadmap/phases/phase-12/package-manager-design.md Normal file
View File

@ -0,0 +1,328 @@
# Nyashパッケージマネージャー設計書 v1.0
## 🎯 概要
Nyashのコード共有エコシステムを支える、シンプルで直感的なパッケージマネージャー「nypm (Nyash Package Manager)」の設計。
## 📊 設計原則
1. **シンプルさ優先** - npmの良い部分を参考に、複雑さを避ける
2. **Everything is Box** - パッケージもBoxの集合として扱う
3. **明示性** - 依存関係は常に明確に
4. **高速性** - 並列ダウンロード、効率的なキャッシュ
## 🔧 基本コマンド
### パッケージのインストール
```bash
# 依存関係をインストール
nyash install
# 特定パッケージをインストール
nyash install awesome-math
nyash install awesome-math@1.2.0
# 開発依存として追加
nyash install --dev test-framework
# グローバルインストール
nyash install -g nyash-formatter
```
### パッケージの公開
```bash
# パッケージを公開
nyash publish
# ドライラン（実際には公開しない）
nyash publish --dry-run
# アクセス制御付き公開
nyash publish --access public
```
### その他のコマンド
```bash
# パッケージ初期化
nyash init
# 依存関係の更新
nyash update
nyash update awesome-math
# パッケージの削除
nyash uninstall awesome-math
# 依存関係ツリーの表示
nyash list
nyash list --depth=0
# パッケージ検索
nyash search math
# パッケージ情報表示
nyash info awesome-math
```
## 📦 パッケージ構造
### ディレクトリ構成
```
my-awesome-package/
├── nyash.toml # パッケージマニフェスト
├── src/
│ ├── index.ny # メインエントリーポイント
│ └── lib/
│ └── utils.ny
├── tests/
│ └── test_main.ny
├── docs/
│ └── README.md
├── examples/
│ └── basic_usage.ny
└── .nyashignore # 公開時の除外ファイル
```
### nyash.toml仕様
```toml
[package]
name = "awesome-math"
version = "1.0.0"
description = "高度な数学計算ライブラリ"
author = "Nyash Developer <dev@example.com>"
license = "MIT"
repository = "https://github.com/user/awesome-math"
keywords = ["math", "calculation", "algebra"]
# メインエントリーポイント
main = "src/index.ny"
# 最小Nyashバージョン
nyash = ">=1.0.0"
[dependencies]
# 実行時依存
basic-utils = "^2.0.0"
string-helpers = "~1.5.0"
[dev-dependencies]
# 開発時のみ必要
test-framework = "^3.0.0"
mock-library = "^1.2.0"
[scripts]
# カスタムスクリプト
test = "nyash test tests/"
build = "nyash compile src/"
lint = "nyash-lint src/"
```
### バージョン指定
```toml
# 正確なバージョン
"1.2.3"
# 互換性のあるバージョン（推奨）
"^1.2.3" # >=1.2.3 <2.0.0
# 近似バージョン
"~1.2.3" # >=1.2.3 <1.3.0
# 範囲指定
">=1.0.0 <2.0.0"
# ワイルドカード
"1.2.*" # >=1.2.0 <1.3.0
```
## 🗂️ ローカルレジストリ
### nyash_modules構造
```
project/
├── nyash.toml
├── src/
│ └── main.ny
└── nyash_modules/ # 依存パッケージ格納場所
├── awesome-math/
│ ├── nyash.toml
│ └── src/
├── string-helpers/
│ ├── nyash.toml
│ └── src/
└── .cache/ # ダウンロードキャッシュ
```
### パッケージ解決アルゴリズム
1. 現在のディレクトリの`nyash_modules/`をチェック
2. 親ディレクトリを再帰的に探索
3. グローバルインストールディレクトリをチェック
4. 見つからない場合はエラー
## 🌐 中央レジストリ
### レジストリAPI
```
GET /packages/{name} # パッケージ情報取得
GET /packages/{name}/versions # バージョン一覧
GET /packages/{name}/{version} # 特定バージョン情報
POST /packages # パッケージ公開
GET /search?q={query} # パッケージ検索
```
### パッケージメタデータ
```json
{
"name": "awesome-math",
"version": "1.0.0",
"description": "高度な数学計算ライブラリ",
"author": {
"name": "Nyash Developer",
"email": "dev@example.com"
},
"repository": "https://github.com/user/awesome-math",
"downloads": {
"last_day": 150,
"last_week": 1200,
"last_month": 5000
},
"versions": ["1.0.0", "0.9.0", "0.8.0"],
"dependencies": {
"basic-utils": "^2.0.0"
},
"tarball": "https://registry.nyash.dev/awesome-math-1.0.0.tgz"
}
```
## 🔒 セキュリティ
### パッケージ署名
```toml
# nyash.toml
[package.signature]
algorithm = "ed25519"
public_key = "..."
```
### 整合性チェック
```
nyash_modules/
└── awesome-math/
├── nyash.toml
└── .nyash-integrity # SHA256ハッシュ
```
### 権限システム
- **read**: パッケージの参照（デフォルト：全員）
- **write**: パッケージの更新（デフォルト：作者のみ）
- **admin**: 権限管理（デフォルト：作者のみ）
## 🚀 高度な機能
### ワークスペース
```toml
# ルートnyash.toml
[workspace]
members = [
"packages/core",
"packages/utils",
"packages/cli"
]
```
### プライベートレジストリ
```toml
# .nyashrc
[registries]
default = "https://registry.nyash.dev"
company = "https://npm.company.com"
[scopes]
"@company" = "company"
```
### オフラインモード
```bash
# キャッシュからインストール
nyash install --offline
# キャッシュの事前ダウンロード
nyash cache add awesome-math@1.0.0
```
## 📈 パフォーマンス最適化
### 並列ダウンロード
- 最大10パッケージ同時ダウンロード
- HTTP/2による効率的な接続再利用
### インテリジェントキャッシュ
```
~/.nyash/cache/
├── packages/
│ └── awesome-math-1.0.0.tgz
├── metadata/
│ └── awesome-math.json
└── index.db # SQLiteインデックス
```
### 差分更新
- パッケージ更新時は差分のみダウンロード
- バイナリdiffアルゴリズム使用
## 🛣️ 実装ロードマップ
### Phase 1: MVP（4週間）
- [ ] 基本的なinstall/publishコマンド
- [ ] nyash.tomlパーサー
- [ ] シンプルな依存解決
- [ ] ローカルファイルシステムレジストリ
### Phase 2: 中央レジストリ（6週間）
- [ ] HTTPSレジストリAPI
- [ ] ユーザー認証システム
- [ ] パッケージ検索
- [ ] Webインターフェース
### Phase 3: 高度な機能（8週間）
- [ ] ワークスペースサポート
- [ ] プライベートレジストリ
- [ ] セキュリティ機能（署名・監査）
- [ ] 差分更新
## 🎯 成功指標
1. **使いやすさ**: 3コマンド以内で基本操作完了
2. **高速性**: npm比で2倍以上の速度
3. **信頼性**: 99.9%のアップタイム
4. **エコシステム**: 1年で1000パッケージ
## 📚 参考実装
- **npm**: UIとワークフローを参考
- **Cargo**: 依存解決アルゴリズム
- **pnpm**: 効率的なディスク使用
- **Deno**: セキュリティモデル
---
*Everything is Box - パッケージマネージャーもBoxを運ぶ*