# M7 performance baseline

Measured against `docs/04-engine-design.md` §8's targets, via `tools/bench/vdm_bench`
(see that file's header comment for the exact commands — reproduced below with their
actual output). `--preset release`, this machine, 2026-09-11 through 2026-09-12. This is
a baseline record, not a sign-off: one of the three numbers below is loopback-only rather
than measured against a real 1 Gbit link, stated plainly rather than rounded away — see
"Open gaps". The RSS number *did* fail the DoD line in the first pass through this file;
it's since been root-caused and fixed (`docs/adr/0017`), not just re-measured.

## Commands and results

```
$ cmake --preset release && cmake --build --preset release

$ bin/vdm_bench throughput --size 5G --require-mbps 940 --max-cpu-pct 8
throughput: 5368709120 bytes in 2.99s
  throughput               14371.00 Mbps
  cpu                        196.52 % of one core
  peak RSS                    22.81 MiB
```
Against `tools/bench/support/local_server.hpp`'s busybox loopback server, not a real 1
Gbit link — no such link was available to test against in this environment, so
`--require-mbps`/`--max-cpu-pct` weren't meaningfully exercised here (loopback trivially
clears 940 Mbps; the 196% CPU figure reflects driving a link far faster than 1 Gbit, not
the 1-Gbit-saturated cost the target is about). This needs re-running against a real
1 Gbit peer before it can stand as the actual M1/M7 sign-off number.

```
$ bin/vdm_bench heap-profile --tasks 20 --task-size 4M --top 5
segment budget: 32 live across tasks, engine reports total=32 active=32 starved=9
heap-profile: peak RSS 45.41 MiB, 20 tasks, 8 segments assumed
```
Default `Config` (`default_segments=8`, `max_active_segments=32`, `default_buffer_bytes=1
MiB`), default `--task-size 4M`. **Now clears the 60 MB line** (45.41 MiB), after the real
fix below — root-caused, not just re-measured. Superseded the original `load` run's ~70
MiB number quoted in earlier drafts of this file; see `docs/adr/0017`.

```
$ bin/vdm_bench alloc-check --size 512M --window-s 2
alloc-check: 4 allocations in 2.00s (budget 15)
```
Clears the no-allocation-on-the-hot-path bar (docs/agents/AGENT-CORE.md) comfortably.
This number is *after* a real fix landed in the same change:
`net::HttpClient::Impl::drain_commands` was constructing an (always-allocating, in
libstdc++) `std::deque` on every worker-loop iteration regardless of whether any command
was actually pending — once per curl_multi_poll wake, i.e. on the transfer hot path. Fixed
by checking `w.queue.empty()` under the lock before touching `local` at all. Before the
fix this bench reported thousands of allocations/sec under any sustained transfer.

## ASan / UBSan / TSan (M1 DoD: "20-task load test... clean")

- `--preset dev` (ASan+UBSan) and `--preset tsan`: the full `core/` test suite (40 ctest
  cases, including `veloxcore_engine_test`'s hostile-mode suite and `veloxcore_budget_test`)
  and all three `tools/bench` smoke tests pass clean on both presets.
- Two real bugs were caught and fixed getting here:
  - `DownloadTaskState::quiesce()` (engine shutdown / `Engine`'s destructor) cleared the
    `workers` map synchronously right after issuing an async `transfer.cancel()`, racing
    the HttpClient worker thread's still-in-flight write callback into a heap-use-after-free
    on the segment's ring buffer — ASan-caught via `alloc-check`, which (by design) drops
    its `Engine` while a download is still active. Fixed by having `quiesce()` wait for
    each worker to drain itself through the same `seg_finished` path every other exit uses,
    instead of tearing the map down itself.
  - `SegWorker::speed_bps` (the polled-progress fix, see `engine_polled_progress_reports_
    nonzero_speed`) was written only by a segment's own curl callback and, before this
    session, only ever read from that same thread (`emit_progress_if_due`, called from the
    same callback) — safe without synchronization. Reading it from `snapshot_progress()`
    (any thread calling `DownloadHandle::progress()`) broke that invariant: `workers_mu`'s
    shared_lock protects the `workers` map's structure, not an individual `SegWorker`'s
    mutable fields. TSan-caught. Fixed with `std::atomic<double>` (relaxed: this is an
    informational EMA, nothing synchronizes real state on it) rather than adding a lock to
    the write side.
- The `tools/bench load` ctest registration still runs at reduced concurrency
  (`--tasks 8 --segments 2`) under sanitizer presets (`tools/bench/CMakeLists.txt`) from
  when this was written against `docs/adr/0016`'s postscript — see `docs/adr/0017`'s "Open
  gaps" note: that straggler is now suspected to have been the *same* root cause as the RSS
  bug, not re-verified at the DoD's full shape under `--preset tsan` in this change.

## Open gaps

1. ~~RSS is ~70 MB against a 60 MB target~~ **Fixed — see `docs/adr/0017`.** Root cause
   was not, as first guessed here, an `ADR 0012` arithmetic gap or per-queued-handle curl
   overhead: `SegmentBudget::confirm_slot()` only checked a task's *own* target against
   its own held count, never the engine-wide `active_` sum, so it could (and under real
   20-task/8-segment contention, reliably did) admit segments well past
   `max_active_segments` — `heap-profile` caught it directly: `budget.active` reading
   56–86 against a `total` of 32. Fixed at the budget level (the one place that can
   actually enforce the invariant); `docs/adr/0012`'s own arithmetic was fine all along.
2. **Throughput/CPU numbers are loopback-only.** No 1 Gbit link was available to test
   against; re-run `throughput --size 5G --require-mbps 940 --max-cpu-pct 8` against a real
   one before treating this as signed off.
3. **`docs/adr/0016`**: `rate::RateLimiter`'s global-limit path (byte-rate pacing, a
   different subsystem from the segment-admission bug in `docs/adr/0017`) has no fairness
   ordering under heavy segment contention (a shared `TokenBucket`'s peek/commit race can
   starve a waiter indefinitely) — a real, separate, still-open gap for the "global
   bandwidth cap with many concurrent downloads" scenario.
4. **The TSan-only load-test straggler** noted in `docs/adr/0016`'s postscript, found
   before `docs/adr/0017`'s fix landed: plausibly the *same* root cause (a segment denied
   admission with nothing to wake it, worse under TSan's slowdown widening the window a
   deferred yield can sit in) rather than the `CURLOPT_LOW_SPEED_TIME` guess that ADR
   originally offered — not reverified at the DoD's full 20-task/8-segment shape under
   `--preset tsan` in this change (the sanitizer-preset smoke registration still runs at
   reduced concurrency; see `tools/bench/CMakeLists.txt`). Worth re-running before treating
   it as closed.