WIP: Add TLS SLL validation and SuperSlab registry fallback

ChatGPT's diagnostic changes to address TLS_SLL_HDR_RESET issue.
Current status: Partial mitigation, but root cause remains.

Changes Applied:
1. SuperSlab Registry Fallback (hakmem_super_registry.h)
   - Added legacy table probe when hash map lookup misses
   - Prevents NULL returns for valid SuperSlabs during initialization
   - Status: ✅ Works but may hide underlying registration issues

2. TLS SLL Push Validation (tls_sll_box.h)
   - Reject push if SuperSlab lookup returns NULL
   - Reject push if class_idx mismatch detected
   - Added [TLS_SLL_PUSH_NO_SS] diagnostic message
   - Status: ✅ Prevents list corruption (defensive)

3. SuperSlab Allocation Class Fix (superslab_allocate.c)
   - Pass actual class_idx to sp_internal_allocate_superslab
   - Prevents dummy class=8 causing OOB access
   - Status: ✅ Root cause fix for allocation path

4. Debug Output Additions
   - First 256 push/pop operations traced
   - First 4 mismatches logged with details
   - SuperSlab registration state logged
   - Status: ✅ Diagnostic tool (not a fix)

5. TLS Hint Box Removed
   - Deleted ss_tls_hint_box.{c,h} (Phase 1 optimization)
   - Simplified to focus on stability first
   - Status: ⏳ Can be re-added after root cause fixed

Current Problem (REMAINS UNSOLVED):
- [TLS_SLL_HDR_RESET] still occurs after ~60 seconds of sh8bench
- Pointer is 16 bytes offset from expected (class 1 → class 2 boundary)
- hak_super_lookup returns NULL for that pointer
- Suggests: Use-After-Free, Double-Free, or pointer arithmetic error

Root Cause Analysis:
- Pattern: Pointer offset by +16 (one class 1 stride)
- Timing: Cumulative problem (appears after 60s, not immediately)
- Location: Header corruption detected during TLS SLL pop

Remaining Issues:
⚠️ Registry fallback is defensive (may hide registration bugs)
⚠️ Push validation prevents symptoms but not root cause
⚠️ 16-byte pointer offset source unidentified

Next Steps for Investigation:
1. Full pointer arithmetic audit (Magazine ⇔ TLS SLL paths)
2. Enhanced logging at HDR_RESET point:
   - Expected vs actual pointer value
   - Pointer provenance (where it came from)
   - Allocation trace for that block
3. Verify Headerless flag is OFF throughout build
4. Check for double-offset application in conversions

Technical Assessment:
- 60% root cause fixes (allocation class, validation)
- 40% defensive mitigation (registry fallback, push rejection)

Performance Impact:
- Registry fallback: +10-30 cycles on cold path (negligible)
- Push validation: +5-10 cycles per push (acceptable)
- Overall: < 2% performance impact estimated

Related Issues:
- Phase 1 TLS Hint Box removed temporarily
- Phase 2 Headerless blocked until stability achieved

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

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

docs/specs/DOCS_INDEX.md

@@ -102,6 +102,8 @@ ACE Learning Layer (Adaptive Control Engine)
   - User guide: `docs/ACE_LEARNING_LAYER.md` ✅
   - Technical plan: `docs/ACE_LEARNING_LAYER_PLAN.md` ✅
   - Progress report: `ACE_PHASE1_PROGRESS.md` ✅
+  - Learning layer overview: `docs/analysis/LEARNING_LAYER_OVERVIEW.md` ✅
+  - Learning A/B results: `docs/benchmarks/LEARNING_AB_RESULTS.md` (growing log)
 - **Phase 1 Deliverables** (COMPLETE ✅):
   - ✅ Metrics collection (`hakmem_ace_metrics.{c,h}`)
   - ✅ UCB1 learning algorithm (`hakmem_ace_ucb1.{c,h}`)

docs/specs/ENV_VARS.md

@@ -1,12 +1,67 @@
 HAKMEM Environment Variables (Tiny focus)
 
-Core toggles
+このファイルは HAKMEM の Tiny 系機能（Tiny allocator / TLS SLL / SuperSlab）に関わる環境変数をまとめたものです。
+数が多いため、まず「よく使うもの」だけをざっと把握できるようにし、その後に詳細なカテゴリ別リストを載せています。
+
+### このファイルと他ドキュメントの関係（現状整理）
+- リポジトリ全体の `getenv()` 呼び出しを集計した結果は `ENV_VARIABLE_SURVEY.md` にまとまっています（変数 228 個）。
+- `ENV_VARIABLE_SURVEY.md` では各変数に対して **KEEP / CONSOLIDATE / DEPRECATE** のステータスを付けています。
+  - KEEP: 本番運用・安全性・主要なチューニングで今後も使う前提の変数
+  - CONSOLIDATE: 将来的に `HAKMEM_DEBUG` / `HAKMEM_TRACE` / `HAKMEM_STATS` 等のマスター系に統合する予定の変数
+  - DEPRECATE: 段階的に削除予定の変数（新規利用は非推奨）
+- この `ENV_VARS.md` はその中から、**Tiny / SuperSlab / TLS SLL 周りで日常的に触るべきものを中心に抜き出した実用リファレンス** です。
+- Tiny 以外を含む網羅的な説明や、個々の変数のステータス詳細が必要な場合は:
+  - `ENV_VARIABLE_SURVEY.md`（最新のサーベイとステータス）
+  - `docs/specs/ENV_VARS_COMPLETE.md`（より古いが網羅的なリファレンス）
+  をあわせて参照してください。
+
+## Quick cheat sheet（よく使うENV）
+
+### コア動作トグル（常用）
+- `HAKMEM_WRAP_TINY`  
+  Tiny allocator を有効化（直リンクまたは LD_PRELOAD 時の主経路にする）。
+- `HAKMEM_TINY_USE_SUPERSLAB`  
+  Tiny が SuperSlab バックエンドを使うかどうか（既定 ON）。
+- `HAKMEM_TINY_TLS_SLL`  
+  Tiny TLS SLL を有効化（Headerless/Phase2 でもコア機能）。
+- `HAKMEM_SAFE_FREE` / `HAKMEM_INVALID_FREE` / `HAKMEM_INVALID_FREE_LOG`  
+  free() 経路の安全性・invalid free 検出モード。
+- `HAKMEM_LD_SAFE` / `HAKMEM_LD_BLOCK_JEMALLOC` / `HAKMEM_FORCE_LIBC_ALLOC(_INIT)`  
+  LD_PRELOAD 時の安全モードと jemalloc との共存制御。
+
+### Tiny/SuperSlab/TLS の主要チューニング
+- `HAKMEM_TINY_REFILL_MAX` / `HAKMEM_TINY_REFILL_MAX_HOT` / `HAKMEM_TINY_REFILL_MAX_C{0..7}`  
+  Tiny TLS キャッシュのリフィル上限（全体／ホットクラス／クラス別）。
+- `HAKMEM_TINY_SS_ADOPT*` / `HAKMEM_TINY_SS_REQTRACE`  
+  SuperSlab publish/adopt 経路と採用ゲートの挙動。
+- `HAKMEM_TINY_SLL_DRAIN_ENABLE` / `HAKMEM_TINY_SLL_DRAIN_INTERVAL`  
+  TLS SLL → freelist drain の頻度・有効/無効。
+
+### ベンチ/実験用（通常運用では OFF 推奨）
+- `HAKMEM_BENCH_FAST_FRONT` / `HAKMEM_BENCH_WARMUP` / `HAKMEM_TINY_BENCH_*`  
+  ベンチマーク専用の fast front / warmup / refill 設定。
+- `HAKMEM_TINY_ULTRA*` / `HAKMEM_TINY_BENCH_SLL_ONLY`  
+  Ultra Tiny / SLL‑only などの実験経路。
+
+### デバッグ/トレース/統計（マスター系）
+- `HAKMEM_DEBUG_ALL` / `HAKMEM_DEBUG_LEVEL` / `HAKMEM_QUIET`  
+  全体デバッグの一括 ON/OFF と冗長度。
+- `HAKMEM_TRACE` / `HAKMEM_TRACE_LEVEL`  
+  トレース対象（ptr/refill/free/mailbox/...）と冗長度。
+- `HAKMEM_STATS` / `HAKMEM_STATS_DUMP`  
+  統計モジュールの有効化と終了時ダンプ。
+
+以降のセクションでは、これらを含むすべての ENV をカテゴリ別に詳しく説明します。
+
+---
+
+## Core toggles
 - HAKMEM_WRAP_TINY=1
   - Tiny allocatorを有効化（直リンク）
 - HAKMEM_TINY_USE_SUPERSLAB=0/1
   - SuperSlab経路のON/OFF（既定ON）
 
-SFC (Super Front Cache) stats / A/B
+## SFC (Super Front Cache) stats / A/B
 - HAKMEM_SFC_ENABLE=0/1
   - Box 5‑NEW: Super Front Cache を有効化（既定OFF; A/B用）。
 - HAKMEM_SFC_CAPACITY=16..256 / HAKMEM_SFC_REFILL_COUNT=8..256
@@ -15,7 +70,7 @@ SFC (Super Front Cache) stats / A/B
   - プロセス終了時に SFC 統計をstderrへダンプ（alloc_hits/misses, refill_calls など）。
   - 使い方: make CFLAGS+=" -DHAKMEM_DEBUG_COUNTERS=1" larson_hakmem; HAKMEM_SFC_ENABLE=1 HAKMEM_SFC_STATS_DUMP=1 ./larson_hakmem …
 
-Larson defaults (publish→mail→adopt)
+## Larson defaults (publish→mail→adopt)
 - 忘れがちな必須変数をスクリプトで一括設定するため、`scripts/run_larson_defaults.sh` を用意しています。
 - 既定で以下を export します（A/B は環境変数で上書き可能）:
   - `HAKMEM_TINY_USE_SUPERSLAB=1` / `HAKMEM_TINY_MUST_ADOPT=1` / `HAKMEM_TINY_SS_ADOPT=1`
@@ -24,7 +79,7 @@ Larson defaults (publish→mail→adopt)
 - `HAKMEM_TINY_MAILBOX_SLOWDISC=1`
 - `HAKMEM_TINY_MAILBOX_SLOWDISC_PERIOD=256`
 
-Front Gate (A/B for boxified fast path)
+## Front Gate (A/B for boxified fast path)
 - `HAKMEM_TINY_FRONT_GATE_BOX=1` — Use Front Gate Box implementation (SFC→SLL) for fast-path pop/push/cascade. Default 0. Safe to toggle during builds via `make EXTRA_CFLAGS+=" -DHAKMEM_TINY_FRONT_GATE_BOX=1"`.
   - Debug visibility（任意）: `HAKMEM_TINY_RF_TRACE=1`
   - Force-notify（任意, デバッグ補助）: `HAKMEM_TINY_RF_FORCE_NOTIFY=1`
@@ -32,7 +87,7 @@ Front Gate (A/B for boxified fast path)
   - tput: `HAKMEM_TINY_SS_FORCE_LG=21`, `HAKMEM_TINY_SS_CACHE=0`, `HAKMEM_TINY_SS_PRECHARGE=0`
   - pf:   `HAKMEM_TINY_SS_FORCE_LG=20`, `HAKMEM_TINY_SS_CACHE=4`, `HAKMEM_TINY_SS_PRECHARGE=1`
 
-Ultra Tiny (SLL-only, experimental)
+## Ultra Tiny (SLL-only, experimental)
 - HAKMEM_TINY_ULTRA=0/1
   - Ultra TinyモードのON/OFF（SLL中心の最小ホットパス）
 - HAKMEM_TINY_ULTRA_VALIDATE=0/1
@@ -42,7 +97,7 @@ Ultra Tiny (SLL-only, experimental)
 - HAKMEM_TINY_ULTRA_SLL_CAP_C{0..7}=N
   - クラス別SLL上限上書き
 
-SuperSlab adopt/publish（実験）
+## SuperSlab adopt/publish（実験）
 - HAKMEM_TINY_SS_ADOPT=0/1
   - SuperSlab の publish/adopt + remote drain + owner移譲を有効化（既定OFF）。
   - 4T Larson など cross-thread free が多いワークロードで再利用密度を高めるための実験用スイッチ。
@@ -60,22 +115,22 @@ SuperSlab adopt/publish（実験）
    - remote queue がすでに非空（old!=0）でも、`slab_listed==0` の場合に publish を強制通知。
    - 初回の空→非空通知を見逃した可能性をあぶり出す用途に有効（A/B 推奨）。
 
-Ready List（Refill最適化の箱）
+## Ready List（Refill最適化の箱）
 - 2025-12 cleanup: Ready系ENVは廃止。Ready ringは常時有効、幅/予算は固定（width=TINY_READY_RING, budget=1）。
 
-Background Remote Drain（束ね箱・軽量ステップ）
+## Background Remote Drain（束ね箱・軽量ステップ）
 - 2025-12 cleanup: BG Remote系ENV（HAKMEM_TINY_BG_REMOTE*）は廃止。BGリモート/aggregatorは固定OFF。
 
-Ready Aggregator（BG, 非破壊peek）
+## Ready Aggregator（BG, 非破壊peek）
 - 2025-12 cleanup: Ready Aggregator系ENVも廃止（固定OFF）。
 
-Registry 窓（探索コストのA/B）
+## Registry 窓（探索コストのA/B）
 - HAKMEM_TINY_REG_SCAN_MAX=N
   - Registry の“小窓”で走査する最大エントリ数（既定256）。
   - 値を小さくすると superslab_refill() と mmap直前ゲートでの探索コストが減る一方、adopt 命中率が低下し OOM/新規mmap が増える可能性あり。
   - Tiny‑Hotなど命中率が高い場合は 64/128 などをA/B推奨。
 
-Mid 向け簡素化リフィル（128–1024B向けの分岐削減）
+## Mid 向け簡素化リフィル（128–1024B向けの分岐削減）
 - HAKMEM_TINY_MID_REFILL_SIMPLE=0/1
   - クラス>=4（128B以上）で、sticky/hot/mailbox/registry/adopt の多段探索をスキップし、
     1) 既存TLSのSuperSlabに未使用Slabがあれば直接初期化→bind、
@@ -224,7 +279,7 @@ New (debug isolation)
   - 小クラス用の小型TLSマガジン（128要素, classes 0..3）を有効化。既定0（A/B用）。
   - alloc: HotMag→SLL→Magazine の順でヒットを狙う。free: SLL優先、溢れ時にHotMag→Magazine。
 
-USDT/tracepoints（perfのユーザ空間静的トレース）
+## USDT/tracepoints（perfのユーザ空間静的トレース）
 - ビルド時に `CFLAGS+=-DHAKMEM_USDT=1` を付与すると、主要分岐にUSDT（DTrace互換）プローブが埋め込まれます。
   - 依存: `<sys/sdt.h>`（Debian/Ubuntu: `sudo apt-get install systemtap-sdt-dev`）。
   - プローブ名（provider=hakmem）例:
@@ -242,7 +297,7 @@ USDT/tracepoints（perfのユーザ空間静的トレース）
       - `sudo sysctl kernel.perf_event_paranoid=1`
   - WSLなど一部カーネルでは UPROBE/USDT が無効な場合があります（PMUのみにフォールバック）。
 
-ビルドプリセット（Tiny‑Hot最短フロント）
+## ビルドプリセット（Tiny‑Hot最短フロント）
 - コンパイル時フラグ: `-DHAKMEM_TINY_MINIMAL_FRONT=1`
   - 入口から UltraFront/Quick/Frontend/HotMag/SuperSlab try/BumpShadow を物理的に除去
   - 残る経路: `SLL → TLS Magazine → SuperSlab →（以降のスローパス）`
@@ -253,7 +308,7 @@ USDT/tracepoints（perfのユーザ空間静的トレース）
   - 入口で SuperSlab TLSバンプ→SuperSlab直経路を優先（ビルド除去ではなく分岐）
   - Tiny‑Hotでは概ね不利（命令・分岐増）なため、既定OFF。ベンチA/B用途のみ。
 
-Scripts
+## Scripts
 - scripts/run_tiny_hot_triad.sh <cycles>
 - scripts/run_tiny_benchfast_triad.sh <cycles> — bench-only fast path triad
 - scripts/run_tiny_sllonly_triad.sh <cycles> — SLL-only + warmup + PGO triad
@@ -495,4 +550,3 @@ Update History:
 - 2025-11-29: Added benchmark env vars (BENCH_FAST_FRONT, BENCH_WARMUP, FREE_ROUTE_TRACE)
 - 2025-11-29: Added HAKMEM_TINY_SS_TRUST_MMAP_ZERO build flag
 - 2025-11-29: Marked DISABLE_MINCORE_CHECK as removed
-