Summary

Document the adapter framework in common_system including typed_adapter, smart_adapter, and the base adapter abstraction that enable cross-system integration.

Parent Issue

Part of: [EPIC] docs: Address documentation gaps across all ecosystem systems (#325)

Background (Why)

The adapter framework is a cornerstone of the kcenon ecosystem, enabling type-safe integration between systems. For example, typed_adapter<ILogger, logger> connects logger_system to any system that needs logging. Despite being used across all systems, the adapter framework itself has no documentation.

Source files:

• include/kcenon/common/adapters/adapter.h — Base adapter abstraction
• include/kcenon/common/adapters/adapters.h — Adapter collection/registry
• include/kcenon/common/adapters/typed_adapter.h — Type-safe adapter template
• include/kcenon/common/adapters/smart_adapter.h — Smart pointer-based adapter

Scope (What)

1. Adapter Pattern in kcenon

• Why adapters instead of direct dependencies
• How adapters enable loose coupling between systems
• Adapter lifecycle (create → register → resolve → use)

2. Base Adapter (adapter.h)

• Base interface and virtual methods
• Adapter identification (name, type info)
• Ownership semantics

3. Typed Adapter (typed_adapter.h)

• Template: typed_adapter<Interface, Implementation>
• Type erasure mechanism
• Compile-time type safety guarantees
• How to create typed adapters for new interfaces

// Example: Connecting logger to database system
auto logger_adapter = make_typed_adapter<ILogger>(my_logger);
container.register_adapter(logger_adapter);

4. Smart Adapter (smart_adapter.h)

• Smart pointer integration (shared_ptr, unique_ptr)
• Ownership transfer semantics
• Reference counting and lifecycle management
• When to use smart_adapter vs typed_adapter

5. Adapter Registry (adapters.h)

• How adapters are registered and discovered
• Lookup by type, name, or capability
• Adapter replacement and hot-swapping
• Thread safety of the registry

6. Cross-System Integration Examples

• logger_system ↔ database_system via adapter
• thread_system ↔ monitoring_system via adapter
• Complete DI container setup with adapters

7. Creating Custom Adapters

• Step-by-step guide to implementing new adapters
• Interface design best practices
• Testing adapter implementations

Acceptance Criteria

• All 4 adapter headers documented
• typed_adapter template usage fully explained
• smart_adapter ownership semantics documented
• Adapter registry API documented
• At least 3 cross-system integration examples
• Custom adapter creation guide provided