Document what duct's resource statistics actually measure

[asmacdo]

Explain the semantics of each field (pcpu, rss, pmem, vsz) under duct's current ps-based sampler, where the numbers are reliable, and where they mislead. Motivated by recurring confusion: peak_pcpu exceeding Ncores × 100% (issue #399), peak_vsz reaching terabytes on workloads with only GBs of real memory, and total_* disagreeing with sum(per-pid) in aggregated records. All are correct behavior of ps semantics and duct's max-reduction aggregation — not bugs — but there was no reference explaining why.

Scope is current behavior only; alternative samplers (psutil, cgroup) will be documented separately.

TODO:

• consider alternatives, start design doc PR and potentially reference here for discussion
• 1 line per sentence, other cleanup/human review
• Create some scenarios and/or tests to demonstrate this behavior

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.87%. Comparing base (2162da9) to head (231c454).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #414   +/-   ##
=======================================
  Coverage   91.87%   91.87%           
=======================================
  Files          15       15           
  Lines        1120     1120           
  Branches      139      139           
=======================================
  Hits         1029     1029           
  Misses         69       69           
  Partials       22       22           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.