bench: FLAT_ENTRIES knob, 20k gate default, liveness heartbeat

The flat-dir case at 120k entries takes ~8 minutes per mke2fs run
(quadratic dirent insertion), which made the recurring CI gate look
hung and cost most of an hour. The gate now runs a 20k-entry flat dir
on the normal 1+5 schedule; FLAT_ENTRIES=120000 remains available for
dedicated headline runs (2 runs, no warmup). A 30s heartbeat keeps CI
logs showing liveness during long runs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: nikhilunni

tools/bench.sh

@@ -3,15 +3,19 @@
 #
 #   (a) small-files: ~120k small files across nested dirs (node_modules-like)
 #   (b) big-files:   ~4 GiB tree containing multi-GiB files
-#   (c) flat-dir:    120k files in ONE directory (pnpm-store shape; the
-#                    case the htree requirement exists for)
+#   (c) flat-dir:    FLAT_ENTRIES files in ONE directory (pnpm-store shape;
+#                    the case the htree requirement exists for)
 #
 # Usage: tools/bench.sh [outdir]
 #   E2SBIN         e2fsprogs sbin dir (default: brew keg or PATH)
 #   BENCH_SMALL=0  skip the small-files benchmark
 #   BENCH_BIG=0    skip the big-files benchmark
 #   BENCH_FLAT=0   skip the flat-dir benchmark
-#   ASSERT_FASTER=1  exit nonzero unless mkext4 wins both
+#   FLAT_ENTRIES=N flat-dir size (default 20000 for the recurring gate:
+#                  mke2fs is QUADRATIC on flat directories — at 120k
+#                  entries a single mke2fs run takes ~8 minutes, so the
+#                  full-size case is for dedicated headline runs only)
+#   ASSERT_FASTER=1  exit nonzero unless mkext4 wins every case
 #
 # Requires hyperfine.
 
@@ -48,15 +52,15 @@ print(n, "files", file=sys.stderr)
 EOF
 }
 
-make_flat_tree() {    # 120k small files in a single directory
-    local t=$1
+make_flat_tree() {    # $2 small files in a single directory
+    local t=$1 n=$2
     [ -d "$t" ] && return
-    echo "generating flat-dir tree..." >&2
-    python3 - "$t" <<'PYEOF2'
+    echo "generating flat-dir tree ($n files)..." >&2
+    python3 - "$t" "$n" <<'PYEOF2'
 import os, sys
 d = os.path.join(sys.argv[1], "flat")
 os.makedirs(d, exist_ok=True)
-for i in range(120000):
+for i in range(int(sys.argv[2])):
     with open(os.path.join(d, "entry_%06d_pad" % i), "wb") as fh:
         fh.write(b"x" * (100 + (i * 37) % 2000))
 PYEOF2
@@ -74,13 +78,22 @@ make_big_tree() {     # ~4 GiB: two multi-GiB files + some medium ones
     done
 }
 
-run_case() {          # $1 name, $2 tree, $3 image-blocks, $4 inode count
-    local name=$1 tree=$2 blocks=$3 inodes=$4
+run_case() {          # $1 name, $2 tree, $3 image-blocks, $4 inodes, $5 runs, $6 warmup
+    local name=$1 tree=$2 blocks=$3 inodes=$4 runs=${5:-5} warmup=${6:-1}
     local img_a="$OUT/$name-mke2fs.img" img_b="$OUT/$name-mkext4.img"
-    echo "== $name" >&2
-    hyperfine --warmup 1 --runs 5 --export-json "$OUT/$name.json" \
+    echo "== $name ($runs runs + $warmup warmup)" >&2
+    # Heartbeat so CI logs show liveness during long runs (a slow run is
+    # not a hang: mke2fs is quadratic on flat directories). Exits on its
+    # own if the script dies mid-benchmark.
+    local t0=$SECONDS
+    ( while sleep 30; do kill -0 $$ 2>/dev/null || exit
+          echo "   [$name] still benchmarking, $((SECONDS - t0))s elapsed" >&2; done ) &
+    local hb=$!
+    hyperfine --warmup "$warmup" --runs "$runs" --export-json "$OUT/$name.json" \
         --command-name mke2fs     "rm -f $img_a && $E2SBIN/mke2fs $MKFS_OPTS -N $inodes -d $tree $img_a $blocks" \
         --command-name mkext4 "rm -f $img_b && MKEXT4_INODES=$inodes $MKFS_RS $tree $img_b $((blocks * 4096))"
+    kill "$hb" 2>/dev/null || true
+    wait "$hb" 2>/dev/null || true
     # Sanity: our image must be fsck-clean.
     "$E2SBIN/e2fsck" -fn "$img_b" >/dev/null
     python3 - "$OUT/$name.json" <<'EOF'
@@ -99,8 +112,17 @@ if [ "${BENCH_SMALL:-1}" = 1 ]; then
     run_case small "$OUT/tree-small" 262144 160000    # 1 GiB image
 fi
 if [ "${BENCH_FLAT:-1}" = 1 ]; then
-    make_flat_tree "$OUT/tree-flat"
-    run_case flat "$OUT/tree-flat" 262144 160000      # 1 GiB image
+    FLAT_ENTRIES=${FLAT_ENTRIES:-20000}
+    FLAT_TREE="$OUT/tree-flat-$FLAT_ENTRIES"   # keyed by size: no stale cache
+    make_flat_tree "$FLAT_TREE" "$FLAT_ENTRIES"
+    if [ "$FLAT_ENTRIES" -ge 60000 ]; then
+        # 2 runs, no warmup: a single mke2fs pass over a flat 120k-entry
+        # directory takes ~8 minutes (quadratic dirent insertion), so the
+        # usual 1+5 schedule would cost an hour for no extra signal.
+        run_case flat "$FLAT_TREE" 262144 $((FLAT_ENTRIES + 40000)) 2 0  # 1 GiB image
+    else
+        run_case flat "$FLAT_TREE" 262144 $((FLAT_ENTRIES + 40000))     # 1 GiB image
+    fi
 fi
 if [ "${BENCH_BIG:-1}" = 1 ]; then
     make_big_tree "$OUT/tree-big"