bench: overhaul benchmark suite, auto-fetch vendors, and refresh charts

- Add strict data dependency chain (checksum sink) to prevent GCC 16 LTO dead-code elimination
- Replace std::stack + malloc with foonathan::memory (memory_stack)
- Add automatic vendor fetching (bench_deps) and building in Makefile
- Re-render throughput charts with solid dark card backgrounds for light/dark theme safety
- Update README benchmark tables and metrics with fresh 4-matrix test results

Author: gooderfreed

.github/assets/memory_efficiency_chart.png

@@ -71,4 +71,5 @@ benchmark
 benchmark_*
 wasi*
 perf.data
-bench/perf*
+bench/perf*
+bench/vendor

.github/assets/throughput_large_payloads.png

@@ -71,18 +71,45 @@ FUZZ_DEBUG_BINS = $(FUZZ_SRCS:%.c=%_debug)
 FUZZ_FLAGS = -fsanitize=fuzzer,address,undefined -O3 -g3 -fno-omit-frame-pointer
 FUZZ_DEBUG_FLAGS = -fsanitize=fuzzer,address,undefined -O0 -g3 -fno-omit-frame-pointer -DESTACK_FUZZ_DEBUG -DDEBUG
 
-# --- Benchmark Configuration ---
+# --- Benchmark Configuration & Dynamic Vendor Discovery ---
 DEPTH ?= 15
 BENCH_DIR = bench
-BENCH_SRCS = $(BENCH_DIR)/benchmark.cpp $(BENCH_DIR)/Allocator.cpp $(BENCH_DIR)/StackAllocator.cpp
-BENCH_BIN = $(BENCH_DIR)/benchmark_$(DEPTH)
+BENCH_VENDOR_DIR = $(BENCH_DIR)/vendor
+
+BENCH_VENDOR_INCLUDES :=
+BENCH_VENDOR_SRCS     :=
+
+ifneq ($(wildcard $(BENCH_VENDOR_DIR)/wb_alloc),)
+    BENCH_VENDOR_INCLUDES += -I$(BENCH_VENDOR_DIR)/wb_alloc
+endif
+
+ifneq ($(wildcard $(BENCH_VENDOR_DIR)/memory-allocators),)
+    BENCH_VENDOR_INCLUDES += -I$(BENCH_VENDOR_DIR)/memory-allocators/includes \
+                             -I$(BENCH_VENDOR_DIR)/memory-allocators/src
+    BENCH_VENDOR_SRCS     += $(BENCH_VENDOR_DIR)/memory-allocators/src/Allocator.cpp \
+                             $(BENCH_VENDOR_DIR)/memory-allocators/src/StackAllocator.cpp
+endif
+
+ifneq ($(wildcard $(BENCH_VENDOR_DIR)/foonathan_memory),)
+    BENCH_VENDOR_INCLUDES += -I$(BENCH_VENDOR_DIR)/foonathan_memory/include \
+                             -I$(BENCH_VENDOR_DIR)/foonathan_memory/include/foonathan/memory \
+                             -I$(BENCH_VENDOR_DIR)/foonathan_memory/build/src \
+                             -I$(BENCH_VENDOR_DIR)/foonathan_memory/build/src/container_node_sizes \
+                             -I$(BENCH_VENDOR_DIR)/foonathan_memory/src
+    BENCH_VENDOR_SRCS     += $(wildcard $(BENCH_VENDOR_DIR)/foonathan_memory/src/*.cpp) \
+                             $(wildcard $(BENCH_VENDOR_DIR)/foonathan_memory/src/detail/*.cpp)
+endif
+
+BENCH_SRCS = $(BENCH_DIR)/benchmark.cpp $(BENCH_VENDOR_SRCS)
+BENCH_BIN  = $(BENCH_DIR)/benchmark_$(DEPTH)
+
 CXX ?= g++
-CXXFLAGS = -O3 -std=c++17 -flto -DNDEBUG -Wno-stringop-overflow -DBENCH_DEPTH=$(DEPTH) -I. -I$(BENCH_DIR)
+CXXFLAGS = -O3 -std=c++17 -flto -DNDEBUG -Wno-stringop-overflow -DBENCH_DEPTH=$(DEPTH) -I. -I$(BENCH_DIR) $(BENCH_VENDOR_INCLUDES)
 
 # Define the primary source file to check coverage for.
 COVERAGE_SRC = easy_stack.h
 
-.PHONY: all clean run tests tests_full list coverage build_coverage bench
+.PHONY: all clean run tests tests_full list coverage build_coverage bench bench_deps clean_vendor
 
 # Default goal: show available commands
 .DEFAULT_GOAL := list
@@ -280,12 +307,34 @@ clean_matrix:
 	rm -rf $(MATRIX_DIR)
 
 
-# --- Benchmark Target ---
+# --- Benchmark Dependencies & Target ---
+.PHONY: bench_deps clean_vendor bench
+
+bench_deps:
+	@mkdir -p $(BENCH_VENDOR_DIR)
+	@if [ ! -d "$(BENCH_VENDOR_DIR)/wb_alloc" ]; then \
+		printf "Fetching wb_alloc...\n"; \
+		git clone --depth 1 https://github.com/WilliamBundy/wb_alloc.git $(BENCH_VENDOR_DIR)/wb_alloc; \
+	fi
+	@if [ ! -d "$(BENCH_VENDOR_DIR)/memory-allocators" ]; then \
+		printf "Fetching Trebi memory-allocators...\n"; \
+		git clone --depth 1 https://github.com/mtrebi/memory-allocators.git $(BENCH_VENDOR_DIR)/memory-allocators; \
+	fi
+	@if [ ! -d "$(BENCH_VENDOR_DIR)/foonathan_memory" ]; then \
+		printf "Fetching foonathan/memory...\n"; \
+		git clone --depth 1 https://github.com/foonathan/memory.git $(BENCH_VENDOR_DIR)/foonathan_memory; \
+		(cd $(BENCH_VENDOR_DIR)/foonathan_memory && cmake -B build -DCMAKE_BUILD_TYPE=Release -DFOONATHAN_MEMORY_BUILD_TESTS=OFF -DFOONATHAN_MEMORY_BUILD_TOOLS=OFF && cmake --build build); \
+	fi
+
+clean_vendor:
+	rm -rf $(BENCH_VENDOR_DIR)
+
 $(BENCH_BIN): $(BENCH_SRCS) easy_stack.h
 	@printf "Compiling benchmark suite (depth $(DEPTH)): $@\n"
 	@$(CXX) $(CXXFLAGS) $(BENCH_SRCS) -o $@
 
-bench: $(BENCH_BIN)
+bench: bench_deps
+	@$(MAKE) --no-print-directory $(BENCH_BIN)
 	@printf "\n--- Running Stack Allocator Benchmarks (Depth: $(DEPTH)) ---\n"
 	@./$(BENCH_BIN)
 
@@ -361,6 +410,7 @@ list:
 	@printf "  make tests_full               - run all tests with debug output\n"
 	@printf "  make test_matrix -j$(nproc)   - run matrix of tests\n"
 	@printf "  make bench [DEPTH=15|30|100]  - compile and run benchmarks with customizable stack depth (default: 15)\n"
+	@printf "  make clean_vendor             - remove downloaded benchmark vendor libraries\n"
 	@printf "  make coverage                 - build & run tests to generate coverage data for CodeCov\n"
 	@printf "  make fuzz_[name]              - run the 'core' fuzzer for 5 minutes (auto-detects fuzz_*.c)\n"
 	@printf "  make replay_[name] CRASH=...  - replay a specific crash file with ASCII visualization\n"

.github/assets/throughput_small_payloads.png

@@ -143,10 +143,10 @@ To evaluate execution speed, cache resilience, and scalability under different w
 ### Tested Allocators:
 1. **EasyStack (Contract)**: Trusted mode with validations delegated to assertions (compiled out in release).
 2. **EasyStack (Defensive)**: Default safety mode with full runtime bounds and API sanitization active.
-3. **Trebi LIFO**: A highly-optimized C++ template-based LIFO stack allocator.
-4. **GNU Obstack**: The glibc standard stack allocator (highly optimized C system baseline).
-5. **wb_alloc (Bundy)**: A popular fixed-size C arena/stack allocator.
-6. **std::stack + malloc**: The default standard library heap-allocated baseline.
+3. **GNU Obstack**: The glibc standard stack allocator (highly optimized C system baseline).
+4. **foonathan::memory**: A popular, highly-optimized C++ memory stack allocator (`foonathan::memory::memory_stack`).
+5. **Trebi LIFO**: A lightweight C++ template-based LIFO stack allocator.
+6. **wb_alloc (Bundy)**: A popular fixed-size C arena/stack allocator.
 
 ---
 
@@ -170,22 +170,22 @@ To prevent compile-time folding, dead-code elimination (DCE), or loop hoisting b
 #### RAW Results (Best of 25 runs, 2,000,000 iterations/run)
 | Allocator | Depth 15 (M ops/s) | Depth 30 (M ops/s) | Depth 100 (M ops/s) |
 | :--- | :---: | :---: | :---: |
-| **EasyStack (Contract)** | **576.40** | **516.74** | **493.63** |
-| **EasyStack (Defensive)** | **415.25** | **385.75** | **402.64** |
-| GNU Obstack | 396.85 | 379.33 | 311.31 |
-| Trebi LIFO (C++) | 365.55 | 358.51 | 360.20 |
-| std::stack + malloc | 209.89 | 214.63 | 188.13 |
-| wb_alloc (Bundy) | 208.18 | 204.88 | 229.38 |
+| **EasyStack (Contract)** | **553.95** | **520.37** | **497.31** |
+| **EasyStack (Defensive)** | 438.24 | 425.04 | 393.81 |
+| GNU Obstack | 492.32 | 472.35 | 354.83 |
+| foonathan::memory | 418.05 | 385.99 | 406.24 |
+| Trebi LIFO (C++) | 402.27 | 399.90 | 397.59 |
+| wb_alloc (Bundy) | 225.39 | 228.38 | 250.47 |
 
 #### PURE Algorithmic Results (Harness Overhead Subtracted)
 | Allocator | Depth 15 (M ops/s) | Depth 30 (M ops/s) | Depth 100 (M ops/s) |
 | :--- | :---: | :---: | :---: |
-| **EasyStack (Contract)** | **2747.82** | **2408.14** | **4972.83** |
-| **EasyStack (Defensive)** | **1076.10** | **941.91** | **1566.77** |
-| GNU Obstack | 870.41 | 895.82 | 720.72 |
-| Trebi LIFO (C++) | 732.81 | 787.78 | 1050.94 |
-| std::stack + malloc | 294.69 | 318.55 | 286.47 |
-| wb_alloc (Bundy) | 291.33 | 297.53 | 394.49 |
+| **EasyStack (Contract)** | **3733.89** | **2159.87** | **4987.23** |
+| **EasyStack (Defensive)** | 1157.74 | 1231.18 | 1354.20 |
+| GNU Obstack | 1631.08 | 1734.35 | 982.89 |
+| foonathan::memory | 1026.76 | 952.16 | 1513.53 |
+| Trebi LIFO (C++) | 936.54 | 1041.50 | 1400.02 |
+| wb_alloc (Bundy) | 331.27 | 352.33 | 456.30 |
 
 ---
 
@@ -199,22 +199,22 @@ To prevent compile-time folding, dead-code elimination (DCE), or loop hoisting b
 #### RAW Results (Best of 25 runs, 2,000,000 iterations/run)
 | Allocator | Depth 15 (M ops/s) | Depth 30 (M ops/s) | Depth 100 (M ops/s) |
 | :--- | :---: | :---: | :---: |
-| **EasyStack (Contract)** | **589.30** | **506.21** | **494.47** |
-| **EasyStack (Defensive)** | **431.45** | **393.71** | **369.90** |
-| Trebi LIFO (C++) | 364.19 | 360.50 | 354.11 |
-| wb_alloc (Bundy) | 70.66 | 69.06 | 67.70 |
-| GNU Obstack | 57.07 | 58.45 | 56.06 |
-| std::stack + malloc | 43.13 | 45.57 | 42.78 |
+| **EasyStack (Contract)** | **586.84** | **509.05** | **498.43** |
+| **EasyStack (Defensive)** | 441.73 | 395.46 | 427.61 |
+| foonathan::memory | 428.22 | 380.73 | 402.30 |
+| Trebi LIFO (C++) | 403.17 | 402.90 | 397.68 |
+| wb_alloc (Bundy) | 73.77 | 72.36 | 72.36 |
+| GNU Obstack | 61.38 | 58.90 | 58.93 |
 
 #### PURE Algorithmic Results (Harness Overhead Subtracted)
 | Allocator | Depth 15 (M ops/s) | Depth 30 (M ops/s) | Depth 100 (M ops/s) |
 | :--- | :---: | :---: | :---: |
-| **EasyStack (Contract)** | **3834.49** | **2164.57** | **4460.48** |
-| **EasyStack (Defensive)** | **1215.93** | **1014.13** | **1141.30** |
-| Trebi LIFO (C++) | 763.55 | 793.38 | 974.88 |
-| wb_alloc (Bundy) | 78.64 | 77.12 | 77.09 |
-| GNU Obstack | 62.17 | 64.12 | 62.35 |
-| std::stack + malloc | 45.97 | 48.94 | 46.34 |
+| **EasyStack (Contract)** | **4679.83** | **2600.74** | **8062.39** |
+| **EasyStack (Defensive)** | 1354.20 | 1072.00 | 1872.09 |
+| foonathan::memory | 1183.62 | 1073.10 | 1467.77 |
+| Trebi LIFO (C++) | 1010.15 | 1128.54 | 1408.14 |
+| wb_alloc (Bundy) | 82.88 | 81.81 | 83.23 |
+| GNU Obstack | 67.56 | 65.01 | 65.95 |
 
 ---