hakorune/docs/development/current/main/phase173b-boxification-assessment.md

# Phase 173-B StaticBoxRegistry Boxification Assessment

**Status**: ✅ **OPTIMAL COMPLEXITY REACHED**

## Architectural Review

### What Was Accomplished
1. **Unified Scattered Management** (4 locations → 1 registry)
   - Before: `static_box_decls` + `static_boxes` in MirInterpreter
   - Before: Manual detection code in vm.rs (63 lines)
   - Before: Scattered checks in multiple handler files
   - After: Single `StaticBoxRegistry` with clear responsibilities

2. **Automatic Detection from MIR** (using-imports solved)
   - Before: Had to manually register using-imported boxes in vm.rs
   - After: Auto-detection from "BoxName.method/arity" function names
   - Result: 63 lines of manual code eliminated

3. **Design Principles Applied**
   - ✅ **箱にする (Boxify)**: Unified declarations + detection + instances
   - ✅ **境界を作る (Boundary)**: Clear API (exists, get_or_create_instance, register)
   - ✅ **Fail-Fast**: No fallback paths, explicit errors for missing boxes
   - ✅ **遅延シングルトン (Lazy Singleton)**: Only create instances on first access

### Complexity Analysis

**StaticBoxRegistry lines**: 285 lines
- Core struct: 15 lines (3 fields, well-focused)
- Naming module: 30 lines (pure, reusable functions)
- Core logic: 95 lines (detection, registration, instantiation)
- Tests: 65 lines (comprehensive unit tests)
- Comments/Docs: 80 lines (clear documentation)

**Ratio**: 38% essential logic, 62% tests + docs = **WELL-TESTED AND DOCUMENTED** ✅

### Can We Simplify Further?

**Question 1: Remove `detected_boxes` HashSet?**
- No. Needed to distinguish:
  - Declared boxes (from AST)
  - Detected boxes (from MIR, using-imports)
  - This distinction matters for error messages and lifecycle

**Question 2: Combine `declarations` and `detected_boxes`?**
- No. Different sources → different semantics
  - Declarations have methods/fields metadata (from AST)
  - Detected boxes have only function signatures (from MIR)
  - Separating prevents false metadata conflicts

**Question 3: Inline the `naming` module?**
- No. Functions are reused in:
  - StaticBoxRegistry itself (detect_from_mir_functions)
  - MirInterpreter (is_static_box_method)
  - Tests (explicitly tested)
- Worth keeping as dedicated utility

**Question 4: Remove BUILTIN_RUNTIME_BOXES list?**
- Tempting to remove, but necessary for correctness
  - Main/main: Not static boxes (entry points)
  - StringBox/IntegerBox/etc: Built-in, not user-defined
  - Prevents false positives in auto-detection
  - Cost: 17 lines. Benefit: Correctness. Worth keeping.

### What About Elsewhere?

**Checked for similar patterns**:
- ✅ No other scattered registry/management patterns found
- ✅ `obj_fields` in MirInterpreter is different (instance field storage, not box metadata)
- ✅ Plugin system has its own registry (appropriate separation)
- ✅ Box factory patterns are elsewhere, different problem domain

### Conclusion

**Current Implementation**: ✅ **CLEAN AND APPROPRIATE**

- **Not over-engineered**: Each line serves a purpose
  - 3 fields in StaticBoxRegistry match exact problem domain
  - 3 public methods + detection API cover all use cases
  - No helper classes, no premature abstraction

- **Not under-engineered**: All necessary concerns covered
  - Auto-detection solves using-import problem
  - Lazy singleton prevents unnecessary initialization
  - Fail-Fast errors prevent silent failures
  - Comprehensive tests ensure correctness

- **Well-positioned for maintenance**
  - Clear naming utilities extract reusable parsing logic
  - Explicit responsibility separation (declarations vs detected)
  - Documentation explains "why" not just "what"

### Recommendations for Future Work

**If you need to extend**:
1. **Add metrics** (trace environment variable already in place)
   - Count detections, instantiations, lookups for diagnostics

2. **Add caching** (if performance needed)
   - Cache `all_box_names()` results between calls
   - Currently rebuilds iterator on each call

3. **Integrate with plugin system** (future)
   - Current design allows plugin boxes to register themselves
   - No architectural barriers to extension

---

## Summary

**状況**: The StaticBoxRegistry is an exemplar of "箱化モジュール化" (boxification modularization).

- **285 lines** of focused, tested, documented code
- **4 responsibilities** clearly separated and bounded
- **0 unnecessary complexity** - each line earns its place
- **Ready for Phase 34+**: No technical debt from this refactoring

**Answer to user's question**: "It's simpler now, not complex!" ✨