From 2dc5ccecec74decff0b4e3726535dd1bd8bc3452 Mon Sep 17 00:00:00 2001 From: nyash-codex Date: Sat, 13 Dec 2025 19:06:53 +0900 Subject: [PATCH] docs(joinir): Phase 84 - Glossary + debug flag documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 84 最小化実装: - 0.1 用語セクション拡張: SSOT, Fail-Fast 追加 - デバッグフラグ新セクション: HAKO_JOINIR_DEBUG 推奨化、後方互換説明 - Phase 82-83 統合後の状態反映 Not included (Phase 84 後回し): - Duplicate heading consolidation - Phase 74-81 comprehensive summary section 次: 箱化モジュール化 + レガシー削除調査 --- .../main/joinir-architecture-overview.md | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/development/current/main/joinir-architecture-overview.md b/docs/development/current/main/joinir-architecture-overview.md index e675a964..9633e4b0 100644 --- a/docs/development/current/main/joinir-architecture-overview.md +++ b/docs/development/current/main/joinir-architecture-overview.md @@ -36,13 +36,32 @@ --- -## 0.1 用語（routing / fallback / fail-fast） +## 0.1 用語・デバッグフラグ（Glossary & Debug Flags） + +### 用語（routing / fallback / fail-fast） 本文では「fallback」という単語が文脈でぶれやすいので、先に用語を固定する： - **routing**: JoinIR Core 内での正規な経路選択（Pattern ルータ、if-sum mode ↔ legacy P3 など）。理由が分かる形でログ/タグを付ける。 - **soft fallback**: 任意箱（pre-validation / optional optimizer）が失敗したときに、同等意味論の別 JoinIR 経路へ退避すること（JoinIR Core 外へは出ない）。 - **prohibited fallback**: 非 JoinIR への退避（例: LoopBuilder）・サイレント退避・契約違反の握りつぶし。 +- **SSOT** (Single Source of Truth): 設計・実装・テストの情報が集約される唯一の場所（e.g., `is_joinir_debug()` for debug flag reading）。Phase ドキュメントより SSOT ドキュメントを優先参照。 +- **Fail-Fast**: エラー条件を明示的に検出・報告し、サイレント退避や暗黙的フォールバックを禁止する設計原則。 + +### デバッグフラグ（Phase 82 SSOT 統一） + +JoinIR デバッグログを有効にするには **`HAKO_JOINIR_DEBUG=1`** を使用（`NYASH_JOINIR_DEBUG=1` は deprecated）: + +```bash +# 推奨（Phase 82 以降） +HAKO_JOINIR_DEBUG=1 cargo test --release --lib + +# Legacy（Phase 82 以前、後方互換保証） +NYASH_JOINIR_DEBUG=1 cargo test --release --lib +``` + +実装: `src/config/env/joinir_flags.rs::is_joinir_debug()` が両者をチェック。 +詳細: `docs/development/current/main/phase82-83-debug-flag-ssot-summary.md` ## 1. 不変条件（Invariants）