# Optimization Ranking

This file is the current Phase 6 ranking for `aria2-rust-pro` Take 2.

It is intentionally evidence-first. Each item below exists because current
benchmarks, size reports, or runtime traces show a real remaining cost or a
real verification gap.

## Current Ranking

### 1. Shared-runtime live HTTP fixed cost

Why it ranks first:

- this is the hottest still-open product path inside the current Phase 6 work
- it already has multiple real wins landed in Take 2
- the latest product-side scheduler change removed the previous loose-cap/cache
  pressure cliff, so remaining work is now narrower fixed-cost work rather than
  broad fanout underutilization
- it is still the clearest place where a product-side win can move the current
  benchmark surface

Current evidence:

- after the latest scheduler and writeback pass, focused Criterion runs now
  land at:
  - `loose_cap`: `23.429 .. 23.998 ms`
  - `tight_cap`: `23.592 .. 24.049 ms`
  - `tight_cap_6way`: `26.089 .. 26.510 ms`
  - `cache_pressure_6way_256k`: `20.255 .. 21.380 ms`
- after the later CLI config-projection cleanup, exact reruns kept the same
  `tight_cap` band and pushed the current shared-runtime `6way` absolute band
  materially lower:
  - exact `tight_cap`: `23.224 .. 23.603 ms`
  - exact `tight_cap_6way`: `13.422 .. 13.824 ms`
- after the latest small-segment probe and admitted-download segment-budget
  pass, the current focused shared-runtime band moved again:
  - `loose_cap`: `12.567 .. 13.399 ms`
  - `tight_cap`: `12.674 .. 13.071 ms`
  - `tight_cap_6way`: `13.773 .. 14.212 ms`
  - `cache_pressure_6way_256k`: `7.793 .. 8.019 ms`
- the later broader short bench-surface refresh kept that band and improved it
  slightly:
  - `loose_cap`: `11.696 .. 11.935 ms`
  - `tight_cap`: `11.732 .. 11.957 ms`
  - `tight_cap_6way`: `12.649 .. 12.855 ms`
  - `cache_pressure_6way_256k`: `7.137 .. 7.452 ms`
- Criterion reports significant improvement in all four shared-runtime lanes:
  - `loose_cap`: roughly `-7.2% .. -3.4%` wall time
  - `tight_cap`: roughly `-4.4% .. -1.6%` wall time
  - `tight_cap_6way`: roughly `-31.9% .. -29.3%` wall time
  - `cache_pressure_6way_256k`: roughly `-14.9% .. -9.5%` wall time
- the new result is a product-path Phase 6 win: runtime now recognizes the
  upstream-compatible `max-concurrent-downloads` surface, does not throttle
  already-registered same-runtime HTTP bootstrap work through the smaller
  active-download queue value, uses even worker partitioning instead of
  under-filling workers on `6 / 5` style workloads, and collapses segment
  dispatcher writeback to the final response per download
- before that fix, the loopback driver imposed a serialized service-side floor
  near `96 ms` / `192 ms` because one server worker processed `12` / `24`
  range requests one at a time with an `8 ms` synthetic response delay
- direct timing with `ARIA2_RUST_PRO_HTTP_TIMING=1` showed that, in the shared
  runtime live HTTP path, the dominant remaining fixed cost was in
  request/connection/send rather than dispatcher writeback
- the same timing probe also confirmed that bootstrap/segment
  `record_http_transfer_result` work is currently `0 ms` on this host in the
  hot shared-runtime lane, so further wins need to come from request shape or
  transport cost rather than from more dispatcher-writeback trimming
- the latest exact `tight_cap_6way` timing rerun now shows the hot small-file
  shared-runtime lane completing all six downloads in the bootstrap request
  alone:
  - `planned_segments=0` for every download
  - `bootstrap_persist_ms=0`
  - `bootstrap_record_ms=0`
  - per-request `send_ms` is now typically `10 .. 11 ms` on top of the driver
    `8 ms` response delay
- that means the previous app-side bookkeeping cliff is gone in this lane; the
  remaining cost is now mostly transport-side send/response floor rather than a
  large remaining dispatcher or persistence tax
- after the latest writeback and segment-tag cleanup, targeted reruns from the
  current tree show the larger segmented/cache-pressure lane is back in the
  fast band and the small 6-way lane improves again:
  - `tight_cap_6way`: `13.008 .. 13.228 ms`
  - `cache_pressure_6way_256k`: `7.819 .. 7.988 ms`
- after the latest reqwest prepared-request contention pass, focused exact
  reruns stay in the same fast band while trimming one more product-path fixed
  cost in the shared-runtime connector hot path:
  - `tight_cap_6way`: mean about `13.117 ms`
  - `cache_pressure_6way_256k`: mean about `7.900 ms`
- root cause for that pass: in concurrent shared-runtime small-file bursts, the
  private prepared-request cache could become mostly contention cost because
  many one-shot URI shapes fought over the same mutex before any real reuse
  existed
- the current connector now treats prepared-request caching as opportunistic:
  repeated shapes still reuse cached URL/header preparation when the lock is
  available, but contended callers fall back to local uncached preparation
  instead of blocking on the cache mutex
- this pass specifically addresses the broader segmented workload instead of
  spending more time on the already near-floor no-follow-up small-file path

Already-landed wins in this lane:

- shared default reqwest client reuse for no-proxy traffic
- initial probe widened from `bytes=0-0` to the first real segment span
- tiny post-probe tails that would previously fan out into three one-alignment
  follow-up requests are now coalesced into two larger follow-up requests
- small-alignment segmented transfers now let the initial range probe cover two
  complete `max-connection-per-server` windows, reducing real follow-up range
  request count for small live HTTP transfers
- shared-runtime segment fanout now budgets against already-admitted downloads
  rather than reusing the smaller active-download queue cap after admission
- the live reqwest connector now also raises its same-host idle connection
  budget, keeps idle range-transfer connections warm for short bursts, and
  enables TCP keepalive; the broader bench-surface rerun kept live HTTP lanes
  fast after this connector change
- `max-concurrent-downloads` is now part of the compat option registry and
  runtime projection, with an upstream-compatible default of `5`
- small static HTTP work sets are partitioned evenly across available workers
  instead of using contiguous chunks that can under-fill the thread set
- shared-runtime follow-up records now update dispatcher state once per
  download from the final segment response, instead of once per range response
- direct URI dispatcher registration
- incremental verified-prefix writeback
- shared-runtime follow-up dispatch through one connection-budgeted segment
  batch
- no-clone first-attempt retry fast path
- concurrent loopback segment-server handling in the Criterion suite, which
  prevents synthetic service-side serialization from hiding client/runtime
  concurrency
- shared-runtime follow-up segments now execute through one batched fanout based
  on active downloads and `max-connection-per-server`, instead of spawning
  nested per-download segment workers during bootstrap preparation
- live streamed response sinks no longer perform an explicit file flush after
  every `reqwest::blocking::Response::copy_to`; write/copy errors are still
  surfaced, while range-heavy live transfers avoid a repeated per-response
  writeback tax
- shared-runtime segment batches now carry the download index as the tag and
  store each segment target path once per download, removing one `PathBuf` clone
  per planned segment and reducing batch-result allocation churn
- reqwest prepared live-request caching now falls back to local request
  preparation when the shared cache lock is contended, which keeps repeated
  range-request reuse available without forcing one-shot concurrent request
  bursts to wait on the cache mutex

Explicitly not counted as a measured shared-runtime win yet:

- proxy-specific reqwest clients are cached by proxy config, but there is still
  no dedicated proxy-path benchmark proving its standalone impact; keep it as
  sensible hot-path cleanup rather than counting it as ranked measured evidence

What still looks promising:

- lower per-request request/connection/send overhead
- more disciplined validation of where blocking reqwest still pays fixed cost
- only product-path reductions, not benchmark-only cosmetics

What has already been tried and rejected:

- forcing shared-runtime follow-up parallelism to honor the global overall cap
  regressed the lane by about `9% .. 10%`
- swapping the local worker batches to rayon did not produce a meaningful win
- leaking prepared-request state into the public `HttpRequestModel` was rejected;
  the kept version confines reqwest-specific URL/header preparation cache state
  to `ReqwestHttpConnector`

### 2. Binary size pressure from the RPC + HTTP/TLS stack

Why it ranks second:

- size evidence is now in-tree and clearly points at one dominant cluster
- the current binary is already smaller than both the checked C++ Pro Core and
  the upstream Windows binary, so this is no longer emergency work
- there is still a clear future size lane, but it is less urgent than the live
  shared-runtime HTTP hot path

Current evidence:

- current Windows Rust binary: `4.94 MiB` (`5,184,512` bytes)
- current checked upstream Windows aria2 binary: `5.39 MiB`
- current checked C++ Pro Core binary: `10.88 MiB`
- top `cargo bloat --crates` buckets are:
  - `aria2_rust_pro_rpc`
  - `reqwest`
  - `rustls`
  - `std`
  - `aria2_rust_pro_protocol`

Interpretation:

- deeper size work should focus on the combined RPC + HTTP/TLS surface
- one recent owned-code win already landed inside the CLI bucket by replacing
  repeated config `BTreeMap<String, String>` materialization with direct
  last-wins directive lookup, which notably shrank
  `derive_http_session`, `derive_runtime_config`, and
  `build_ftp_transfer_parts`
- current CLI-side LLVM IR evidence is refreshed at `53,272` total lines across
  `307` function copies, down from the older `59,204` / `320` snapshot
- this is now a ranked future optimization lane, not a closure blocker by
  itself

### 3. RPC pressure guard depth

Why it ranks third:

- current synthetic RPC responsiveness evidence now covers both a deterministic
  integration guard and Criterion pressure anchors
- this remains a ranked lane because the workload is still synthetic and should
  not be overclaimed as a public-swarm certification
- it is no longer an immediate Phase 6 evidence blocker

Current evidence:

- the current pressure guards:
  - repeated `tellStatus`
  - sampled `getFiles`
  - repeated `tellActive`
  - repeated `tellGlobalStat`
  - BT-like synthetic runtime churn
- the denser mixed guard now covers 96 BT-like magnet tasks over 6 rounds,
  including 576 `tellStatus` calls and 72 sampled `getFiles` calls under
  per-download runtime tick churn
- current Criterion anchors include:
  - `rpc_mixed_pressure/mixed_rpc/96`: `92.383 us`
  - `rpc_mixed_pressure/mixed_rpc/192`: `175.169 us`
  - `bt_visibility_pressure/bt_visibility/32`: `2.3293 ms`
  - `bt_visibility_pressure/bt_visibility/64`: `2.1302 ms`
- the current guard is documented in `rpc-pressure-evidence.md`
- that document explicitly says the thresholds are broad and not a final
  performance certification

Needed future expansion:

- higher scheduler pressure
- clearer resource counters suitable for long-term perf reporting

### 4. Same-host comparison noise and interpretation discipline

Why it still matters:

- the local comparison report is now useful and much less misleading than it
  used to be
- but it is still a whole-process host-local comparison, not a precision
  microbenchmark

Current evidence:

- `local-comparison.md` now reports medians and spread after warmup
- the driver no longer suffers from coarse accept/sleep quantization
- the Rust rows now complete with matching payload size and SHA256

Interpretation:

- this report is good enough to act as a local regression anchor
- it should not be overclaimed as precise proof for micro-optimizations

## Current Phase 6 Read

What is already true:

- benchmark evidence exists
- size/bloat evidence exists
- multiple real product-side wins are already landed and documented
- the current hottest open lane is identified and ranked
- non-HTTP RPC and BT-visibility pressure now have current deterministic and
  Criterion evidence
- the Phase 6 shared-runtime loose-cap/cache cliff is fixed by product code,
  not by benchmark-only masking
- current broader bench, bloat, binary-size, and LLVM-lines evidence are now
  synchronized with the latest Phase 6 tree

What is not yet honest to claim:

- that the shared-runtime live HTTP lane is fully exhausted
- that size work is fully exhausted
- that the current RPC pressure guard is a public-network performance
  certification

## References

- `progress.md`
- `docs\perf\local-comparison.md`
- `docs\perf\rpc-pressure-evidence.md`
- `docs\perf\size-evidence.md`