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**:
```rust
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
// 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**:
```rust
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](ring0-inventory.md) - println! categorization and Ring0.log plans
- [CoreBoxes Design - Section 15.6-A](core_boxes_design.md#section-156-a-logsoutput-unified-design) - Architectural context
- [Phase 85 CURRENT_TASK](../../../CURRENT_TASK.md) - 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.