hakorune/docs/development/current/main/phases/phase-285/phase-285a1-boxification.md

Phase 285A1: Weak Field Validator Boxification

Status: ✅ Complete (2025-12-24)

Goal

Phase 285A1 の weak field 処理を専用 Box に箱化し、以下を実現：

• 単一責任: weak field 契約検証のみを担当
• テスト容易性: 独立してテスト可能
• 再利用性: 他の箇所でも使える

Implementation

新規ファイル

src/mir/builder/weak_field_validator.rs

/// Phase 285A1: Weak Field Contract Validator Box
///
/// 単一責任: weak field の契約検証のみ
/// - 読み込み時: WeakRef 型注釈
/// - 書き込み時: 型契約検証（WeakRef/Void のみ許可）
pub(super) struct WeakFieldValidatorBox;

impl WeakFieldValidatorBox {
    /// Weak field 読み込み時の型注釈を追加
    pub(super) fn annotate_read_result(
        type_ctx: &mut TypeContext,
        dst: ValueId,
    ) {
        // Phase 285A1: Mark the result as WeakRef type
        type_ctx.value_types.insert(dst, MirType::WeakRef);
    }

    /// Weak field への代入を検証（3つの許可ケース）
    ///
    /// Phase 285A1 Fail-Fast 契約:
    /// - **許可**: WeakRef (weak() または weak field 読み込み)
    /// - **許可**: Void (クリア操作)
    /// - **禁止**: BoxRef (weak() なしの Box)
    /// - **禁止**: プリミティブ型
    /// - **禁止**: 型追跡されていない値
    pub(super) fn validate_assignment(
        value_type: Option<&MirType>,
        box_name: &str,
        field_name: &str,
    ) -> Result<(), String> {
        // 3つの許可ケースを検証
        // Fail-Fast: エラーは即座に返す
    }
}

特徴:

• Phase 33 の箱化モジュール化と同じ思想（単一責任、明確な境界）
• 充実したコメント（目的、契約、例）
• 単体テスト完備（5つのテストケース）

変更ファイル

src/mir/builder/fields.rs

Before (277行):

• check_weak_field_assignment() メソッド（232-277行）
• 読み込み時の型注釈（inline）
• 書き込み時の型検証（inline）

After (237行):

• WeakFieldValidatorBox::annotate_read_result() 呼び出し
• WeakFieldValidatorBox::validate_assignment() 呼び出し
• 40行削減（-14.4%）

src/mir/builder.rs

モジュール宣言追加:

mod weak_field_validator; // Phase 285A1: Weak field contract validator

Contract Enforcement

読み込み契約

// Phase 285A1: weak field 読み込みは WeakRef 型を返す（自動昇格なし）
WeakFieldValidatorBox::annotate_read_result(&mut self.type_ctx, dst);

書き込み契約

3つの許可ケース:

1. WeakRef: weak() または weak field 読み込みの結果
2. Void: クリア操作（me.next = Void）
3. BoxRef: 禁止 - エラーメッセージで weak() 使用を提案

エラーメッセージ例:

Cannot assign Box (StringBox) to weak field 'Node.next'.
Use weak(...) to create weak reference: me.next = weak(value)

Tests

単体テスト（5つ）

1. test_validate_weakref_allowed: WeakRef 許可
2. test_validate_void_allowed: Void 許可
3. test_validate_boxref_forbidden: BoxRef 禁止
4. test_validate_untracked_forbidden: 型追跡なし禁止
5. test_validate_primitive_forbidden: プリミティブ禁止

動作確認

# ビルド成功
cargo build --release
# Finished `release` profile [optimized] target(s) in 1m 23s

# 基本機能確認
echo 'static box Main { main() { print("Hello"); return 0 } }' > test.hako
./target/release/hakorune test.hako
# Output: Hello
# RC: 0

# フィールドアクセス確認
# Box with fields works correctly

Architecture Benefits

単一責任（SRP）

• Before: fields.rs が weak field 処理を含む（複数責任）
• After: WeakFieldValidatorBox が検証のみ担当

テスト容易性

• Before: fields.rs 全体のテストが必要
• After: WeakFieldValidatorBox 単独でテスト可能

再利用性

• Before: check_weak_field_assignment() は MirBuilder メソッド
• After: WeakFieldValidatorBox はどこからでも使える

明確な境界

fields.rs
  ├─ フィールド読み込み/書き込みロジック
  └─ WeakFieldValidatorBox::validate_assignment() 呼び出し
      ↓
weak_field_validator.rs
  └─ weak field 契約検証のみ

Code Quality

Phase 33 思想の継承

• 単一責任: 1つの Box = 1つの関心事
• 明確な境界: 入力/出力が明確
• 充実したコメント: 目的、契約、例
• Fail-Fast: エラーは即座に返す（フォールバック禁止）

メトリクス

• 行数削減: 277行 → 237行（-40行、-14.4%）
• モジュール化: 1ファイル → 2ファイル（責任分離）
• テストカバレッジ: 0 → 5単体テスト

Phase 285 Context

Phase 285A1 は Phase 285 の一部として、weak field 処理の基盤を整備：

• Phase 285 Goal: Box lifecycle / weakref / finalization / GC conformance
• Phase 285A1 Scope: weak field 契約検証の箱化
• Status: P0 (docs-only) → 実装進行中

Note: weak field 構文（weak next: Node）は未実装。Phase 285 P1 で実装予定。

References

• Phase 33: Box Theory Modularization (phase-33-modularization.md)
• Phase 285: Box lifecycle (phase-285/README.md)
• src/mir/builder/weak_field_validator.rs: 実装本体
• src/mir/builder/fields.rs: 呼び出し側