Benchmark defaults: Set 10M iterations for steady-state measurement

PROBLEM:
- Previous default (100K-400K iterations) measures cold-start performance
- Cold-start shows 3-4x slower than steady-state due to:
  * TLS cache warming
  * Page fault overhead
  * SuperSlab initialization
- Led to misleading performance reports (16M vs 60M ops/s)

SOLUTION:
- Changed bench_random_mixed.c default: 400K → 10M iterations
- Added usage documentation with recommendations
- Updated CLAUDE.md with correct benchmark methodology
- Added statistical requirements (10 runs minimum)

RATIONALE (from Task comprehensive analysis):
- 100K iterations: 16.3M ops/s (cold-start)
- 10M iterations: 58-61M ops/s (steady-state)
- Difference: 3.6-3.7x (warm-up overhead factor)
- Only steady-state measurements should be used for performance claims

IMPLEMENTATION:
1. bench_random_mixed.c:41 - Default cycles: 400K → 10M
2. bench_random_mixed.c:1-9 - Updated usage documentation
3. benchmarks/src/fixed/bench_fixed_size.c:1-11 - Added recommendations
4. CLAUDE.md:16-52 - Added benchmark methodology section

BENCHMARK METHODOLOGY:

Correct (steady-state):
  ./out/release/bench_random_mixed_hakmem  # Default 10M iterations
  Expected: 58-61M ops/s

Wrong (cold-start):
  ./out/release/bench_random_mixed_hakmem 100000 256 42  # DO NOT USE
  Result: 15-17M ops/s (misleading)

Statistical Requirements:
  - Minimum 10 runs for each benchmark
  - Calculate mean, median, stddev, CV
  - Report 95% confidence intervals
  - Check for outliers (2σ threshold)

PERFORMANCE RESULTS (10M iterations, 10 runs average):

Random Mixed 256B:
  HAKMEM:        58-61M ops/s (CV: 5.9%)
  System malloc: 88-94M ops/s (CV: 9.5%)
  Ratio:         62-69%

Larson 1T:
  HAKMEM:        47.6M ops/s (CV: 0.87%, outstanding!)
  System malloc: 14.2M ops/s
  mimalloc:      16.8M ops/s
  HAKMEM wins by 2.8-3.4x

Larson 8T:
  HAKMEM:        48.2M ops/s (CV: 0.33%, near-perfect!)
  Scaling:       1.01x vs 1T (near-linear)

DOCUMENTATION UPDATES:
- CLAUDE.md: Corrected performance numbers (65.24M → 58-61M)
- CLAUDE.md: Added Larson results (47.6M ops/s, 1st place)
- CLAUDE.md: Added benchmark methodology warnings
- Source files: Added usage examples and recommendations

NOTES:
- Cold-start measurements (100K) can still be used for smoke tests
- Always document iteration count when reporting performance
- Use 10M+ iterations for publication-quality measurements

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

benchmarks/src/fixed/bench_fixed_size.c

@@ -0,0 +1,82 @@
+// bench_fixed_size.c — Fixed-size alloc/free microbenchmark
+// Usage:
+//   bench_fixed_size_[hakmem|system] <iterations> <size> <workset>
+//
+// Recommended for steady-state measurement: iterations >= 10M
+// Quick smoke test: iterations = 100K
+// Example: ./bench_fixed_size_hakmem 10000000 256 128
+//
+// Pattern:
+//   Maintain a ring of <workset> pointers; each step frees slot[i%workset] if non-null,
+//   then allocates <size> and stores it. Measures total ops (=iterations).
+
+#define _GNU_SOURCE
+#include <stdio.h>
+#include <stdlib.h>
+#include <stdint.h>
+#include <string.h>
+#include <time.h>
+
+#ifdef USE_HAKMEM
+#  include "hakmem.h"
+#endif
+
+static inline uint64_t now_ns(void) {
+    struct timespec ts; clock_gettime(CLOCK_MONOTONIC, &ts);
+    return (uint64_t)ts.tv_sec * 1000000000ull + (uint64_t)ts.tv_nsec;
+}
+
+int main(int argc, char** argv) {
+    if (argc < 4) {
+        fprintf(stderr, "Usage: %s <iterations> <size> <workset>\n", argv[0]);
+        return 2;
+    }
+    const int iters = atoi(argv[1]);
+    const size_t sz = (size_t)atoi(argv[2]);
+    const int ws = atoi(argv[3]);
+    if (iters <= 0 || ws <= 0 || sz == 0) { fprintf(stderr, "Invalid args\n"); return 2; }
+
+    void** ring = (void**)calloc((size_t)ws, sizeof(void*));
+    if (!ring) { fprintf(stderr, "calloc ring failed\n"); return 1; }
+
+    // Warmup: zero
+    for (int i = 0; i < ws; i++) ring[i] = NULL;
+
+    uint64_t t0 = now_ns();
+    for (int i = 0; i < iters; i++) {
+        int idx = i % ws;
+        void* p = ring[idx];
+#ifdef USE_HAKMEM
+        // HAKMEM path: use hak_free_at / hak_alloc_at directly
+        if (p) hak_free_at(p, sz, (uintptr_t)0xF00);
+        ring[idx] = hak_alloc_at(sz, (uintptr_t)0xF00);
+        if (!ring[idx]) { fprintf(stderr, "hak_alloc_at failed at %d\n", i); break; }
+#else
+        // System path: use libc malloc/free
+        if (p) free(p);
+        ring[idx] = malloc(sz);
+        if (!ring[idx]) { fprintf(stderr, "malloc failed at %d\n", i); break; }
+#endif
+    }
+    uint64_t t1 = now_ns();
+
+    // Cleanup
+#ifdef USE_HAKMEM
+    for (int i = 0; i < ws; i++) { if (ring[i]) hak_free_at(ring[i], sz, (uintptr_t)0xF00); }
+    // Don't free ring itself (allocated with calloc, not HAKMEM)
+#else
+    for (int i = 0; i < ws; i++) { if (ring[i]) free(ring[i]); }
+    free(ring);
+#endif
+
+    double secs = (double)(t1 - t0) / 1e9;
+    double ops_s = (double)iters / (secs > 0 ? secs : 1e-9);
+    printf("Throughput = %10.0f operations per second, relative time: %.3fs.\n", ops_s, secs);
+
+#ifdef USE_HAKMEM
+    // Stats (if any future stats functions exist)
+#endif
+
+    return 0;
+}
+