Mainline Integration Plan (Tiny focus)

> **⚠️ ARCHIVE NOTICE (2025-11-26)**
> Several ENV variables and files referenced in this document were removed in commit 6b791b97d:
> - `HAKMEM_TINY_BG_REMOTE` (deleted)
> - `HAKMEM_TINY_BG_REMOTE_BATCH` (deleted)
>
> This document is kept for historical reference but may contain outdated information.

What we promoted to mainline (safe, general)
- Safer tiny refill into SLL (already integrated)
  - `sll_refill_small_from_ss(class_idx, max_take)` now caps refill by the actual SLL free capacity, avoiding overtake and wasted meta->used increments.
- Entry order consolidation in the small fast path
  - Prefer `SLL → Magazine → SuperSlab` in the normal (non‑bench) path; Quick/FrontCache/Ultra tiers remain opt‑in.
- Targeted remote‑drain queue (compiled in, default OFF)
  - Per‑class Treiber queue for slabs that exceed remote thresholds; disabled by default via env knobs to preserve conservative behavior.
- PGO recipe (opt‑in)
  - Makefile targets for PGO on tiny benches are available, but not required for normal builds.

What remains bench‑only (NOT promoted)
- SLL‑only front (Magazine compiled out) and TLS warmup
  - These are highly benchmark‑specific and are kept in bench‑only builds.
- Free‑side SLL‑first push without owner/stats
  - Mainline preserves learning/stats semantics; bench builds can cut them out.
- Quick/FrontCache / 32/64 specialization hardwiring
  - Retained as A/B options; not enabled by default in mainline.

Recommended “Perf‑Main” preset (opt‑in, no bench macros)
- Environment (Tiny‑Hot biased but general):
  - `HAKMEM_TINY_TLS_SLL=1`
  - `HAKMEM_TINY_REFILL_MAX=96`
  - `HAKMEM_TINY_REFILL_MAX_HOT=192`
  - `HAKMEM_TINY_SPILL_HYST=16`
  - `HAKMEM_TINY_BG_REMOTE=0` (keep targeted remote drain off by default)
  - Keep Quick/FrontCache/Ultra OFF unless explicitly A/B tested

How to try Perf‑Main locally
- Build benches: `make bench_fast`
- Run tiny‑hot triad (no bench macros): `bash scripts/run_tiny_hot_triad.sh 60000`
- Run random‑mixed matrix: `bash scripts/run_random_mixed_matrix.sh 100000`

Notes
- LD_PRELOAD/app mode remains conservative (LD_SAFE staging). Tiny‑only and pass‑through modes are recommended for stability. The bench‑only optimizations are intentionally not applied in LD mode.