Summary

Addresses #331

This PR creates a comprehensive unified error code registry document that catalogs all error codes across the kcenon ecosystem, verifies ranges, and provides cross-system error handling guidance.

Changes

docs/ERROR_CODES.md (759 lines):

• Error Code Range Allocation Table: Complete allocation table for 8 systems with usage statistics
• Per-System Error Code Catalog: Detailed catalogs for all systems:
  • Common Errors (-1 to -99): 11 codes
  • thread_system (-100 to -199): 14 codes
  • logger_system (-200 to -299): 9 codes (centralized)
  • monitoring_system (-300 to -399): 10 codes
  • container_system (-400 to -499): 12 codes
  • database_system (-500 to -599): 12 codes
  • network_system (-600 to -699): 11 codes
  • pacs_system (-700 to -799): 24 codes
  • logger_system (Alternate): ~60 positive integer codes (1-1999)
• Error Code Lookup: Programmatic lookup using get_error_message() and get_category_name() helper functions
• Cross-System Error Handling: Patterns for error propagation across system boundaries with Result<T> wrapper
• Compile-Time Verification: Documentation of static assertions that prevent range violations at compile time
• Verification Script: Optional Python script for CI integration to verify uniqueness

Key Findings

Total Error Codes: 103 negative integer codes + ~60 positive integer codes (logger_system alternate)

Range Utilization:

• common_system: 11 / 99 (11%)
• thread_system: 14 / 100 (14%)
• logger_system: 9 / 100 (9%)
• monitoring_system: 10 / 100 (10%)
• container_system: 12 / 100 (12%)
• database_system: 12 / 100 (12%)
• network_system: 11 / 100 (11%)
• pacs_system: 24 / 100 (24%)

No Overlapping Codes: All error codes are unique and within designated ranges, enforced by compile-time static assertions in /include/kcenon/common/error/error_codes.h.

Dual Error Code Systems:

• Centralized System: Negative integers (-1 to -799) in common/error/error_codes.h for cross-system errors
• logger_system Internal: Positive integers (0-1999) in logger/core/error_codes.h for detailed internal operations

Cross-System Error Handling Patterns

The document provides concrete examples for:

• Thread System → Logger System error propagation
• Database System → Network System error conversion
• Error context addition when wrapping errors
• Best practices for maintaining error chains

API Documentation

Programmatic Lookup:

#include <kcenon/common/error/error_codes.h>

int code = kcenon::common::error::codes::thread_system::pool_full;
auto message = kcenon::common::error::get_error_message(code);
// Returns: "Thread pool full"

auto category = kcenon::common::error::get_category_name(code);
// Returns: "ThreadSystem"

Cross-System Error Wrapping:

// Preserve original error code and add context
auto result = database_operation();
if (result.is_err()) {
    return make_error<T>(
        result.error().code,
        result.error().message + " (context: " + additional_info + ")",
        result.error().category + "/subsystem"
    );
}

Test Plan

• Documentation accurately reflects source code (error_codes.h)
• All 103 centralized error codes documented
• logger_system's alternate 60+ error codes documented
• No overlapping codes (verified by compile-time assertions)
• Error code ranges match header file definitions
• Helper function APIs documented with examples
• Cross-system error handling patterns provided
• Verification script example included (optional CI integration)

Closes #331