phase15: add Cranelift AOT design, LinkerBox spec, and smoke skeleton docs (handoff)

docs/interfaces/cranelift-aot-box.md

@@ -0,0 +1,57 @@
+CraneliftAotBox インタフェース草案（Phase 15 準備）
+
+前提
+- 本ブランチでは「仕様化（ドキュメント）」のみ行い、実装は別ブランチ `phase-15/self-host-aot-cranelift` で行う。
+- Cargo フィーチャ: `cranelift-aot = ["dep:cranelift-object"]` を追加し、同フィーチャ時のみ AOT モジュールを有効化する。
+
+モジュール構成（案）
+- パス: `src/backend/cranelift/aot_box.rs`
+- 依存: `cranelift-object`（オブジェクト出力）、既存のオブジェクトビルダ/ヘルパを再利用可能なら抽象化して流用。
+
+公開型（案）
+- `pub struct CraneliftAotConfig {`
+  - `pub opt_level: u8`  // 0..3 程度（実装は後続）
+  - `pub target: Option<String>` // target triple 等（未指定でホスト）
+`}`
+
+- `pub struct CraneliftAotBox {`
+  - `obj: <object builder>`
+  - `cfg: CraneliftAotConfig`
+`}`
+
+- `#[derive(Debug)] pub enum CraneliftAotError {`
+  - `Codegen(String)`, `IO(String)`
+`}`
+
+主要メソッド（案）
+- `impl CraneliftAotBox {`
+  - `pub fn new(cfg: CraneliftAotConfig) -> Result<Self, CraneliftAotError>`
+  - `pub fn compile_stub_ny_main_i64(&mut self, val: i64, out_obj: impl AsRef<Path>) -> Result<(), CraneliftAotError>`
+    - 役割: PoC。`ny_main` 関数を定義し、即値 `val` を返すオブジェクトを生成。
+  - `pub fn compile_mir_to_obj(&mut self, mir: MirModule, out_obj: impl AsRef<Path>) -> Result<(), CraneliftAotError>`
+    - 役割: P1〜。最小 MIR（`const_i64`/`add_i64`/`ret`）から CLIF を組み立てて出力。
+`}`
+
+使用例（PoC フロー）
+1) NyRT ビルド: `cargo build -p nyrt --release`
+2) オブジェクト出力（CLIイメージ）:
+   - `nyash --backend cranelift-aot --poc-const 42 apps/hello/main.nyash -o ny_main.o`
+3) リンク:
+   - Linux: `cc -o app ny_main.o target/release/libnyrt.a -ldl -lpthread`
+   - Windows: `link ny_main.obj nyrt.lib /OUT:app.exe`
+4) 実行: `./app` → `Result: 42` を確認。
+
+エラーモデル（案）
+- 環境・設定: フィーチャ未有効や未対応ターゲット → 分かりやすいメッセージ。
+- 生成・出力: `CraneliftAotError::Codegen(_)`／`CraneliftAotError::IO(_)` で大別。
+
+補助スクリプトの仕様（設計のみ）
+- ファイル: `tools/aot_smoke_cranelift.sh`
+- 目的: `.o/.obj` を生成→リンク→実行して PoC を自動検証。
+- 主要引数: `apps/APP/main.nyash -o app`、必要に応じ `--const` を透過的に渡す。
+
+今後の拡張（非ブロッキング）
+- NyRT の外部関数呼び出し（checkpoint など）の導入。
+- MIR 命令カバレッジの拡大、BoxCall/Plugin 経由の I/O。
+- ターゲットトリプルとオブジェクト形式の明示的制御。
+

docs/interfaces/linker-box.md

@@ -0,0 +1,48 @@
+LinkerBox 仕様（Phase 15 準備 / Windows優先）
+
+目的
+- AOT 生成されたオブジェクト（`.o/.obj`）を NyRT とリンクして実行可能ファイルを得る統一レイヤ。
+- 初期実装は「外部リンカー呼び出し」（MSVC `link.exe` または `lld-link`、Unix は `cc`）で動作し、将来的に lld 内蔵連携へ置換可能な設計とする。
+
+前提／エントリポイント
+- 既定のエントリポイントは NyRT 側の `main()`（`crates/nyrt` に実装）。
+- AOT 側は `ny_main`（想定: `() -> i64`）を定義し、NyRT の `main()` が `ny_main()` を呼び出す。
+- よって通常は `/ENTRY:` 指定は不要（NyRT をリンクしない特殊構成でのみ上書き可能とする）。
+
+入力と出力
+- 入力: 一つ以上のオブジェクト（`.obj`/`.o`）、追加ライブラリ群、ライブラリ検索パス。
+- 既定ライブラリ: NyRT（Windows: `nyrt.lib`、Unix: `libnyrt.a`）。
+- 出力: 実行ファイル（Windows: `*.exe`、Unix: 実行ビット付きバイナリ）。
+
+環境変数（LinkerBox が解釈）
+- `NYASH_LINKER`: 使用リンカーを強制。`link` | `lld-link` | `cc`（未指定は OS/環境から自動推定）
+- `NYASH_LINK_FLAGS`: 追加フラグ（空白区切り）。
+- `NYASH_LINK_VERBOSE=1`: 実コマンドラインを表示。
+- `NYASH_LINK_ENTRY=<symbol>`: エントリポイントを明示的に指定（既定は未指定で NyRT の `main` を使用）。
+- `NYASH_LINK_OUT=<path>`: 出力先を明示的に指定（CLI引数 `-o` が優先）。
+
+Windows（MSVC / lld-link）
+- 既定探索順: `link.exe` → `lld-link`。
+- 代表フラグ:
+  - `link.exe`: `/OUT:<exe>` `/SUBSYSTEM:CONSOLE`（既定） `/LIBPATH:<dir>` `nyrt.lib` 他
+  - `lld-link`: `-OUT:<exe>` `-SUBSYSTEM:CONSOLE` `-LIBPATH:<dir>` `nyrt.lib`
+- `PATH`/`LIB`/`LIBPATH` の整合に注意（Developer Command Prompt を推奨）。
+
+Unix（参考）
+- 代表フラグ: `cc -o <exe> <objs...> <lib paths> -L... -lnyrt -ldl -lpthread`
+- 既定のオブジェクト形式/ターゲットはホストに従う。
+
+CLI API（想定）
+- `nyash --linker link|lld-link|cc --libpath <dir> --lib nyrt [--entry nyash_main] -o app <objs...>`
+- AOT パスでは内部的に LinkerBox を呼び出し、上記環境変数も透過的に反映する。
+
+エラー方針
+- ツールチェーン未検出（リンカー不在）: わかりやすい対処案を表示（MSVC のセットアップ／lld の導入）。
+- 未解決シンボル: `ny_main`/NyRT 関連の欠落を優先表示。
+- 引数/パスのクォート: 空白を含むパスは安全にクォートして実行。
+
+将来拡張
+- 内蔵 lld を採用した一体化（外部プロセス呼び出しからの置換）。
+- ターゲットトリプルの明示指定とクロスリンク（フェーズ後半）。
+- 追加ランタイムやプラグイン静的リンクのオプション化。
+