Remove --autotune

[martinus]

Closes #150.

--autotune is the one feature that can quietly make oans slower, and it does so persistently.

The measurement

On a 32-core NVMe box the storage heuristic picks 8, matching what CLAUDE.md already records: "8 was the knee (7.3s), 16/32 gave no wall gain while sys exploded (16→23→46s)".

Autotune, run as a normal user, recommends and stores 16:

  threads   time       throughput
  8         1s         942.6 MiB/s
  12        1s         1.1 GiB/s
  16        1s         1.2 GiB/s     <- best

Recommended: --io-threads=16
Stored in the hashfile; future runs use --io-threads=16 automatically.

$ sqlite3 h.db "select keyname, keyval from config where keyname like '%autotune%'"
autotune_io_threads|16

$ oans -rv --hashfile=h.db ...
Using autotuned --io-threads=16 from the hashfile

Without root it cannot drop caches, so it measures memory bandwidth — which keeps scaling with threads long past the point where btrfs metadata contention caps real cold throughput. It prints a warning and then persists the answer anyway, into the hashfile the systemd timer replays forever.

So the documented NAS setup path, followed without sudo, silently locks in a thread count worse than the default the user would have got for free.

Why remove rather than fix

• On SSD it has nothing to find. min(nproc, 8) is the validated path, so autotune either agrees (no value) or disagrees by measuring the wrong thing (negative value).
• On HDD it is the only real evidence — but unobtainable. The constants are admittedly guesses, yet autotune needs root and cold reads to say anything true, and CLAUDE.md already records that it cannot be measured meaningfully on the dev box.
• scripts/bench.py --walk-threads already answers the question properly — cold, interleaved, medians — as a dev tool that does not write to the hashfile.

Gating persistence behind a verified cold measurement was considered; it fixes the harmful path but leaves 532 lines and a documented setup step earning nothing on the hardware most people run.

What goes

src/autotune.{c,h}, its integration test, the --autotune mode and its report-mode exclusivity, the autotune_io_threads config key and its reader, and dbfile_set_config_int() (autotune was its only caller). Step 2 of the NAS quick-start is removed and the remaining steps renumbered — the cache-directory setup it carried moves into the new Step 2. Man page, README, zsh completion, benchmarks and two stale code comments updated.

Net −739/+41 across 15 files.

Compatibility

No schema bump. create_tables() is unchanged and a stale autotune_io_threads key in an existing hashfile is simply never read again. Verified directly: injected the key into a hashfile, re-scanned, and the run fell back to the heuristic with no error.

The heuristic itself is untouched — storage_recommend_io_threads() and its unit tests are unchanged, so the default sizing behaves exactly as before.

scripts/verify.sh passes: build with warnings-as-failure, 116 tests, valgrind scan+dedupe+replay smoke.

🤖 Generated with Claude Code