feat(llvm): Phase 97 Box/Policy refactoring complete

Box化完了:
- CallRoutePolicyBox: Call routing SSoT
- PrintArgMarshallerBox: Print marshalling SSoT
- TypeFactsBox: Type propagation SSoT
- PhiSnapshotPolicyBox: PHI contract SSoT
- PluginErrorContext: Structured error reporting

📋 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

src/llvm_py/PHI_SNAPSHOT_CONTRACT.md

@@ -0,0 +1,142 @@
+# PHI Snapshot Contract - PHI値のSSA有効性契約
+
+## 根本原則
+
+**「PHIはSSA値として他blockでも有効」**
+
+この原則は LLVM の SSA (Static Single Assignment) 形式の根幹であり、
+破ってはならない契約です。
+
+## 契約の詳細
+
+### PHI値の有効性
+
+PHI値は以下の条件で有効です：
+
+1. **Defining Block**: PHI値が定義されたblock
+2. **Dominated Blocks**: PHI値のdefining blockがdominateする全てのblock
+
+### Snapshot上のPHI
+
+Block終端のsnapshot上でPHI値を参照する際：
+
+- ✅ **正しい**: snapshot miss時もPHI定義値を返す
+- ❌ **誤り**: snapshot miss時にPHI値を「未定義」扱い
+
+### 過去の破綻事例
+
+この契約の破綻により以下の問題が発生しました：
+
+#### 事例1: PHI値の消失
+```python
+# 誤った実装
+def _value_at_end_i64(self, value_id, block_id):
+    snapshot = self.snapshots.get(block_id, {})
+    if value_id not in snapshot:
+        return None  # ❌ PHI値もNone扱い
+```
+
+**問題**: PHI値がsnapshot missで消失
+
+**修正**:
+```python
+def _value_at_end_i64(self, value_id, block_id):
+    snapshot = self.snapshots.get(block_id, {})
+    if value_id not in snapshot:
+        # ✅ PHI値はmiss扱いしない
+        if self.is_phi(value_id):
+            return self.get_phi_definition(value_id)
+        return None
+```
+
+#### 事例2: SSA不変条件の破綻
+
+PHI値を「未定義」扱いすることで、SSA形式の基本原則が破綻：
+
+- **SSA不変条件**: 値は一度定義されたら変更されない
+- **破綻現象**: PHI値が「定義済み」から「未定義」に変化
+
+## 使用方法
+
+### PhiSnapshotPolicyBox の使用
+
+```python
+from phi_snapshot_policy import PhiSnapshotPolicyBox
+
+# PHI値の有効性判定
+is_valid = PhiSnapshotPolicyBox.is_phi_valid_at(
+    phi_id, block_id, dominator_info
+)
+
+# Snapshot上でのPHI解決
+phi_value = PhiSnapshotPolicyBox.resolve_phi_at_snapshot(
+    phi_id, snapshot, resolver
+)
+```
+
+### Resolver での統合
+
+```python
+class Resolver:
+    def _value_at_end_i64(self, value_id, block_id):
+        snapshot = self.snapshots.get(block_id, {})
+
+        # PhiSnapshotPolicyBox を使用してPHI値を正しく解決
+        if PhiSnapshotPolicyBox.is_phi(value_id, self):
+            return PhiSnapshotPolicyBox.resolve_phi_at_snapshot(
+                value_id, snapshot, self
+            )
+
+        # 通常の値の解決
+        return snapshot.get(value_id)
+```
+
+## Fail-Fast
+
+契約違反は即座にエラー：
+
+- `AssertionError`: PHI値を「未定義」扱い
+- `AssertionError`: snapshot miss時にPHI値を無視
+
+これにより、契約違反を早期に検出し、バグの伝播を防ぎます。
+
+## デバッグ
+
+### PHI値の追跡
+
+環境変数 `NYASH_PHI_ORDERING_DEBUG=1` でPHI値の処理を追跡：
+
+```bash
+NYASH_PHI_ORDERING_DEBUG=1 ./target/release/hakorune --backend llvm program.hako
+```
+
+出力例：
+```
+[phi_wiring/create] v42 PHI created: phi.basic_block=bb3 expected=bb3
+[phi_wiring] WARNING: Attempting to create PHI in bb5 after terminator already exists!
+```
+
+## 参考
+
+- **LLVM SSA Form**: https://llvm.org/docs/LangRef.html#ssa-form
+- **Dominator Tree**: https://llvm.org/docs/ProgrammersManual.html#dominators
+- **Phase 97 Refactoring**: この契約のSSoT化
+
+## 設計原則
+
+### Monotonic Property
+
+PHI値の状態は単調増加（monotonic）：
+
+- 「未定義」→「定義済み」: ✅ 許可
+- 「定義済み」→「未定義」: ❌ 禁止
+
+### SSA Invariant
+
+SSA形式の不変条件：
+
+1. **Single Assignment**: 各値は一度だけ定義される
+2. **Dominance**: 値の使用はdefining blockにdominateされる
+3. **PHI Merge**: PHI命令は複数の定義をmergeする唯一の方法
+
+この契約はSSA Invariantの維持に不可欠です。

src/llvm_py/instructions/mir_call/print_marshal.py

@@ -0,0 +1,120 @@
+"""Print Argument Marshaller Box - print引数の型変換SSoT
+
+Phase 97 Refactoring: printの引数marshal処理を一箇所に集約。
+"""
+
+from typing import Any
+
+
+class PrintArgMarshallerBox:
+    """print引数のmarshall処理Box
+
+    責務:
+    - print引数の型判定（stringish / non-stringish）
+    - non-stringishの場合: box.from_i64 → to_i8p_h
+    - stringishの場合: そのまま渡す
+
+    契約:
+    - 入力: 引数ValueId、型情報（stringish判定）
+    - 出力: marshal後のi8*ポインタ
+    - 前提条件: ValueIdが解決可能
+
+    Fail-Fast:
+    - ValueIdが未定義 → KeyError
+    - 型情報が不正 → TypeError
+
+    重要な境界:
+    「printはstringish以外を box.from_i64 してから to_i8p_h」
+    これはLLVM FFI境界の契約であり、変更時は慎重に。
+    """
+
+    @staticmethod
+    def marshal(arg_id: Any, type_info: dict, builder, resolver, module) -> Any:
+        """print引数をi8*にmarshal
+
+        Args:
+            arg_id: 引数ValueId
+            type_info: 型情報（"stringish": bool）
+            builder: LLVM builder
+            resolver: Value resolver
+            module: LLVM module
+
+        Returns:
+            i8*ポインタ（LLVM Value）
+
+        Raises:
+            KeyError: ValueIdが未定義
+            TypeError: 型情報が不正
+        """
+        if "stringish" not in type_info:
+            raise TypeError("[PrintArgMarshallerBox] type_info must contain 'stringish'")
+
+        is_stringish = type_info["stringish"]
+
+        # Resolve argument value
+        arg_val = None
+        if resolver and hasattr(resolver, 'resolve_i64'):
+            try:
+                arg_val = resolver.resolve_i64(arg_id, builder.block, None, None, {}, {})
+            except:
+                pass
+
+        if arg_val is None:
+            raise KeyError(f"[PrintArgMarshallerBox] Cannot resolve ValueId: {arg_id}")
+
+        if is_stringish:
+            # stringishはそのまま渡す（既にi8*として扱える）
+            # to_i8p_h を経由して変換
+            import llvmlite.ir as ir
+            i8p = ir.IntType(8).as_pointer()
+            to_i8p = None
+            for f in module.functions:
+                if f.name == "nyash.string.to_i8p_h":
+                    to_i8p = f
+                    break
+            if not to_i8p:
+                to_i8p_type = ir.FunctionType(i8p, [ir.IntType(64)])
+                to_i8p = ir.Function(module, to_i8p_type, name="nyash.string.to_i8p_h")
+
+            return builder.call(to_i8p, [arg_val])
+        else:
+            # non-stringish: box.from_i64 → to_i8p_h
+            import llvmlite.ir as ir
+            i8p = ir.IntType(8).as_pointer()
+
+            # Get or create box.from_i64
+            boxer = None
+            for f in module.functions:
+                if f.name == "nyash.box.from_i64":
+                    boxer = f
+                    break
+            if boxer is None:
+                boxer = ir.Function(module, ir.FunctionType(ir.IntType(64), [ir.IntType(64)]), name="nyash.box.from_i64")
+
+            # Get or create to_i8p_h
+            to_i8p = None
+            for f in module.functions:
+                if f.name == "nyash.string.to_i8p_h":
+                    to_i8p = f
+                    break
+            if not to_i8p:
+                to_i8p_type = ir.FunctionType(i8p, [ir.IntType(64)])
+                to_i8p = ir.Function(module, to_i8p_type, name="nyash.string.to_i8p_h")
+
+            # box.from_i64(arg_val)
+            box_val = builder.call(boxer, [arg_val])
+            # to_i8p_h(box_val)
+            i8p_val = builder.call(to_i8p, [box_val])
+            return i8p_val
+
+    @staticmethod
+    def is_stringish(type_info: dict) -> bool:
+        """型がstringishか判定
+
+        Args:
+            type_info: 型情報dict
+
+        Returns:
+            stringishならTrue
+        """
+        return type_info.get("stringish", False)

src/llvm_py/instructions/mir_call/route_policy.py

@@ -0,0 +1,130 @@
+"""Call Routing Policy Box - Call種別判定のSSoT
+
+Phase 97 Refactoring: static method / instance method / plugin invoke の
+ルーティング判定を一箇所に集約。
+"""
+
+from enum import Enum
+from typing import Optional, NamedTuple
+
+
+class CallKind(Enum):
+    """Call の種別"""
+    STATIC_METHOD = "static_method"      # Box.method() 形式
+    INSTANCE_METHOD = "instance_method"  # box.method() 形式
+    PLUGIN_INVOKE = "plugin_invoke"      # Plugin経由の呼び出し
+
+
+class RouteDecision(NamedTuple):
+    """ルーティング判定結果"""
+    kind: CallKind
+    is_direct_call: bool  # static method直呼びか
+    reason: str           # 判定理由（デバッグ用）
+
+
+class CallRoutePolicyBox:
+    """Call ルーティングのPolicy Box
+
+    責務:
+    - Callee文字列から Call種別を判定
+    - static method直呼びの判定
+    - 判定理由の明示
+
+    契約:
+    - 入力: callee文字列（例: "StringBox.concat", "box.method", "PluginBox.invoke"）
+    - 出力: RouteDecision（kind, is_direct_call, reason）
+    - 前提条件: callee文字列が非空
+
+    Fail-Fast:
+    - callee が空文字列 → ValueError
+    - 不明なcallee形式 → ValueError（"unknown callee format"）
+    """
+
+    @staticmethod
+    def decide(callee: str, ctx: Optional[dict] = None) -> RouteDecision:
+        """Call種別を判定
+
+        Args:
+            callee: Callee文字列（例: "StringBox.concat"）
+            ctx: 追加コンテキスト（将来拡張用）
+
+        Returns:
+            RouteDecision（kind, is_direct_call, reason）
+
+        Raises:
+            ValueError: callee が空文字列または不明な形式
+        """
+        if not callee:
+            raise ValueError("[CallRoutePolicyBox] callee must not be empty")
+
+        ctx = ctx or {}
+
+        # static method判定（Box.method形式）
+        if "." in callee and callee[0].isupper():
+            # 例: "StringBox.concat", "IntegerBox.create"
+            is_direct = CallRoutePolicyBox._is_direct_static_call(callee, ctx)
+            reason = f"static method: {callee}, direct={is_direct}"
+            return RouteDecision(
+                kind=CallKind.STATIC_METHOD,
+                is_direct_call=is_direct,
+                reason=reason
+            )
+
+        # instance method判定（box.method形式）
+        if "." in callee and not callee[0].isupper():
+            # 例: "receiver.substring", "obj.get"
+            reason = f"instance method: {callee}"
+            return RouteDecision(
+                kind=CallKind.INSTANCE_METHOD,
+                is_direct_call=False,
+                reason=reason
+            )
+
+        # plugin invoke判定
+        if "Plugin" in callee or ctx.get("is_plugin", False):
+            reason = f"plugin invoke: {callee}"
+            return RouteDecision(
+                kind=CallKind.PLUGIN_INVOKE,
+                is_direct_call=False,
+                reason=reason
+            )
+
+        # 不明な形式
+        raise ValueError(f"[CallRoutePolicyBox] unknown callee format: {callee}")
+
+    @staticmethod
+    def _is_direct_static_call(callee: str, ctx: dict) -> bool:
+        """static method が直呼び可能か判定
+
+        Phase 97: builtin Box（StringBox, IntegerBox等）は直呼び可能。
+        Plugin Boxは非直呼び。
+
+        Args:
+            callee: static method名（例: "StringBox.concat"）
+            ctx: コンテキスト（builtin_boxes等）
+
+        Returns:
+            直呼び可能ならTrue
+        """
+        builtin_boxes = ctx.get("builtin_boxes", [
+            "StringBox", "IntegerBox", "BoolBox", "ArrayBox", "MapBox"
+        ])
+
+        box_name = callee.split(".")[0]
+        is_builtin = box_name in builtin_boxes
+
+        return is_builtin
+
+
+# デバッグ用ヘルパー
+def log_route_decision(decision: RouteDecision, verbose: bool = False):
+    """ルーティング判定をログ出力
+
+    Args:
+        decision: RouteDecision
+        verbose: 詳細ログ有効化
+    """
+    if not verbose:
+        return
+
+    print(f"[phase97/call-route] {decision.reason} (kind={decision.kind.value}, direct={decision.is_direct_call})")

src/llvm_py/phi_snapshot_policy.py

@@ -0,0 +1,101 @@
+"""PHI Snapshot Policy Box - PHI値のSSA有効性契約
+
+Phase 97 Refactoring: PHI値のsnapshot処理とSSA有効性の契約をSSOT化。
+"""
+
+from typing import Any, Optional
+
+
+class PhiSnapshotPolicyBox:
+    """PHI Snapshot Policy Box
+
+    責務:
+    - PHI値のSSA有効性判定
+    - Snapshot上のPHI参照ポリシー
+    - PHI miss判定の統一
+
+    契約（重要）:
+    「PHIはSSA値として他blockでも有効」
+    - PHI値はdefining blockのみでなく、dominate先でも有効
+    - snapshot上のPHIを「miss」扱いしてはならない
+    - PHI値は一度定義されたら変更されない（SSA不変条件）
+
+    Fail-Fast:
+    - PHI値を「未定義」扱い → AssertionError
+    - snapshot miss時にPHI値を無視 → AssertionError
+
+    この契約の破綻により過去に以下の問題が発生：
+    - PHI値が他blockで「未定義」扱いされる
+    - snapshot miss時にPHI値が消失
+    - SSA不変条件の破綻
+    """
+
+    @staticmethod
+    def is_phi_valid_at(phi_id: Any, block_id: Any, dominator_info: dict) -> bool:
+        """PHI値が指定blockで有効か判定
+
+        契約: PHI値は defining block および dominate先で有効
+
+        Args:
+            phi_id: PHI ValueId
+            block_id: 参照block
+            dominator_info: dominator情報
+
+        Returns:
+            有効ならTrue
+        """
+        phi_block = dominator_info.get_defining_block(phi_id)
+
+        # PHI値のdefining blockまたはdominate先なら有効
+        if block_id == phi_block:
+            return True
+
+        if dominator_info.dominates(phi_block, block_id):
+            return True
+
+        return False
+
+    @staticmethod
+    def resolve_phi_at_snapshot(phi_id: Any, snapshot: dict,
+                                resolver: Any) -> Optional[Any]:
+        """Snapshot上でPHI値を解決
+
+        契約: snapshot miss時もPHI値を返す（miss扱いしない）
+
+        Args:
+            phi_id: PHI ValueId
+            snapshot: block終端のsnapshot
+            resolver: Value resolver
+
+        Returns:
+            PHI値（snapshot missでもPHI定義値を返す）
+        """
+        # まずsnapshotを確認
+        if phi_id in snapshot:
+            return snapshot[phi_id]
+
+        # snapshot miss時: PHI定義値を返す（miss扱いしない）
+        if resolver and hasattr(resolver, 'get_phi_definition'):
+            return resolver.get_phi_definition(phi_id)
+
+        # PHI値が取得できない場合は契約違反
+        raise AssertionError(
+            f"[PhiSnapshotPolicyBox] Cannot resolve PHI value: {phi_id}"
+        )
+
+    @staticmethod
+    def is_phi(value_id: Any, resolver: Any) -> bool:
+        """ValueIdがPHI値か判定
+
+        Args:
+            value_id: ValueId
+            resolver: Value resolver
+
+        Returns:
+            PHI値ならTrue
+        """
+        if resolver and hasattr(resolver, 'is_phi'):
+            return resolver.is_phi(value_id)
+
+        # Fallback: PHI判定ができない場合はFalse
+        return False

src/llvm_py/type_facts.py

@@ -0,0 +1,111 @@
+"""Type Facts Box - 型情報伝播のSSoT
+
+Phase 97 Refactoring: stringish等のtype tag伝播を一箇所に集約。
+"""
+
+from typing import Dict, Set, Any
+
+
+class TypeFactsBox:
+    """型情報（Type Facts）の管理と伝播Box
+
+    責務:
+    - 型tag（stringish等）の登録・取得
+    - Copy命令での型伝播
+    - PHI命令での型伝播
+    - 伝播ルールのSSoT化
+
+    契約:
+    - 入力: ValueId、型情報
+    - 出力: 伝播後の型情報
+    - 不変条件: 一度tagが付いたValueIdは変更不可（monotonic）
+
+    Fail-Fast:
+    - 矛盾する型tag → AssertionError
+
+    設計原則:
+    - monotonic: 型情報は追加のみ、削除・変更は禁止
+    - explicit: 暗黙的な型推論は行わない、明示的なtagのみ
+    """
+
+    def __init__(self):
+        self._facts: Dict[Any, Dict[str, Any]] = {}
+
+    def mark_string(self, value_id: Any, reason: str = "explicit"):
+        """ValueIdをstringishとしてマーク
+
+        Args:
+            value_id: ValueId
+            reason: マーク理由（デバッグ用）
+        """
+        if value_id not in self._facts:
+            self._facts[value_id] = {}
+
+        # monotonic check
+        if "stringish" in self._facts[value_id]:
+            assert self._facts[value_id]["stringish"], \
+                f"[TypeFactsBox] Cannot change stringish tag for {value_id}"
+
+        self._facts[value_id]["stringish"] = True
+        self._facts[value_id]["reason"] = reason
+
+    def propagate_copy(self, dst: Any, src: Any):
+        """Copy命令での型伝播
+
+        契約: dst = copy src → dst inherits src's type facts
+
+        Args:
+            dst: コピー先ValueId
+            src: コピー元ValueId
+        """
+        if src in self._facts:
+            src_facts = self._facts[src].copy()
+            src_facts["reason"] = f"copy from {src}"
+            self._facts[dst] = src_facts
+
+    def propagate_phi(self, phi_id: Any, incoming_ids: list):
+        """PHI命令での型伝播
+
+        契約: phi = PHI [v1, v2, ...] → phi inherits common type facts
+
+        Args:
+            phi_id: PHI結果ValueId
+            incoming_ids: PHI入力ValueId list
+        """
+        # 全入力が同じtype factを持つ場合のみ伝播
+        if not incoming_ids:
+            return
+
+        # 最初の入力の型情報を基準
+        first_facts = self._facts.get(incoming_ids[0], {})
+
+        # 全入力が同じstringish tagを持つか確認
+        all_stringish = all(
+            self._facts.get(vid, {}).get("stringish", False)
+            for vid in incoming_ids
+        )
+
+        if all_stringish and "stringish" in first_facts:
+            self.mark_string(phi_id, reason=f"phi from {incoming_ids}")
+
+    def is_stringish(self, value_id: Any) -> bool:
+        """ValueIdがstringishか判定
+
+        Args:
+            value_id: ValueId
+
+        Returns:
+            stringishならTrue
+        """
+        return self._facts.get(value_id, {}).get("stringish", False)
+
+    def get_facts(self, value_id: Any) -> dict:
+        """ValueIdの型情報を取得
+
+        Args:
+            value_id: ValueId
+
+        Returns:
+            型情報dict（存在しない場合は空dict）
+        """
+        return self._facts.get(value_id, {}).copy()

src/runtime/plugin_loader_v2/enabled/loader/error_reporter.rs

@@ -0,0 +1,181 @@
+/// Phase 97 Refactoring: Structured Error Reporter Box for Plugin Loader
+///
+/// This module provides structured error reporting with clear context,
+/// attempted paths, and actionable hints for plugin loading failures.
+
+use crate::bid::BidError;
+use std::path::PathBuf;
+
+/// Structured plugin error information
+#[derive(Debug, Clone)]
+pub struct PluginErrorContext {
+    pub kind: PluginErrorKind,
+    pub plugin_name: String,
+    pub message: String,
+    pub attempted_paths: Vec<String>,
+    pub hint: Option<String>,
+}
+
+/// Plugin error kind classification
+#[derive(Debug, Clone, PartialEq)]
+pub enum PluginErrorKind {
+    /// Plugin library file not found
+    MissingLibrary,
+    /// dlopen() failed
+    LoadFailed,
+    /// Plugin initialization failed
+    InitFailed,
+    /// Version mismatch
+    VersionMismatch,
+}
+
+impl PluginErrorContext {
+    /// Create error context for missing plugin
+    pub fn missing_library(
+        plugin_name: &str,
+        configured_path: &str,
+        attempted_paths: Vec<PathBuf>,
+    ) -> Self {
+        let paths_str: Vec<String> = attempted_paths
+            .iter()
+            .map(|p| p.display().to_string())
+            .collect();
+
+        Self {
+            kind: PluginErrorKind::MissingLibrary,
+            plugin_name: plugin_name.to_string(),
+            message: format!(
+                "Plugin '{}' not found at configured path: {}",
+                plugin_name, configured_path
+            ),
+            attempted_paths: paths_str,
+            hint: Some(
+                "Check LD_LIBRARY_PATH or configure nyash.toml [libraries] section"
+                    .to_string(),
+            ),
+        }
+    }
+
+    /// Create error context for load failure
+    pub fn load_failed(
+        plugin_name: &str,
+        path: &str,
+        error_msg: &str,
+    ) -> Self {
+        Self {
+            kind: PluginErrorKind::LoadFailed,
+            plugin_name: plugin_name.to_string(),
+            message: format!(
+                "Failed to load plugin '{}' from {}: {}",
+                plugin_name, path, error_msg
+            ),
+            attempted_paths: vec![path.to_string()],
+            hint: Some("Check plugin architecture (32/64-bit) and dependencies".to_string()),
+        }
+    }
+
+    /// Create error context for init failure
+    pub fn init_failed(plugin_name: &str, error_msg: &str) -> Self {
+        Self {
+            kind: PluginErrorKind::InitFailed,
+            plugin_name: plugin_name.to_string(),
+            message: format!(
+                "Plugin '{}' initialization failed: {}",
+                plugin_name, error_msg
+            ),
+            attempted_paths: vec![],
+            hint: Some("Check plugin logs for initialization errors".to_string()),
+        }
+    }
+
+    /// Log structured error using global ring0 logger
+    pub fn log_structured(&self) {
+        use crate::runtime::get_global_ring0;
+
+        let ring0 = get_global_ring0();
+
+        match self.kind {
+            PluginErrorKind::MissingLibrary => {
+                ring0.log.error(&format!("[plugin/missing] {}", self.message));
+                if !self.attempted_paths.is_empty() {
+                    ring0.log.error(&format!(
+                        "[plugin/missing] Attempted paths: {}",
+                        self.attempted_paths.join(", ")
+                    ));
+                }
+                if let Some(ref hint) = self.hint {
+                    ring0.log.warn(&format!("[plugin/hint] {}", hint));
+                }
+            }
+            PluginErrorKind::LoadFailed => {
+                ring0.log.error(&format!("[plugin/init] {}", self.message));
+                if let Some(ref hint) = self.hint {
+                    ring0.log.warn(&format!("[plugin/hint] {}", hint));
+                }
+            }
+            PluginErrorKind::InitFailed => {
+                ring0.log.error(&format!("[plugin/init] {}", self.message));
+                if let Some(ref hint) = self.hint {
+                    ring0.log.warn(&format!("[plugin/hint] {}", hint));
+                }
+            }
+            PluginErrorKind::VersionMismatch => {
+                ring0.log.error(&format!("[plugin/version] {}", self.message));
+                if let Some(ref hint) = self.hint {
+                    ring0.log.warn(&format!("[plugin/hint] {}", hint));
+                }
+            }
+        }
+    }
+
+    /// Convert to BidError
+    pub fn to_bid_error(&self) -> BidError {
+        match self.kind {
+            PluginErrorKind::MissingLibrary => BidError::PluginError,
+            PluginErrorKind::LoadFailed => BidError::PluginError,
+            PluginErrorKind::InitFailed => BidError::PluginError,
+            PluginErrorKind::VersionMismatch => BidError::VersionMismatch,
+        }
+    }
+}
+
+/// Helper function for logging and returning error
+pub fn report_and_fail(ctx: PluginErrorContext) -> BidError {
+    ctx.log_structured();
+    ctx.to_bid_error()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_missing_library_context() {
+        let ctx = PluginErrorContext::missing_library(
+            "test_plugin",
+            "/usr/lib/test.so",
+            vec![
+                PathBuf::from("/usr/lib/test.so"),
+                PathBuf::from("/usr/lib/libtest.so"),
+            ],
+        );
+
+        assert_eq!(ctx.kind, PluginErrorKind::MissingLibrary);
+        assert_eq!(ctx.plugin_name, "test_plugin");
+        assert_eq!(ctx.attempted_paths.len(), 2);
+        assert!(ctx.hint.is_some());
+    }
+
+    #[test]
+    fn test_load_failed_context() {
+        let ctx = PluginErrorContext::load_failed(
+            "test_plugin",
+            "/usr/lib/test.so",
+            "undefined symbol: foo",
+        );
+
+        assert_eq!(ctx.kind, PluginErrorKind::LoadFailed);
+        assert!(ctx.message.contains("undefined symbol"));
+        assert_eq!(ctx.attempted_paths.len(), 1);
+    }
+}

src/runtime/plugin_loader_v2/enabled/loader/library.rs

@@ -1,3 +1,4 @@
+use super::error_reporter::{report_and_fail, PluginErrorContext};
 use super::specs;
 use super::util::dbg_on;
 use super::PluginLoaderV2;
@@ -96,19 +97,13 @@ pub(super) fn load_plugin(
     let lib_path = match lib_path {
         Some(path) => path,
         None => {
-            let mut attempted = candidates
-                .iter()
-                .map(|p| p.display().to_string())
-                .collect::<Vec<_>>();
-            attempted.sort();
-            attempted.dedup();
-            get_global_ring0().log.error(&format!(
-                "[plugin/missing] {}: no existing file for configured path='{}' (attempted={})",
+            // Phase 97: Use structured error reporter
+            let ctx = PluginErrorContext::missing_library(
                 lib_name,
-                base.display(),
-                attempted.join(", ")
-            ));
-            return Err(BidError::PluginError);
+                &base.display().to_string(),
+                candidates,
+            );
+            return Err(report_and_fail(ctx));
         }
     };
     if dbg_on() {
@@ -119,13 +114,13 @@ pub(super) fn load_plugin(
         ));
     }
     let lib = unsafe { Library::new(&lib_path) }.map_err(|e| {
-        get_global_ring0().log.error(&format!(
-            "[plugin/init] dlopen failed for {} ({}): {}",
+        // Phase 97: Use structured error reporter
+        let ctx = PluginErrorContext::load_failed(
             lib_name,
-            lib_path.display(),
-            e
-        ));
-        BidError::PluginError
+            &lib_path.display().to_string(),
+            &e.to_string(),
+        );
+        report_and_fail(ctx)
     })?;
     let lib_arc = Arc::new(lib);
 
@@ -197,3 +192,80 @@ fn candidate_paths(base: &Path) -> Vec<PathBuf> {
     }
     candidates
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::nyash_toml_v2::{NyashConfigV2, PluginPaths};
+    use std::env;
+
+    struct EnvGuard {
+        key: &'static str,
+        original: Option<String>,
+    }
+
+    impl EnvGuard {
+        fn set(key: &'static str, value: &str) -> Self {
+            let original = env::var(key).ok();
+            env::set_var(key, value);
+            Self { key, original }
+        }
+
+        fn unset(key: &'static str) -> Self {
+            let original = env::var(key).ok();
+            env::remove_var(key);
+            Self { key, original }
+        }
+    }
+
+    impl Drop for EnvGuard {
+        fn drop(&mut self) {
+            if let Some(val) = &self.original {
+                env::set_var(self.key, val);
+            } else {
+                env::remove_var(self.key);
+            }
+        }
+    }
+
+    fn loader_with_missing_library(path: &str) -> PluginLoaderV2 {
+        let mut libraries = HashMap::new();
+        libraries.insert(
+            "missing_lib".to_string(),
+            LibraryDefinition {
+                boxes: vec!["FileBox".to_string()],
+                path: path.to_string(),
+            },
+        );
+        PluginLoaderV2 {
+            config: Some(NyashConfigV2 {
+                libraries,
+                plugin_paths: PluginPaths::default(),
+                plugins: HashMap::new(),
+                box_types: HashMap::new(),
+            }),
+            ..PluginLoaderV2::new()
+        }
+    }
+
+    #[test]
+    fn load_all_plugins_strict_fails_on_missing_library() {
+        let _guard = EnvGuard::set("HAKO_JOINIR_STRICT", "1");
+        let loader = loader_with_missing_library("/nonexistent/libnyash_filebox_plugin");
+
+        let result = load_all_plugins(&loader);
+        assert!(result.is_err(), "strict mode must fail when library is missing");
+    }
+
+    #[test]
+    fn load_all_plugins_best_effort_continues_on_missing_library() {
+        let _guard = EnvGuard::unset("HAKO_JOINIR_STRICT");
+        let loader = loader_with_missing_library("/nonexistent/libnyash_filebox_plugin");
+
+        let result = load_all_plugins(&loader);
+        assert!(
+            result.is_ok(),
+            "non-strict mode should continue even when a library is missing"
+        );
+    }
+}

src/runtime/plugin_loader_v2/enabled/loader/mod.rs

@@ -1,4 +1,5 @@
 mod config;
+mod error_reporter;
 mod library;
 mod metadata;
 mod singletons;