hakorune/docs/development/roadmap/phases/phase-21.7-normalization/README.md

Phase 21.7 — Normalization & Unification (Methodize Static Boxes)

Goal
- Unify user-defined function calls onto a single, consistent representation.
- Move from ad-hoc Global("Box.method") calls toward Method calls with an explicit (singleton) receiver when appropriate.
- Keep defaults stable; introduce dev toggles and canaries; then promote to default after green.

Scope
- Parser/Stage‑B: keep emitting Program(JSON v0). No schema changes required for MVP.
- MirBuilder: add methodization (dev toggle) that:
  - Emits method functions as-is (defs) and/or provides a mapping to Method calls
  - Rewrites Global("Box.method") to Method {receiver=static singleton, box_name, method}
  - Preserves arity and naming as Box.method/N
- VM: handle Method calls uniformly (receiver resolved via ensure_static_box_instance for static boxes).
- LLVM: rely on mir_call(Method) lowering (already supported) and provide the static receiver where needed.

Toggles
- HAKO_MIR_BUILDER_METHODIZE=1 — enable methodization (rewrite Global→Method with static singleton receiver)
- HAKO_STAGEB_FUNC_SCAN=1 — Stage‑B defs scan (already available)
- HAKO_MIR_BUILDER_FUNCS=1 — defs→MIR 関数化（既存）
- HAKO_MIR_BUILDER_CALL_RESOLVE=1 — Global 名解決（既存）

Design Rules
- Naming: canonical "Box.method/N". Arity N must equal params.len (or callsite args len if defs unknown).
- Receiver: for static boxes, provide implicit singleton receiver. For instance boxes, preserve existing Method path.
- Effects: preserve EffectMask semantics; do not broaden side effects.
- Fail‑Fast: when rewrite is ambiguous (multiple candidates), keep original form and WARN under dev toggle; never change defaults silently.

Acceptance
- Canaries:
  - call (global style) passes when methodization ON (rc unchanged)
  - Existing return/binop/loop/call (global) canaries remain green when OFF
  - A dedicated methodization canary asserts presence of callee.type=="Method" in MIR(JSON v1) or correct v0 lowering

Rollout Plan
1) Ship behind HAKO_MIR_BUILDER_METHODIZE=1 with canaries
2) Validate on representative apps (selfhost‑first path)
3) Promote to default ON only after green for a cycle; keep rollback instructions

Rollback
- Disable HAKO_MIR_BUILDER_METHODIZE. Revert to Global("Box.method") resolution path (current 21.6 behavior).

## Phase 21.7++ 実装完了 (2025-11-22)

### Global 名の SSOT ルール

#### 原則
- Global 関数名は **`Box.method/N`** が SSOT
- VM/LLVM で `Box.method` を受け取ったら、arity は `args.len()` から補完
- すべての名前解決は `NamingBox::StaticMethodId` 経由

#### 実装箇所

**NamingBox**: `src/mir/naming.rs`
- `StaticMethodId::parse()`: 名前のパース（"Box.method/N" or "Box.method"）
- `StaticMethodId::format()`: 正規化された名前生成
- `StaticMethodId::with_arity()`: arity 補完
- 13 テストケースで検証済み（src/tests/namingbox_static_method_id.rs）

**VM**: `src/backend/mir_interpreter/handlers/calls/global.rs`
- `StaticMethodId` で名前解決
- arity 無し → `args.len()` で補完
- "Did you mean?" エラーメッセージ実装

**UnifiedCallEmitter**: `src/mir/builder/calls/unified_emitter.rs`
- Methodization で `StaticMethodId` 使用
- TypeRegistry と連携して static box method 判定
- 素手 split 根絶

**Rewrite Known**: `src/mir/builder/rewrite/known.rs`
- split_once → StaticMethodId::parse() に統一

#### デバッグ環境変数
- `NYASH_DEBUG_FUNCTION_LOOKUP=1`: VM 関数ルックアップ詳細（box/method/arity 表示）
- `NYASH_DEBUG_USING=1`: using 解決詳細
- `NYASH_METHODIZE_TRACE=1`: Global→Method 変換ログ

#### 実装フェーズ（全完了）
- ✅ **Phase 0: 観測ライン** (commit 63012932) - Silent Failure 根絶
- ✅ **Phase 1: 基盤整備** (commit 96c1345e) - StaticMethodId SSOT 確立
- ✅ **Phase 2: VM 統一** (commit 1b413da5) - arity バグ根治
- ✅ **Phase 3: 全体統一** (commit c8ad1dae) - Builder 側統一、素手 split 根絶

#### 技術的成果
- Silent Failure 根絶（デバッグ時間: 時間→分）
- arity バグ根治（Hotfix 卒業）
- 素手 split 根絶（全箇所を SSOT 経由に統一）
- 型安全化（構造化表現で誤用防止）
- テスト完全通過（349 passed, 退行なし）

---

## 旧ノート（Phase 25.x bring-up 時点）

### NamingBox / static 名 SSOT
- `src/mir/naming.rs` に NamingBox を実装済み。`Main.main` / `main._nop` などの揺れを `"Main.main/0"` 形式に正規化する経路は Rust VM/LLVM/JSON bridge から既に利用中。
- VM 側は `normalize_static_global_name` を通して static box 名を一元化するよう更新済み。
- **Phase 21.7++ で完全 SSOT 化完了**（2025-11-22）

### 既知のギャップ（解決済み）
- ~~static box 内のローカル呼び出し（例: `Main.main` → `me._nop()`）が Global 呼び出しのまま落ちるケースを確認済み。~~ → Phase 2 で解決
- ~~MeCallPolicy / method_call_handlers 周りで、static box method に対しても一律で receiver（`me`）を先頭に追加してしまうパスがあり、arity 不一致や miss-call の温床になり得る。~~ → Phase 3 で解決