# alderbench

Sister app to [aldermon](../aldermon) for the same Alder Lake box
(i5-12600KF, ASRock Z690M ITX/ax). Runs **comparative benchmarks and CPU
stress tests** across stock vs OC/UV configurations, with a live TUI and
a JSON report file on exit.

Standalone — no shared code with aldermon. Sensor conventions and the
config parser shape are mirrored, not linked.

## Usage

```sh
cargo run --release                # run configured workloads, live TUI (default)
cargo run -- --report runs/foo.json   # print a past run's human summary
cargo run -- --list                # enumerate available workloads
```

The TUI needs a real terminal (pty); it will not run on redirected output.

## Workloads

v1 drives **stress-ng** (`/usr/bin/stress-ng`, unprivileged for CPU
classes) for stability testing — CPU stressors at a configurable core
count and duration, with per-tick sensor traces (vCore, package power,
package temp, peak clock) captured throughout. Stability verdict per run:
clean / WHEA seen / throttle seen / crash.

Additional workloads (mprime, y-cruncher, phoronix-test-suite) are
pluggable via the `Workload` trait but not yet implemented — see
`to-do.md`.

## Config

`alderbench.conf` is read from the working directory, then
`~/.config/alderbench/alderbench.conf`. Simple `KEY = VALUE` lines; `#`
comments; unknown keys ignored. All values optional — defaults target the
i5-12600KF / Z690M ITX box.

```ini
workloads     = stress-ng-cpu     # comma list (v1: only stress-ng-cpu)
duration_secs = 60                # per-workload run length
poll_ms       = 250               # sensor sample interval
cool_secs     = 15                # cooldown between workloads
vcore_limit   = 1.403             # shown as marker on the vCore hero
temp_crit     = 95.0              # throttle/crit flag threshold
report_dir    = ./runs            # where JSON reports are written
```

## Reports

Each run writes `./runs/<timestamp>-<workload>.json` (`schema_version: 1`):
run metadata, per-tick sensor samples, workload exit status, and a
stability verdict. A human summary is also printed to stdout after the
TUI exits. Incremental flush — a crash mid-run still leaves a partial
report.

## Package power (RAPL)

`energy_uj` is root-only on this kernel. To read watts as a normal user,
install aldermon's udev rule once (it covers both apps — same box, same
device):

```sh
doas ../aldermon/powercap-pl-rules.sh
doas usermod -aG adm $USER   # then re-login
```

## Status

Scaffold. See `to-do.md` for the build order.