hakorune/docs/development/current/main/logging_policy.md

Logging & Output Policy (Phase 99)

Overview

This document establishes the clear separation of concerns between three logging/output layers in the Nyash runtime, and provides guidelines for transitioning the remaining ~1477 println!/eprintln! call sites to the appropriate mechanism.

Status: Phase 101-B in progress — documentation plus partial internal log migration (Ring0.log) and test-output policy fixed.

---

Section 1: Three-Layer Log/Output Role Separation

The Nyash runtime uses three distinct layers for logging and output, each with a specific purpose:

Layer 1: Ring0.log (OS API Layer)

Purpose: Runtime/OS layer internal logging

Use Cases:

• Memory management state
• Garbage collection events
• Thread management
• Cache information
• Internal state tracking

Target Audience: Developers, debugging, measurement, internal state tracking

API:

ring0.log.debug("message");
ring0.log.info("message");
ring0.log.warn("message");
ring0.log.error("message");

Characteristics:

• Not intended for direct user visibility
• Controlled by log levels
• Can be redirected to files or monitoring systems
• Developer-facing diagnostics

---

Layer 2: ConsoleService (Box Layer - User-Facing)

Purpose: Direct CLI output for end users

Use Cases:

• Error messages displayed to users
• Success notifications
• Help text
• Progress information
• Command execution results

Target Audience: End users of the Nyash CLI

Access Methods:

1. Via console_println! macro (Rust code)
2. Via host.core.console.println(...) (Box code)

API:

// Rust side
console_println!("User-visible message");

// Box side
host.core.console.println("User-visible message");

Characteristics:

• Active after PluginHost initialization
• Falls back to eprintln! before initialization (Graceful Degradation)
• User-friendly messages
• Respects output redirection

---

Layer 3: Raw println!/eprintln! (Restricted Use)

Purpose: Limited to tests and temporary debugging only

Restrictions:

• Should be removed from production paths
• Should be removed from selfhost/hack_check/VM runner paths
• Permitted in test code (isolated environment)

Current Status:

• Test code: ~299 instances (permitted)
• Production code: ~1477 instances (to be migrated)

Phase 99 Stance:

• Judgment only in Phase 99
• Implementation deferred to Phase 100+
• Test code println! remains as-is (safe in isolated environment)

---

Section 2: Macro Policy

console_println! Macro (Implemented in Phase 98)

Purpose: Safe entry point for user-facing messages

Implementation:

macro_rules! console_println {
    ($($arg:tt)*) => {{
        if let Some(host) = try_get_core_plugin_host() {
            host.core.console.println(&format!($($arg)*));
        } else {
            eprintln!($($arg)*);  // Graceful fallback
        }
    }};
}

Usage Locations:

• selfhost runner main output
• hack_check result display
• VM runner main output (RC, errors, etc.)

Design Principle:

• Follows Fail-Fast principle with exception for output destination selection
• Dynamic fallback is permitted for "where to output" decision only
• Core logic remains static and deterministic

---

dev_eprintln! / Other dev_* Macros (Under Consideration)

Purpose: Temporary debug output during development

Phase 99 Decision:

• Evaluate necessity only
• No implementation in Phase 99
• Implementation deferred to Phase 100+

Rationale:

• Most use cases can be covered by Ring0.log or console_println!
• May be redundant with existing logging infrastructure
• Need to assess actual developer needs before implementing

---

Section 3: Test Code println! Policy

Current Status

• Test code: ~299 instances of println!/eprintln!
• Purpose: Test output and result visualization
• Location: Throughout test modules

Policy

Phase 99 Stance: Leave as-is - OK to use println! in tests

Rationale:

1. Tests run in isolated environments
2. Test output is separate from production output
3. println! is safe and appropriate for test diagnostics
4. No need for special test macros (println_test!, etc.)

Future Considerations: No changes planned

---

Section 4: Complete Integration Criteria

The "CoreServices Log/Output Complete Integration" is considered achieved when:

Console (Required)

• ✅ All selfhost runner user-facing output uses console_println!
• ✅ All hack_check result display uses console_println!
• ✅ All VM runner main output (RC, errors) uses console_println!

Current Status (Phase 98):

• ✅ 7 locations completed
• ✅ Representative paths covered
• 🔄 ~359 locations remaining (Phase 100-101)

---

Ring0.log (Phased)

Existing Infrastructure:

• debug/info/warn/error API available
• StdLog implementation outputs to stdout/stderr

Migration Priority:

1. Internal errors → ring0.log.error(...)
2. VM execution logs → ring0.log.info(...)
3. Memory/GC information → ring0.log.debug(...)

Phase 99 Scope: Planning only - document migration strategy

---

Tests (Permitted)

• Test code println! (~299 locations): Keep as-is
• Production paths: Removed (migration complete)

---

Section 5: Migration Strategy

Phase-by-Phase Approach

Phase 99 (Current):

• Document policy and categorization
• No code changes
• Establish migration framework

Phase 100-101:

• Migrate user-facing println! to console_println! (~366 locations)
• Prioritize src/runner/ paths
• Focus on visible user messages

Phase 102+:

• Evaluate Ring0.log usage for internal logging
• Migrate dev-debug println! as needed
• Leave test println! unchanged

---

Categorization of Remaining println!/eprintln!

Total: 1776 locations (1477 excluding tests)

Categories:

1. user-facing (~366 locations, priority: high)

   • CLI messages, errors, help text
   • Target: console_println!
   • Phase 98: 7 completed (representative paths)
   • Phase 100-101: Gradual expansion

2. dev-debug (TBD, Ring0.log candidates)

   • Temporary debug output
   • Target: Ring0.log or dev_* macros (to be decided)
   • Priority: Medium
   • Phase 99: Assessment only

3. test (~299 locations, priority: low)

   • Test output and verification
   • Target: Keep as-is (isolated environment)
   • Phase 99-101: No changes

4. internal (~812 locations remaining)

   • Internal processing println! remnants
   • Target: TBD in Phase 99
   • Phase 99: Uncategorized

---

Section 6: Design Principles

Graceful Degradation

The console_println! macro implements graceful degradation:

• Primary: Use ConsoleService when available
• Fallback: Use eprintln! before PluginHost initialization
• Rationale: Output should always work, even during early initialization

This is the only permitted exception to the Fail-Fast principle, as it only affects output destination, not core logic.

---

Separation of Concerns

Each layer has a clear responsibility:

• Ring0.log: Developer diagnostics
• ConsoleService: User communication
• println!: Test-only convenience

This separation ensures:

• Maintainability: Clear ownership of output
• Testability: Test output isolated from production
• Flexibility: Each layer can be configured independently

---

Migration Philosophy

80/20 Rule Applied:

• Phase 98: 7 locations = covering representative paths
• Phase 100-101: ~366 locations = user-visible improvements
• Phase 102+: Remaining locations = diminishing returns

Focus on high-impact migrations first, defer low-priority changes.

---

Section 4: .hako側ロギング方針 (Phase 104)

概要

Nyash（.hako）アプリケーションからのロギングは、ConsoleBoxを通じてユーザーに伝える方式に統一。

Note: Phase 105では Logger Box フレームワークが正式化され、より構造化された ロギングが可能になりました。詳細は Logger Box Design を参照。

パターン分類

Pattern 1: ユーザー向けメッセージ（user-facing）

用途: ユーザーに表示される情報

• エラーメッセージ
• 進捗情報
• 成功/完了通知

実装方法:

box MyApp {
    console: ConsoleBox

    main() {
        me.console = new ConsoleBox()

        // ✅ 正しい方法: ConsoleBox経由
        me.console.println("Processing started...")

        // 実装例: エラーハンドリング
        if error_occurred {
            me.console.println("❌ Error: " + error_msg)
            return 1
        }

        me.console.println("✅ Success!")
        return 0
    }
}

ガイドライン:

• すべてのユーザー向けメッセージは ConsoleBox.println() 使用
• エラーメッセージは "❌" 絵文字で開始
• 成功メッセージは "✅" 絵文字で開始
• 進捗は "[1/10]" などの形式で表示

Pattern 2: デバッグ/診断ログ（dev-debug）

用途: 開発時のデバッグ情報

• 変数値のダンプ
• 関数entry/exit
• 分岐の選択記録

実装方法 (Phase 104では ユーザーアプリ側は println! 許容):

box MyApp {
    main() {
        // 現在: ユーザーアプリが debug print 時は println! OK
        // 将来 (Phase 105): ユーザー定義ロギングフレームワーク検討

        local debug_enabled = false  // 環境変数から読む
        if debug_enabled {
            print("[DEBUG] Processing item: " + item_id)
        }
    }
}

ガイドライン:

• デバッグ出力は "[DEBUG]" prefix で統一
• bool flag で on/off 制御（環境変数参照）
• 本番環境では全削除推奨

Pattern 3: 監視/メトリクス（monitoring）

用途: 運用時の監視情報

• 実行時間計測
• メモリ使用量
• 処理レート

実装方法:

box PerformanceMonitor {
    console: ConsoleBox
    start_time: IntegerBox

    begin() {
        me.console = new ConsoleBox()
        me.start_time = runtime.now()
    }

    report() {
        local elapsed = runtime.now() - me.start_time
        me.console.println("[PERF] Elapsed: " + elapsed + "ms")
    }
}

ガイドライン:

• メトリクスは "[PERF]" prefix で統一
• 定期レポーティング推奨
• Ring0.log（Rust側）と連携可能（将来拡張）

設計原則（.hako側視点）

1. Single Responsibility: 各Boxは1つのロギング目的に専念
2. Testability: ログ出力をテスト可能にする（interface化）
3. Composability: ロギングBoxを組み合わせる
4. Zero Config Default: 環境変数なしでもロギング動作

アンチパターン（避けるべき書き方）

// ❌ ダメな例 1: raw println!を散乱
print("value: " + x)  // → Boxにロギング機能を出す

// ❌ ダメな例 2: ConsoleBoxの多重初期化
box MyBox {
    main() {
        local console = new ConsoleBox()
        console.println("msg1")

        local console2 = new ConsoleBox()  // ← 重複初期化
        console2.println("msg2")
    }
}

// ❌ ダメな例 3: ロギングロジック混在
box DataProcessor {
    process(data) {
        if validate(data) {
            print("OK")  // ← 出力ロジックが混在
            return process_data(data)
        }
    }
}

// ✅ 正しい例: 責務分離
box DataProcessor {
    logger: LoggerBox

    process(data) {
        if validate(data) {
            return process_data(data)
        } else {
            me.logger.error("Validation failed")
            return null
        }
    }
}

今後の拡張予定

Phase 105: ユーザー定義ロギングフレームワーク

• Logger Box interface化
• ログレベル統一（DEBUG/INFO/WARN/ERROR）
• Structured logging (JSON形式)

Phase 106: ログ出力先の切り替え

• ConsoleBox → FileBox
• ConsoleBox → NetworkBox
• Pluggable logger architecture

テストでのロギング

テストコード内のロギング/println!は許容:

// ✅ テストコード内
test my_test {
    local result = my_function()
    print("Result: " + result)  // テスト内 OK
    assert(result == expected)
}

理由: テストは隔離環境実行のため、ログ管理の必要がない

---

Phase 122: ConsoleBox.println / log の統一

使い分けガイドライン

用途	推奨 API	理由
selfhost / CLI	ConsoleService / console_println!	Ring0 経由で安定
ユーザーコード	ConsoleBox.println	ユーザー向け sugar
内部実装	ConsoleBox.log	VM レベルでは同じ

正規化ルール

• ConsoleBox.println は VM の TypeRegistry で ConsoleBox.log（slot 400）に正規化される
• JSON v0 / selfhost / 通常VM のすべての経路で同じ動作を保証
• Rust から直接使用する場合も println / log の両方が使用可能

---

関連ドキュメント

• Logger Box Design - Phase 105 structured logging framework
• .hako側ロギング設計 - Phase 104 ユーザーアプリ視点
• ring0-inventory.md - Ring0.log利用状況の在庫管理
• core_optional_design.md - CoreServices optional化
• CoreBoxes Design - Section 15.6-A - Architectural context
• Phase 85 CURRENT_TASK - Implementation timeline

---

Summary

Phase 99 establishes the documentation foundation for future logging/output migrations:

1. Clear role separation: Ring0.log (internal) vs ConsoleService (user-facing) vs println! (test-only)
2. Macro policy: console_println! (implemented), dev_* macros (under consideration)
3. Test policy: println! in tests is OK (isolated environment)
4. Migration strategy: Phased approach with clear priorities

Next Steps: Phase 100+ will implement gradual migrations based on this policy framework.

---

Section 7: Phase 100 Implementation Complete (2025-12-03)

user-facing 出力の CoreServices 化完了

実装概要: selfhost と LLVM runner の主要なユーザー向け出力を ConsoleService (console_println!) 経由に統一

完了箇所:

• selfhost.rs: 6箇所 → console_println!
  • Line 57: CoreInitError 出力
  • Line 194, 363, 418, 519, 570: Result 出力
• llvm.rs: 23箇所（ユーザー向けメッセージ） → console_println!
  • Line 26, 44, 53, 60, 116: エラーメッセージ（❌）
  • Line 121-122: 成功メッセージ（📊）
  • Line 215, 230, 239, 275, 287, 295: LLVM/harness エラー
  • Line 324, 328, 334-335, 353-354, 357-358, 362: 実行結果
  • Line 369-370, 379, 383, 391: Mock LLVM メッセージ
• vm.rs: 1箇所（Phase 98 で完了済み）
• core_bridge.rs: 2箇所（Phase 98 で完了済み）
• selfhost 関連: 5箇所（Phase 98 で完了済み）

合計: Phase 98 (7箇所) + Phase 100 (29箇所) = 36箇所完了

除外箇所（意図的に残した）:

• llvm.rs の [joinir/llvm], [parse/context] デバッグログ（Phase 101 対象）
• hack_check: .hako アプリ（Nyash言語の ConsoleBox 経由、別フェーズ）

テスト結果:

• ✅ cargo build --release 成功
• ✅ core_services テスト: 11 passed
• ✅ plugin_host テスト: 7 passed
• ✅ 代表ケース動作確認:
  • loop_min_while.hako: "📊 MIR Module compiled successfully!" 等が console_println! 経由で出力
  • エラーケース: "❌ Error reading file..." が console_println! 経由で出力

残りの user-facing 出力:

• 推定: ~330箇所（その他の runner/modes/*）
• 優先度: HIGH → Phase 101-102 で段階的拡張

技術的成果:

• selfhost/LLVM runner のユーザー向けメッセージが ConsoleService に統一
• Phase 99 で確立したログ/出力ポリシーが実装レベルで実現
• デバッグログとユーザー向け出力の明確な分離

---

Section 7-A: Phase 101-A dev-debug ログの Ring0.log 統一（2025-12-03）

dev-debug ログ ~34箇所を Ring0.log に統一

実装概要: llvm.rs, loop_form.rs, phi_core モジュールの代表的なデバッグログを Ring0.log に移行

完了箇所:

• llvm.rs: 13箇所 → Ring0.log

  • [joinir/llvm] デバッグログ: 12箇所（JoinIR 実験パス関連）
  • [parse/context] デバッグログ: 1箇所（プリロードファイル一覧）

• loop_form.rs: 全 [loopform] ログ → Ring0.log

  • [loopform] 基本ログ: 変数マップ、ブロックID等
  • [loopform/condition] ログ: 条件式処理関連
  • [loopform/writes] ログ: 変数書き込み収集
  • [loopform/27.4-C] ログ: JoinIR ヘッダーφバイパス

• phi_core モジュール: 21箇所 → Ring0.log

  • loopform_builder.rs: 16箇所
    • [loopform/prepare] ログ: 構造準備、変数分類、サマリー
    • [loopform/seal_phis] ログ: PHI シール処理
  • loop_snapshot_merge.rs: 5箇所
    • [Option C] ログ: Exit PHI 分類、変数解析

実装パターン:

// Before
eprintln!("[loopform] variable_map size={}", size);

// After
crate::runtime::get_global_ring0().log.debug(&format!(
    "[loopform] variable_map size={}", size
));

合計: Phase 101-A で 34箇所のデバッグログを Ring0.log に統一

テスト結果:

• ✅ cargo build --release 成功（警告のみ、エラーなし）
• ✅ VM実行テスト: loop_min_while.hako 正常動作
• ✅ デバッグログが stderr に出なくなることを確認

環境変数制御:

• NYASH_LOOPFORM_DEBUG=1: LoopForm 関連デバッグログ有効化
• NYASH_OPTION_C_DEBUG=1: Option C 関連デバッグログ有効化
• Ring0.log のログレベル設定で出力制御可能

残りの dev-debug ログ:

• 推定: ~585箇所（全体 ~615箇所から Phase 101-A の 34箇所を除く）
• 対象外: test 出力（~347箇所、Phase 101-B で別途検討）
• 対象外: internal 出力（Phase 101-B で別途検討）

技術的成果:

• Ring0.log で dev-debug ログを一元管理
• 環境に応じた出力制御が可能（将来の活用に向けて）
• stderr の cleanness 向上（ユーザー向けメッセージのみになる）
• Phase 99-100 で確立した 3層設計を実装レベルで完成

---

Section 7-B: Phase 101-B internal/test ログ整理（2025-12-04）

内部ログを Ring0.log に寄せ、テスト出力ポリシーを固定

実装概要:

• internal/dev ログ 26 箇所を Ring0.log に移行（stderr 汚染を削減） → 第1バッチ
  • 対象: provider_lock.rs, plugin_loader_unified.rs, type_meta.rs, deprecations.rs, leak_tracker.rs
  • Plugin loader v2 系: loader/config.rs, loader/library.rs, loader/metadata.rs, instance_manager.rs, ffi_bridge.rs
• internal/dev ログ 21 箇所を追加で Ring0.log 化 → 第2バッチ
  • 対象: provider_verify.rs, scheduler.rs, gc_controller.rs, box_registry.rs
  • Plugin loader v2 specs: loader/specs.rs（TypeBox ABI/trace）
  • Runner trace: runner/trace.rs（cli_verbose トレース）
  • MIR verifier dev-trace: mir/verification.rs（NYASH_BREAKFINDER_SSA_TRACE/NYASH_DEBUG_VERIFIER）
• internal/dev ログ 20 箇所を追加で Ring0.log 化 → 第3バッチ
  • MIR core: basic_block.rs, control_form.rs, hints.rs, effect.rs, printer.rs, optimizer.rs
• internal/dev ログ 26 箇所を追加で Ring0.log 化 → 第4バッチ
  • MIR builder/region: loop_builder/phi_ops.rs, builder/type_registry.rs, region/observer.rs
  • Plugin loader v2: enabled/extern_functions.rs（trace）/types.rs（finalize trace）
• internal/dev ログ 20 箇所を追加で Ring0.log 化 → 第5バッチ
  • MIR loop_builder JoinIR: joinir_if_phi_selector.rs（dry-run trace）, control.rs（LoopForm debug）
  • MIR builder observe: observe/types.rs（NYASH_MIR_TYPE_TRACE）, observe/resolve.rs（NYASH_DEBUG_KPI_KNOWN）
  • joinir VM bridge: join_ir_vm_bridge_dispatch/exec_routes.rs（run_generic_joinir_route trace）
  • Plugin loader v2: enabled/extern_functions.rs（NYASH_DEBUG_TRACE / runtime_checkpoint_trace / NYASH_BOX_INTROSPECT_TRACE）
• ログレベル整理: init/loader 失敗は error、warn-once 系は warn、トレースは debug/info に整理
• ログレベル整理: init/loader 失敗は error、warn-once 系は warn、トレースは debug/info に整理

テスト出力方針:

• Rust テスト内（src/tests/, tests/）の println!/eprintln! は原則許容（大きな出力のみ将来検討）
• 本フェーズではテストコードは無変更、ポリシーを docs に明文化

残件:

• internal/dev ログ残量: 概算で ~475–495 箇所（引き続き段階的に Ring0.log へ移行/削除）
• user-facing: console_println! 移行は別ラインで継続
• .hako/hack_check: Rust とは別フェーズで整理

成果:

• Ring0/Ring1/Core の責務分離を保ったまま internal ログを OS 抽象層に集約
• 環境変数ベースのデバッグトレース（PLUGIN_DEBUG, HAKO_*）も Ring0.log 経由に統一
• stderr のノイズ低減とログ観測の一元化を達成