hakorune/docs/development/current/main/ring0-inventory.md

Ring0 Inventory & println! Categorization (Phase 99)

Overview

This document provides an inventory of Ring0.log infrastructure and categorizes the remaining println!/eprintln! call sites across the codebase. This inventory serves as the foundation for future migration planning.

Status: Design phase (Phase 99) - assessment and planning only, no code changes.

---

Section 1: Ring0.log Utilization Status

Current Infrastructure (Phase 99 Start)

Implemented:

• Ring0Context contains log: Arc<dyn LogApi>
• LogApi trait with methods:
  • debug(message: &str)
  • info(message: &str)
  • warn(message: &str)
  • error(message: &str)
• StdLog implementation outputs to stdout/stderr

Location: crates/nyash_kernel/src/ring0/log.rs

---

Phase 95-98 Usage

ConsoleService Implementation (Phase 95-98):

• PluginHost established with CoreServices
• ConsoleService provides user-facing output
• console_println! macro consolidates user messages
• Ring0.log remains underutilized (future expansion target)

Current Ring0.log Usage: Minimal

• Primary logging still uses raw println!/eprintln!
• Opportunity for consolidation exists

---

Section 2: println!/eprintln! Remaining Call Sites

Overall Statistics

Total: 1776 locations (Phase 99 initial assessment)

• Test code: ~299 locations
• Production code: ~1477 locations

Source: Phase 99 initial assessment via rg 'println!|eprintln!'

Historical Context (Phase 88-90):

• Phase 88-90 migrated 56 locations to ring0.log.*
• Phase 90 migrated 12 locations to ring0.fs/time/thread.*
• Previous total: 3,955 locations → Current: 1,776 locations

---

Category Breakdown (Design Phase)

Category 1: user-facing (~366 locations, HIGH priority)

Description: CLI messages, errors, help text, and other user-visible output

Target Migration: console_println! macro

Priority: HIGH (directly visible to end users)

Phase 98 Progress: 7 locations completed (representative paths)

Phase 100-101 Plan: Gradual expansion

Example Locations:

• src/runner/ - CLI entry points
• Error messages in main execution paths
• Help text and usage information
• Progress indicators

---

Category 2: dev-debug (TBD, MEDIUM priority)

Description: Temporary debug output for development purposes

Target Migration: Ring0.log or dev_* macros (to be decided later)

Priority: MEDIUM

Phase 99 Scope: Assessment only - determine if Ring0.log is appropriate

Decision Deferred: Phase 100+

Considerations:

• Is this debug output needed in production?
• Should it use Ring0.log.debug()?
• Or should it be removed entirely?
• Or should it use a special dev_* macro?

---

Category 3: test (~299 locations, LOW priority)

Description: Test output and verification messages

Target Migration: None - keep as-is

Priority: LOW (safe in isolated environment)

Phase 99-101 Plan: No changes

Rationale:

• Tests run in isolated environments
• println! is appropriate for test output
• No migration needed

Example Locations:

• Test assertion messages
• Test progress indicators
• Debug output during test execution

---

Category 4: internal (~812 locations, TBD)

Description: Internal processing println! remnants

Target Migration: TBD

Priority: To be determined in Phase 99

Phase 99 Scope: Initial categorization

Subcategories (to be refined):

• Internal errors (could use Ring0.log.error)
• State transitions (could use Ring0.log.debug)
• Legacy debug output (could be removed)
• Performance metrics (could use Ring0.log.info)

---

Section 3: Ring0.log Expansion Plan (Sketch)

Future Directions (Not Implemented)

This section outlines potential future uses of Ring0.log. Implementation is deferred to Phase 100+.

---

Option 1: Error Log Consolidation

Concept: Unify error logging through Ring0.log

Examples:

// VM execution errors
ring0.log.error(&format!("VM execution failed: {}", err));

// Parser errors
ring0.log.error(&format!("Parse error at line {}: {}", line, msg));

// MIR lowering errors
ring0.log.error(&format!("Lowering failed for {}: {}", node, reason));

Benefits:

• Centralized error logging
• Consistent error format
• Easy to redirect to files or monitoring systems

Phase 99 Decision: Concept documented, implementation deferred

---

Option 2: Internal State Logging

Concept: Use Ring0.log for runtime state tracking

Examples:

// Memory usage
ring0.log.debug(&format!("Memory allocated: {} bytes", size));

// GC triggers
ring0.log.info("Garbage collection triggered");

// Cache events
ring0.log.debug(&format!("Cache hit rate: {}%", rate));

Benefits:

• Non-intrusive diagnostics
• Performance monitoring
• Debugging production issues

Phase 99 Decision: Concept documented, implementation deferred

---

Option 3: Execution Tracing

Concept: Trace program execution through Ring0.log

Examples:

// Function entry/exit
ring0.log.debug(&format!("Entering function: {}", name));

// State transitions
ring0.log.info(&format!("State changed: {} -> {}", old, new));

// Performance markers
ring0.log.debug(&format!("Operation completed in {}ms", duration));

Benefits:

• Detailed execution visibility
• Performance profiling
• Bug reproduction

Phase 99 Decision: Concept documented, implementation deferred

---

Implementation Priority (Future)

Phase 100-101 Focus: User-facing migrations (console_println!)

Phase 102+ Candidates:

1. Error log consolidation (HIGH impact)
2. Internal state logging (MEDIUM impact)
3. Execution tracing (LOW impact, high cost)

Decision Point: After console_println! migration is complete

---

Section 4: Call Site Distribution

By Module (Approximate)

src/runner/: ~366 locations

• Priority: HIGH (user-facing)
• Target: console_println!

src/mir/: ~200 locations

• Priority: MEDIUM (internal/debug)
• Target: Ring0.log or removal

src/parser/: ~150 locations

• Priority: MEDIUM (internal/debug)
• Target: Ring0.log or removal

tests/: ~299 locations

• Priority: LOW (keep as-is)
• Target: None

Other: ~761 locations

• Priority: TBD
• Target: TBD

---

By Type (Approximate)

Error messages: ~400 locations

• User errors → console_println!
• Internal errors → Ring0.log.error

Debug output: ~600 locations

• Development debug → Ring0.log.debug or removal
• Temporary debug → removal

Progress/info: ~200 locations

• User progress → console_println!
• Internal progress → Ring0.log.info

Test output: ~299 locations

• Keep as-is

Other: ~277 locations

• TBD

---

Section 5: Migration Roadmap

Phase 99 (Current): Documentation & Planning

Objectives:

• ✅ Document Ring0.log infrastructure
• ✅ Categorize remaining println!/eprintln! call sites
• ✅ Establish migration strategy
• ✅ Define completion criteria

Deliverables:

• This document (ring0-inventory.md)
• Logging policy (logging_policy.md)
• Updated core_boxes_design.md Section 15.6-A

---

Phase 100-101: User-Facing Migrations

Objectives:

• Migrate ~366 user-facing println! to console_println!
• Focus on src/runner/ paths
• Ensure all CLI messages use ConsoleService

Estimated Effort: Medium (straightforward replacements)

Success Criteria:

• All user-visible messages use console_println!
• No println! in main execution paths
• Tests still pass

---

Phase 102+: Internal Logging

Objectives:

• Evaluate Ring0.log usage for internal logging
• Migrate or remove dev-debug println!
• Consolidate error logging

Estimated Effort: Variable (requires case-by-case analysis)

Success Criteria:

• Clear separation: Ring0.log (internal) vs ConsoleService (user)
• No unnecessary println! in production code
• Test println! remains untouched

---

Section 6: Grep Commands for Investigation

Finding Call Sites

# All println!/eprintln! in source code
rg 'println!|eprintln!' --type rust

# Excluding tests
rg 'println!|eprintln!' --type rust --glob '!**/tests/**' --glob '!**/test_*.rs'

# Only in src/runner/
rg 'println!|eprintln!' --type rust src/runner/

# Only in src/mir/
rg 'println!|eprintln!' --type rust src/mir/

# Only in tests
rg 'println!|eprintln!' --type rust --glob '**/tests/**' --glob '**/test_*.rs'

---

Finding console_println! Usage

# Current console_println! usage
rg 'console_println!' --type rust

# Potential candidates for console_println!
rg 'eprintln!\("Error:|Warning:|Info:' --type rust

---

Finding Ring0.log Usage

# Current Ring0.log usage
rg 'ring0\.log\.(debug|info|warn|error)' --type rust

# LogApi trait implementations
rg 'impl.*LogApi' --type rust

---

Section 7: Historical Migration Data (Phase 88-90)

Phase 88-90: ring0.log.* Migration (56 locations)

Migrated Files:

• src/runner/selfhost.rs: 11 locations
• src/runner/modes/vm.rs: 22 locations
• src/runner/modes/vm_fallback.rs: 4 locations
• src/runner/modes/common_util/hack_check.rs: 19 locations

Impact: Consolidated user-facing error messages to Ring0.log.error()

---

Phase 90: Ring0 API Migration (12 locations)

Phase 90-A: fs API (7 locations):

• src/runner/modes/common_util/resolve/strip.rs: 4 locations
• src/runner/dispatch.rs: 1 location
• src/runner/mod.rs: 3 locations
• Migration: std::fs::read_to_string → ring0.fs.read_to_string

Phase 90-C: time API (3 locations):

• src/runner/modes/common_util/selfhost_exe.rs: 1 location
• src/runner/modes/common_util/io.rs: 1 location
• src/runtime/plugin_loader_unified.rs: 1 location
• Migration: Instant::now() + elapsed() → ring0.time.monotonic_now() + ring0.time.elapsed()

Phase 90-D: thread API (2 locations):

• src/runtime/global_hooks.rs: 1 location
• src/runtime/plugin_loader_unified.rs: 1 location
• Migration: std::thread::sleep → ring0.thread.sleep

---

Section 8: Success Metrics

Completion Criteria

Phase 99 Complete when:

• ✅ Ring0.log infrastructure documented
• ✅ println!/eprintln! call sites categorized
• ✅ Migration strategy established
• ✅ Roadmap defined for Phase 100+

Phase 100-101 Complete when:

• All user-facing println! migrated to console_println!
• src/runner/ paths use ConsoleService exclusively
• Test println! remains untouched

Phase 102+ Complete when:

• Internal logging uses Ring0.log appropriately
• No unnecessary println! in production code
• Clear separation of concerns maintained

---

Related Documentation

• Logging Policy - Role separation and macro policy
• CoreBoxes Design - Section 15.6-A - Architectural context
• Phase 85 CURRENT_TASK - Implementation timeline

---

Summary

Phase 99 establishes a clear inventory of logging infrastructure and println! call sites:

1. Ring0.log: Underutilized, ready for expansion
2. println!/eprintln!: 1477 production call sites categorized into 4 groups
3. Migration strategy: Phased approach starting with user-facing messages
4. Success criteria: Clear metrics for each phase

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