Summary

Document the autoscaling subsystem including autoscaler.h, autoscaling_policy.h, and autoscaling_pool_policy.h which enable dynamic thread pool sizing based on workload.

Parent Issue

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

Background (Why)

thread_system includes a sophisticated autoscaling subsystem that dynamically adjusts thread pool size based on workload metrics. This is a key feature for production deployments but is completely undocumented.

Source files:

• include/kcenon/thread/scaling/autoscaler.h — Core autoscaling logic
• include/kcenon/thread/scaling/autoscaling_policy.h — Scaling decision policies
• include/kcenon/thread/pool_policies/autoscaling_pool_policy.h — Pool-level scaling integration

Scope (What)

Create documentation covering:

1. Autoscaling Architecture

• How autoscaler monitors workload metrics
• Decision-making algorithm (scale up/down triggers)
• Integration with thread pool lifecycle

2. Scaling Policies (autoscaling_policy.h)

• Available policy types (threshold-based, queue-depth, latency-target, etc.)
• Policy configuration parameters
• Custom policy interface for user-defined strategies

3. Autoscaler API (autoscaler.h)

• autoscaler class interface
• Configuration options (min/max threads, cooldown periods, sensitivity)
• Start/stop/pause scaling
• Manual override capabilities

4. Pool Integration (autoscaling_pool_policy.h)

• How autoscaling integrates with thread pool policies
• Pool policy composition with autoscaling
• Thread lifecycle during scale-up/scale-down

5. Metrics and Observability

• Which metrics drive scaling decisions
• How to monitor autoscaler behavior
• Logging and diagnostics for scaling events

6. Configuration Examples

// Document configuration patterns
auto scaler = autoscaler::create()
    .min_threads(2)
    .max_threads(16)
    .scale_up_threshold(0.8)    // 80% utilization
    .scale_down_threshold(0.2)  // 20% utilization
    .cooldown(std::chrono::seconds(30))
    .build();

7. Best Practices

• Choosing appropriate thresholds
• Cooldown period recommendations
• Testing autoscaling behavior
• Production monitoring strategies

Acceptance Criteria

• Autoscaling architecture documented with diagram
• All 3 source files' APIs documented
• Scaling decision algorithm explained
• Configuration examples with parameter descriptions
• Best practices for production use
• Integration with thread pool clearly explained