# Phase 10.6 → Pythonネイティブ接続プラン（整理版 / txt）

目的: 10.6で整えたThread-Safety/Schedulerの最小足場の上に、Pythonプラグイン（PyRuntimeBox/PyObjectBox）をネイティブEXE（AOT）まで安定接続する。

====================
1) 到達イメージ（DoD）
====================
- Linux/Windows で以下が安定動作:
  - AOT: `examples/aot_py_min_chain.hako` → `Result: 4`（math.sqrt(16)）
  - VM: `examples/py_min_chain_vm.hako` → 4.0 表示（NYASH_PY_AUTODECODE=1）
  - returns_result 系サンプル（importR/getattrR/callR）で Ok/Err が期待通りに表示
- AOTビルドの配布体験が明確:
  - `tools/build_aot.{sh,ps1}` で .o → EXE、`nyash.toml`/plugins 解決、Windowsでは PATH/PYTHONHOME 調整
  - 配布ガイド（依存コピー/環境変数/動作確認手順）が `docs/guides/build/aot_quickstart.md` に追記済み

====================
2) 方針（変えない原則）
====================
- Plugin-First / Handle-First / TLV 統一（String/Integerはプリミティブ、Bufferはbytes(tag=7)、他はHandle(tag=8)）。
- Strict: 実行はVM、JITはAOT生成専用（フォールバック禁止）。
- by-name経路: 受け手箱名未確定時は `nyash_plugin_invoke_name_{getattr,call}_i64` で実行時解決。

====================
3) 実装タスク（M1→M5）
====================
M1: AOT最小ルートの安定（完了確認/微修正）
- nyrt シム：BufferBox→bytes(tag=7) 対応、3引数目以降をレガシーVM引数からTLV追補（暫定N引数）
- Windows探索：EXE起動時に PATH へ exe/`plugins/` を追加、`PYTHONHOME` が未設定なら `exe\python` を採用（相対はexe基準に正規化）
- ドキュメント：AOTクイックスタートにWindows注意点を追記（済）

M2: TLV/FFIカバレッジ拡大（最小）
- kwargs/辞書のパス（callKwR）をbytes(tag=7) or string(tag=6, JSON)で暫定対応（将来 BID-1拡張）
- N引数の一般化（invoke3→invokeN 設計、実装は段階導入。先行はレガシー補完で可）
- returns_result の統一処理（VM既存→AOTでも同等に扱う）

M3: Lowerer/Policy の整流
- Handle-First統一の確認：Python特化の型伝搬は撤去済み（戻りはHandle or プリミティブのみ参照）
- birth引数の一般化（TLVメモに沿い、Integer/Stringはプリミティブ、他はHandle）
- by-name の適用範囲と導線（`getattr`/`call` はby-name固定、importはmethod_id直参照）

M4: 配布導線とサンプル
- スクリプト整備：`tools/build_python_aot.sh` の統合（`build_aot.sh` に一本化 or ラッパー）
- サンプル最小化：returns_result（Ok/Err）、例外伝搬（Error文字列）、bytes引数、context共有（per-runtime globals）
- ガイド整理：`docs/guides/build/aot_quickstart.md` に「Pythonネイティブ」節を追加（動作要件・環境変数）

M5: 観測/CI（軽量）
- スモーク：VMチェーン / AOTチェーンの比較（Result行）を `tools/smoke_aot_vs_vm.sh` に追加（Python系は最小のみ）
- ログ：`NYASH_JIT_EVENTS*`/`NYASH_JIT_NATIVE_F64`/`NYASH_PY_AUTODECODE` による差分観測

====================
4) リスク/制約
====================
- CPython依存の配布：WindowsのDLL探索（PATH/PYTHONHOME）は最小整備。完全同梱（embedded）は後段で検討。
- KW/辞書のTLV表現：暫定はbytes/stringでブリッジ。正式BIDタグは将来導入（後方互換のためJSON連携を許容）。
- ネイティブN引数：v0はレガシーVM引数からのTLV補完でしのぎ、invokeNは次期導入。

====================
5) タイムライン（目安）
====================
- M1（安定）: 0.5日（確認/微修正）
- M2（TLV拡充）: 1–2日（kwargsは暫定・bytes/JSON）
- M3（Lowerer整流）: 0.5–1日
- M4（配布/サンプル）: 1日
- M5（観測/CI）: 0.5日

====================
6) 成果物（Artifacts）
====================
- 例: `examples/aot_py_min_chain.hako`, `examples/py_min_chain_vm.hako`（既存）
- ツール: `tools/build_aot.{sh,ps1}`（Python節）、`tools/smoke_aot_vs_vm.sh`（Python最小）
- Docs: `docs/guides/build/aot_quickstart.md`（Python節）、`docs/reference/abi/ffi_calling_convention_min.md`（bytes/N引数注記）

====================
7) 参照
====================
- 10.5c: Handle-First/PluginInvoke 設計（by-name シム）
- 10.5d/e: AOT統合/最終仕上げ（nyrt/Windows探索/TLV拡張）
- 10.6: Thread-Safety/Scheduler（並列化前の足場）

