[Refactor] Adopt common_system error_category for typed error codes

[kcenon]

Summary

Migrate messaging_system's error codes from raw integer constants to common_system's new typed_error_code + error_category framework, enabling type-safe error handling with rich error context across the messaging infrastructure.

Parent Epic

Part of: #215 (Ecosystem Dependency Sync - Q1 2026)

Background

common_system introduced a structured error category infrastructure (commit aa542e0, #302):

• include/kcenon/common/error/error_category.h (432 lines)
• typed_error_code type with implicit conversion to error_info
• Result<T> now accepts typed_error_code directly
• Provides compile-time error code categorization

messaging_system currently uses raw integer error codes in the range -700 to -799:

// Current: error_codes.h
namespace kcenon::messaging::error {
    // Message errors (-700 to -719)
    constexpr int INVALID_MESSAGE = -700;
    constexpr int MESSAGE_TOO_LARGE = -701;
    // ...
    
    // Routing errors (-720 to -739)
    constexpr int NO_ROUTE_FOUND = -720;
    // ...
    
    // Queue errors (-740 to -759)
    constexpr int QUEUE_FULL = -740;
    // ...
    
    // Transport errors (-780 to -799)
    constexpr int TRANSPORT_NOT_CONNECTED = -780;
    // ...
}

Technical Specification

Current State

// Usage in messaging_system
return common::make_error<T>(
    common::error_codes::INTERNAL_ERROR,  // Generic common error code
    "Queue is full",
    "message_queue"
);

// Or with messaging-specific codes
return common::make_error<T>(
    error::QUEUE_FULL,  // Raw integer -740
    "Message queue capacity exceeded",
    "message_queue"
);

Target State

// Define messaging error category
class messaging_error_category : public common::error_category {
public:
    static const messaging_error_category& instance();
    
    std::string_view name() const noexcept override { return "messaging"; }
    std::string message(int code) const override;
};

// Define typed error codes
namespace kcenon::messaging::error {
    using typed_code = common::typed_error_code<messaging_error_category>;
    
    // Message errors
    inline constexpr typed_code invalid_message{-700, "Invalid message format"};
    inline constexpr typed_code message_too_large{-701, "Message exceeds size limit"};
    
    // Routing errors
    inline constexpr typed_code no_route_found{-720, "No matching route for message"};
    
    // Queue errors
    inline constexpr typed_code queue_full{-740, "Message queue capacity exceeded"};
    
    // Transport errors
    inline constexpr typed_code transport_not_connected{-780, "Transport not connected"};
}

// Usage - cleaner and type-safe
return common::Result<T>{error::queue_full};
// Automatically creates error_info with code, message, and category

Implementation Tasks

Phase 1: Define Error Category

• Create include/kcenon/messaging/error/messaging_error_category.h
• Implement messaging_error_category class
• Register category with common_system registry

Phase 2: Convert Error Codes

• Convert message errors (-700 to -719) to typed codes
• Convert routing errors (-720 to -739) to typed codes
• Convert queue errors (-740 to -759) to typed codes
• Convert subscription errors (-760 to -779) to typed codes
• Convert transport errors (-780 to -799) to typed codes

Phase 3: Update Error Construction Sites

• Replace common::make_error<T>(code, msg, component) with Result<T>{typed_code}
• Update all error construction in message_serializer.h
• Update all error construction in message_bus.cpp
• Update all error construction in message_broker.cpp
• Update all error construction in transport adapters
• Update all error construction in task module

Phase 4: Backward Compatibility

• Keep integer constants as deprecated aliases
• Ensure error code values remain unchanged (-700 to -799)
• Verify error matching/comparison still works

Phase 5: Testing

• Unit tests for error category
• Verify error propagation through Result
• Verify error messages are correct
• Integration test error handling paths

Acceptance Criteria

• All messaging error codes defined as typed_error_code
• messaging_error_category registered with common_system
• Error construction simplified at all call sites
• Backward compatibility maintained (same integer values)
• All tests pass
• Error messages are descriptive and consistent

Dependencies

• Depends on: common_system validation ([Build] Validate and fix common_system indirect include compatibility #218) — error_category header must be available
• Non-blocking: can be done incrementally

Related Issues

• [Epic] Ecosystem Dependency Sync - Q1 2026 Upstream Changes Integration #215 - Parent epic
• [Refactor] Adopt Result<T> pattern for transport layer error handling #207 - Previous Result adoption work

[kcenon]

Implementation PR: #235

This addresses Phase 2 (typed error codes via codes enum), Phase 4 (backward compatibility), and Phase 5 (unit tests). Phase 3 (call site migration) is tracked in #230.