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**:
```rust
// 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**:
```rust
// 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**:
```rust
// 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

```bash
# 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

```bash
# 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

```bash
# 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](logging_policy.md) - Role separation and macro policy
- [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 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.