docs(design): adaptive thread-pool sizing replaces static num_cpus*2

[oferchen]

Summary

Cross-cutting design ADR that replaces the static num_cpus * 2 defaults in two recently-landed designs with feedback-driven adaptive sizing.

Amends:

• docs/design/buffer-pool-sharding.md (PR docs(design): sharded BufferPool layout for high thread counts #3645, merged) - shard count was num_cpus * 2.
• docs/design/daemon-async-accept-sync-workers.md (PR docs(design): daemon async accept loop with sync transfer workers #3649, open) - transfer worker pool was num_cpus * 2.

The static default underutilizes idle cores on I/O-bound workloads (long-haul SSH, slow disk) and oversubscribes on CPU-bound workloads (compression, checksum). This note specifies a single adaptive sizer both sites can opt into, joining the existing adaptive family alongside the BufferPool capacity resizer (#1640 / #1641) and adaptive queue depth (#1735).

Key sections

• Telemetry signals: pool utilization, queue depth/stall, per-worker idle EWMA, CPU vs I/O classification - all reused from existing adaptive subsystems with no new hot-path counters.
• Two sizing modes considered: PI-controller in [60%, 85%] band (recommended) vs AIMD (rejected as too jittery for long-running transfers).
• Hard bounds: [max(2, num_cpus / 2), num_cpus * 4].
• Asymmetric cadence: 5 s grow, 30 s shrink. Convergence guard for thrash detection.
• Override path: OC_RSYNC_ADAPTIVE_THREADS=0 env-var disable; transfer-worker-threads = adaptive | <fixed> daemon config knob; BufferPool::with_capacity(Adaptive | Fixed) API.
• Failure semantics: sizer runs on a dedicated thread under catch_unwind; on panic, pool stays at last-known-good size, no respawn loop.
• Telemetry: structured debug_log! line at -vv per sizing decision (mirrors Update oc help banner to use branded daemon wording #1369 SPSC contention metrics pattern).
• Migration plan: 5 phases with default-on + env-var disable; remove disable after one release once telemetry confirms stability.
• Risks: oscillation, memory bloat, sizer overhead at low concurrency, sizer-vs-sizer interaction, integration churn - each with explicit mitigation.
• Rayon thread pool sizing explicitly NOT adopted (rayon's own scheduler conflicts).

Wire-compat invariants

Zero impact. Pool sizing is process-internal. The sizer does not change the rsync wire protocol, multiplex framing, daemon greeting, auth handshake, file-list / delta / end-of-transfer envelopes, or any frame's byte count, byte order, or padding. Same invariant the two parent designs already establish.

Test plan

• No code changes - design doc only, so the only verification is documentation review.
• CI fmt + lint on the markdown file (no Rust touched).
• Reviewer cross-check of cited file:line references against current crates/engine/src/local_copy/buffer_pool/ and crates/daemon/src/daemon/.