# Phase 20.10 — Tasks (Script‑First Runner)

Status: In progress

Objectives
- Move orchestration/runner logic towards Hakorune scripts while keeping execution backends unchanged.
- Manage extern/effects and CLI/ENV policies with clear contracts and gates.

Focus Areas (Python は当面除外)
1) 実行エンジンとランナー（方針・調停部分のみ）
   - Rust VM 本体・MIR インタプリタ（据え置き）: `src/backend/mir_interpreter/*`, `src/runtime/*`
   - バックエンド/実行選択・ランナー: `src/runner/*`, `src/cli/args.rs`
   - Plan (20.10): Script Runner facade（lang側）を追加し、エントリ/前後処理を段階移譲（Gate: 既定ON・`HAKO_SCRIPT_RUNNER=0`でopt‑out）。

2) Extern/効果解決（VM ルート）
   - Extern アダプタ/レジストリ: `src/backend/mir_interpreter/extern_adapter/*`
   - 既存の最小 ABI 基本ルート: `src/runtime/method_router_box/abi_basic.rs`
   - Plan (20.10): SSOT（`specs/externs.toml`）の雛形と検出スクリプト（WARN）を追加。C‑ABI (`hako_*`) 経由の原則を再確認。

3) CLI/ENV/設定
   - 追加 CLI（quiet-result/using/macro/llvm-exe）と ENV エイリアス: `src/cli/args.rs`
   - 環境読み出し/feature gates: `src/config/env/*`
   - using 解決/モジュール: `src/using/*`, `src/runner/modes/common_util/resolve/*`
   - Plan (20.10): ドキュメントを一本化（`docs/guides/env-variables.md` を正）。Envは補助、CLIが正。

4) LLVM ツールチェーン（AOT）
   - Rust バイナリ: `crates/nyash-llvm-compiler`
   - llvmlite 降ろし（Python）: `src/llvm_py/*`（対象外・据え置き）

Deliverables（20.10）
- [x] Script Runner facade（lang/）
- [x] externs SSOT 生成スクリプト（tools/dev/run_gen_externs.sh）
- [ ] externs SSOT の雛形（specs/externs.toml）＋差分WARNスクリプト
- [ ] ENV/CLIガイドの更新（HAKO_* 優先・エイリアス表）
- [ ] Dotted C symbol チェックの STRICT 化準備（ドキュメント）

Add‑ons（runner／SSOT 安定化）
- [x] Runner pre‑invoke の短文（stdout）を固定（invoke / invoke: FAIL）
- [x] Trace 行（START/DONE）を env ゲートで追加（`HAKO_SCRIPT_RUNNER_TRACE=1`）
- [x] workspace‑only 代表スモーク（quick/integration-core）を追加
- [x] dev トグル `HAKO_SCRIPT_RUNNER_FORCE_FAIL` を追加（TTL；FAIL 行の観測用）
- [x] externs の SSOT（effects）の取り込み導線を追加（env ゲート `HAKO_EXTERN_EFFECTS_SSOT=1`、Io だけ反映）
 - [x] compare(lang) counts の観測（VM counts と lang stats を2行出力、スモーク整合）
 - [x] resolve/1 最小形状（空形状）の言語側導線（観測用・挙動不変）
 - [x] SSOT 生成のCI統合（build-only；STRICT_ALWAYS/CI_GEN_EXTERN_SSOTで生成→drift fail）

---

## 脱Rust 優先プラン & チェックリスト（20.10）

目標（ゴール）
- `lang/bin/hakorune`（Hakorune スクリプト由来の自己ホストバイナリ）をリポジトリ内に配置し、代表スモークを緑に保つ。

### 1) Runner 既定化（ゲート解除の準備）
- Plan
  - workspace-only 導線を代表化（override 依存を縮小）
  - TRACE/FAIL 注入の TTL を撤去（Docs/Smokes からの参照整理）
  - 短文の最終版（invoke / invoke: FAIL）を固定
- Checklist
  - [x] quick/integration-core: workspace-only 代表が恒常 PASS
  - [x] TTL トグルの撤去（trace/force-fail）— スモークは短文観測のみ
  - [x] Gate 既定ON・OFF時は静穏（opt‑out: HAKO_SCRIPT_RUNNER=0）
- DoD
  - Gate を OFF しても既存挙動不変／ON 時は短文が安定出力

### 2) Using Resolver 前段を lang へ
- Plan
  - メタResolver Box（公開名=SSOT）で `resolve/1` を Runner から呼べる導線を追加
  - workspace→override の順に優先、private/aliases/衝突を Fail‑Fast
- Checklist
  - [ ] メタResolver Box の公開名/SSOT を Docs に固定
  - [ ] Runner から ModuleFunction 呼び出しで前段解決（代表1本 PASS）
  - [ ] 既存 Rust 側の前処理は “検証/整流” に限定（重複はWARN→撤去）
- DoD
  - using 解決の決定（方針/診断）が lang 側で一貫し、Rust は検証に専念

### 3) SSOT 完全一本化
- Plan
  - extern/効果の読み込みを生成物（specs/externs.toml → Python/Rust）へ統一
  - STRICT（drift=FAIL）の継続運用
- Checklist
  - [x] Rust 側 effects 参照を ssot_generated に切替（既定）
  - [x] 生成スクリプト tools/dev/run_gen_externs.sh を追加（specs→Python/Rust）
  - [x] externs_ssot_check のローカルPASS（STRICT=1で運用可能）

---

## 残タスク（Remaining）

Runner / UsingResolver（安全な段階移行）
- [x] Shadow: DIFFの詳細化（`DIFF=aliases:X modules:Y paths:Z`）
- [x] Compare(lang): VM counts と lang stats の一致を観測（スモーク整合）
- [x] Compare: ModuleFunction結果のJSON1行出力（lang側 stats）＋ VM側 stats を Runner が出力（挙動不変）
      - 備考: 比較はスモーク側で実施（短文を安定維持）。shapeの厳密比較は将来の実値導入後に検討。
- [ ] 代表負例スモークの拡充（未存在/衝突/プライベート）— 比較/シャドウでの観測

UsingResolver（lang実装の充実）
- [x] resolve/1 の最小形状（空形状）を返す導線（観測用・挙動不変）
- [ ] using_paths/modules/aliases/packages/policy の実値構築（plugins無効環境でも最小が動作）
- [ ] host-slot依存の最小ガード（Box側での安全化）

SSOT（運用の固定化）
- [x] 生成スクリプトのCI統合（build-only）
- [ ] Python/Rustの参照経路を生成物に統一（残存定義の撤去/WARN化）

C‑ABI AOT（可搬性）
- [x] macOS/Windows のスモーク有効化（依存検出＋実行；不足時はSKIP）
- [x] ny-llvmc呼出失敗時の詳細取込み（stderr→短文化）

Docs
- [ ] runner-facade.md に Shadow/Compare のDIFF出力仕様を追記（実装後）
- [ ] c-abi-aot.md にWindows/mingwの依存補足（lld/CRTの注意）

## 受け入れ基準（Acceptance）
- Runner（既定ON）: quick/integration-core の代表が安定PASS（invoke/workspace-only）。
- UsingResolver: Shadow/Compare が quick/core で観測可能（DIFF=0が既定）。
- SSOT: externs drift=0（ローカル/CIでSTRICT）。
- C‑ABI: Linux/Darwinの代表スモークが依存整備環境でPASS（他OSはSKIP）。
- DoD
  - 生成系のみで Python/Rust の乖離が発生しない（drift=0 を維持）

### 4) Selfhost Compiler 最小パス
- Plan
  - const/binop/compare/ret/phi の emit を lang 側に実装（最小 JSON→MIR(JSON)）
  - Rust 側は Verify/整形に寄せる（意味論追加は行わない）
- Checklist
  - [ ] lang 側最小 emitter で `const,binop,compare,ret,phi` の代表スモーク PASS
  - [ ] Rust Verify を用いた形状検証が GREEN
  - [ ] 既存 VM/LLVM 実行と出力パリティを代表で確認
- DoD
  - 最小 MIR(JSON) 生成が lang 側のみで完結、Rust は検証に留まる

### 5) AOT C API の最小2関数（compile/link）
- Plan
  - `compile(json_v0)->obj`, `link(obj)->exe` の C ABI を薄く定義（ヘッダ＋実装）
  - lang/build から呼び出す最小サンプルを同梱
- Checklist
  - [ ] hako_hostbridge.h にプロトタイプ追記（所有権/戻り値/エラー）
  - [ ] canary 実装（linker flags ガイド含む）が quick 代表1本 PASS
  - [ ] Windows/macOS CRT 注意（hako_mem_free 以外禁止）の Docs 追記
- DoD
  - C ABI の 2 関数で AOT 経路の基本が成立、配布ガイドが明文化


Gates
- `HAKO_SCRIPT_RUNNER`（既定ON。`0|off|false` で無効化）
- `HAKO_SCRIPT_RUNNER_TRACE=1`（runner pre‑invoke の START/DONE 行）
- `HAKO_SCRIPT_RUNNER_FORCE_FAIL=1`（dev限定；FAIL 短文を強制；TTL）
- `HAKO_EXTERN_EFFECTS_SSOT=1`（extern effects を SSOT から反映；Io のみ）
- `CI_STRICT=1`（lint類をFAIL化）

TTL / 移行計画（runner）
- `HAKO_SCRIPT_RUNNER_FORCE_FAIL` と `HAKO_SCRIPT_RUNNER_TRACE` は bring‑up 期間限定の dev トグル。
  - TTL（目安）: Phase‑20.10 の runner 配線が安定したら 1 リリース後に削除。
  - 撤去手順: スモークから参照を削除 → 短文観測のみを維持（invoke / invoke: FAIL）。

STRICT への段階導入（externs）
- まずは `tools/ci/run_local_checks.sh` の WARN 運用を継続。
- `CI_STRICT=1`（or `CI_STRICT_ALWAYS=1`）でドライランし、差分ゼロを確認。
- 問題なければ CI 本線で STRICT 化（WARN→FAIL）へ移行。

Notes
- Extern は C‑ABI (`hako_*`) 経由で統一。dotted シンボルは IR まで（AOTへは流さない）。
- Python は据え置き。Rust VM/LLVM の本番経路は維持しつつ、上位調停をスクリプトへ段階移譲。