Summary

Create C++20 module interface files (.cppm) for common_system as part of Epic #256 Phase 2: Module Conversion. This enables modern C++20 module imports across the kcenon ecosystem.

Parent Issue

• [EPIC] C++20 Module Migration - Cross-System Preparation #256 - [EPIC] C++20 Module Migration - Cross-System Preparation

Prerequisites (Completed)

• [REFACTOR] Consolidate Result<T> headers from 9 to 3 - C++20 Module preparation #255 - Result Header Consolidation
• [REFACTOR] Standardize Result API - Deprecate free functions in favor of member methods #258 - Result API Standardization
• Circular dependency analysis (none found)
• Module boundary clarity established

Current State

Header Organization (59 headers in 11 modules):

include/kcenon/common/
├── common.h                    # Public API aggregator
├── fwd.h                       # Forward declarations
├── adapters/                   # Type adapters (3 headers)
├── bootstrap/                  # System bootstrapper (1 header)
├── concepts/                   # C++20 concepts (9 headers)
├── config/                     # Configuration (8 headers)
├── di/                         # Dependency injection (3 headers)
├── error/                      # Error codes (1 header)
├── interfaces/                 # Core interfaces (12 headers)
├── logging/                    # Log utilities (2 headers)
├── patterns/                   # Result, EventBus (14 headers)
└── utils/                      # Utilities (3 headers)

Proposed Module Structure

Primary Module

// src/modules/common.cppm
export module kcenon.common;

export import :result;
export import :interfaces;
export import :concepts;
export import :config;
export import :di;
export import :patterns;
export import :utils;

Module Partitions

Tier 1: Core (No Dependencies)

// :utils partition
export module kcenon.common:utils;
// source_location, circular_buffer, object_pool

// :error partition
export module kcenon.common:error;
// error_codes

Tier 2: Foundation

// :result partition (leverages #255 consolidation)
export module kcenon.common:result;
export import :result.core;       // Result<T>, error_info
export import :result.utilities;  // Factory functions, macros

// :concepts partition
export module kcenon.common:concepts;
// All C++20 concepts

Tier 3: Infrastructure

// :interfaces partition
export module kcenon.common:interfaces;
export import :interfaces.core;       // executor, database, thread_pool
export import :interfaces.monitoring; // metrics, health, alerting
export import :interfaces.transport;  // message, session, connection

// :config partition
export module kcenon.common:config;
// feature_flags, config_loader, cli_config_parser

// :di partition
export module kcenon.common:di;
// service_container, bootstrapper

Tier 4: Application

// :patterns partition
export module kcenon.common:patterns;
// event_bus, helpers

// :logging partition
export module kcenon.common:logging;
// log_functions, log_macros

Implementation Plan

Phase 2a: Setup and Core Modules

• Create src/modules/ directory structure
• Update CMakeLists.txt for C++20 module support
• Implement :utils partition (simplest, no dependencies)
• Implement :error partition
• Verify compilation with CMake 3.28+

Phase 2b: Foundation Modules

• Implement :result.core partition
• Implement :result.utilities partition
• Implement :result aggregator partition
• Implement :concepts partition
• Test Result module imports

Phase 2c: Infrastructure Modules

• Implement :interfaces.core partition
• Implement :interfaces.monitoring partition
• Implement :interfaces.transport partition
• Implement :interfaces aggregator partition
• Implement :config partition
• Implement :di partition

Phase 2d: Application and Integration

• Implement :patterns partition
• Implement :logging partition
• Implement primary kcenon.common module
• Integration testing with all partitions
• Update documentation

CMake Configuration

cmake_minimum_required(VERSION 3.28)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_SCAN_FOR_MODULES ON)

add_library(kcenon_common)
target_sources(kcenon_common
    PUBLIC FILE_SET CXX_MODULES
    FILES
        src/modules/common.cppm
        src/modules/utils.cppm
        src/modules/error.cppm
        src/modules/result/core.cppm
        src/modules/result/utilities.cppm
        src/modules/result.cppm
        src/modules/concepts.cppm
        src/modules/interfaces/core.cppm
        src/modules/interfaces/monitoring.cppm
        src/modules/interfaces/transport.cppm
        src/modules/interfaces.cppm
        src/modules/config.cppm
        src/modules/di.cppm
        src/modules/patterns.cppm
        src/modules/logging.cppm
)

Acceptance Criteria

• All module files compile with CMake 3.28+
• import kcenon.common; works as expected
• Individual partition imports work (e.g., import kcenon.common:result;)
• No circular module dependencies
• Backward compatibility with header includes maintained
• All existing tests pass
• Performance not regressed (compile time within 10%)

Testing Strategy

1. Unit tests for each partition
2. Integration test importing full module
3. Compile time benchmark comparison
4. Downstream system compatibility (thread_system, container_system)

Files to Create

Related

• [EPIC] C++20 Module Migration - Cross-System Preparation #256 - C++20 Module Migration Epic
• [REFACTOR] Consolidate Result<T> headers from 9 to 3 - C++20 Module preparation #255 - Result Header Consolidation (completed)
• Kent Beck "Reveals Intention" principle