From b4ef8a002384d6266b6ffc4ea011078e3f2a0694 Mon Sep 17 00:00:00 2001
From: nyash-codex <codex@nyash.local>
Date: Mon, 15 Dec 2025 19:03:05 +0900
Subject: [PATCH] docs: Update JoinIR design map + organize CLAUDE.md (Phase
 135 follow-up)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Changes

### joinir-design-map.md
- Added "Allocator SSOT (Phase 135)" section
  - Principle: All ValueId allocation via single allocator (ConditionContext.alloc_value)
  - Prohibited: Internal counters in ConditionLoweringBox/ExprLowerer
  - Reason: Collisions with JoinIR params (ValueId(1000+)) overwrite header PHI dst
  - Detection: --verify catches "Value %N defined multiple times"

- Added "Boundary Injection SSA (Phase 135)" section
  - Principle: condition_bindings allow aliases, but injected Copy dst must be unique
  - Fail-Fast: Error on different sources to same dst
  - Reason: Breaks MIR SSA, causes undefined behavior in VM/LLVM

- Added "Box Implementation Checklist"
  - 4-point checklist for Box implementation/changes
  - Covers: --verify, smoke tests, allocator usage, boundary injection

### CLAUDE.md
- Organized "重要設計書" section with clearer structure
- Added "JoinIR 設計図" subsection with both documents:
  - JoinIR アーキテクチャ概要 (normative SSOT for contracts/invariants)
  - JoinIR 設計マップ (navigation SSOT for implementation)
- Grouped related documents: JoinIR, MIR・言語仕様

## Context
Phase 135 revealed that missing "what not to do" (invariants/contracts) in
design docs led to Allocator SSOT violations and ValueId collisions.
This update ensures future Box implementations can follow clear contracts.

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

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 CLAUDE.md                                     |  9 +++++--
 .../current/main/design/joinir-design-map.md  | 25 +++++++++++++++++++
 2 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 746775fa..074c0cd8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -825,10 +825,15 @@ Read docs/reference/  # まずドキュメント（API/言語仕様の入口）
 **設計書がすぐ見つからない問題を解決！**
 
 ### 🏗️ **アーキテクチャ核心**
-- **[JoinIR アーキテクチャ](docs/development/current/main/joinir-architecture-overview.md)** ⭐超重要 - Loop/If/ExitLine/Boundary/PHI の全体図
-- **[名前空間・using system](docs/reference/language/using.md)** - ドット記法・スコープ演算子・Phase 15.5計画
+
+#### JoinIR 設計図（超重要！）
+- **[JoinIR アーキテクチャ概要](docs/development/current/main/joinir-architecture-overview.md)** ⭐超重要 - Loop/If/ExitLine/Boundary/PHI の全体図・契約・不変条件（normative SSOT）
+- **[JoinIR 設計マップ](docs/development/current/main/design/joinir-design-map.md)** ⭐NEW - 実装導線の地図（どのファイルを触るか/入口/Pattern 分類/Allocator SSOT/Boundary SSA/チェックリスト）
+
+#### MIR・言語仕様
 - **[MIR Callee革新](docs/development/architecture/mir-callee-revolution.md)** - 関数呼び出し型安全化・シャドウイング解決
 - **[構文早見表](docs/quick-reference/syntax-cheatsheet.md)** - 基本構文・よくある間違い
+- **[名前空間・using system](docs/reference/language/using.md)** - ドット記法・スコープ演算子・Phase 15.5計画
 
 ### 📋 **Phase 15.5重要資料**
 - **[Core Box統一計画](docs/private/roadmap2/phases/phase-15.5/README.md)** - builtin vs plugin問題
diff --git a/docs/development/current/main/design/joinir-design-map.md b/docs/development/current/main/design/joinir-design-map.md
index 5d768989..546c8428 100644
--- a/docs/development/current/main/design/joinir-design-map.md
+++ b/docs/development/current/main/design/joinir-design-map.md
@@ -130,6 +130,31 @@ JoinIR を触るときは、次を破ったら「即エラーで止める」前
 - ExitLine は「出口へ集約する」ための契約であり、未接続の経路を残さない。
 - carrier/slot の不足・余剰・不整合は `error_tags::exit_line_contract(...)` 等で即エラーにする。
 
+### Allocator SSOT（Phase 135）
+
+- **原則**: すべての ValueId 発行は単一の allocator（`ConditionContext.alloc_value`）を経由する
+- **禁止事項**: ConditionLoweringBox / ExprLowerer での内部カウンタ使用
+- **理由**: JoinIR params (ValueId(1000+)) と衝突し、merge 時に header PHI dst を上書きする
+- **検出**: `--verify` で "Value %N defined multiple times" エラー
+- **修正例**: Phase 135 P0 - ConditionLoweringBox が `&mut ConditionContext` を受け取り、alloc_value を必ず使用
+
+### Boundary Injection SSA（Phase 135）
+
+- **原則**: condition_bindings は alias を許すが、注入 Copy の dst は重複させない
+- **Fail-Fast**: 異なる source が同一 dst に来る場合は即座にエラー
+- **理由**: MIR SSA を破壊し、VM/LLVM で未定義動作を引き起こす
+- **検出**: `joinir_inline_boundary_injector.rs` の重複排除ロジック
+- **修正例**: Phase 135 P0 - Boundary Copy deduplication by dst
+
+### Box 実装チェックリスト
+
+Box を新規実装・変更した際は以下を必ず確認：
+
+1. ✅ `--verify` で契約違反が検出されるか（SSA 破綻・ValueId 衝突）
+2. ✅ smoke test で退行が出ないか（phase132/133/135 など）
+3. ✅ allocator を bypass していないか（ConditionContext.alloc_value を使っているか）
+4. ✅ boundary injection で dst 重複を防いでいるか
+
 ---
 
 ## 追加手順チェックリスト（新しいループ形を飲み込む最小手順）