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: Design phase (Phase 99) - documentation only, no code implementation yet.

---

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.

---

Related Documentation

• Ring0 Inventory - println! categorization and Ring0.log plans
• 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.