From ee722b2131eef5a3e7fdec017c1fd6f6cb59305a Mon Sep 17 00:00:00 2001
From: "Moe Charm (CI)" <moecharm@example.com>
Date: Wed, 26 Nov 2025 12:34:27 +0900
Subject: [PATCH] Update Larson bug analysis: root cause identified, larson-fix
 branch created

(cherry-picked from 328a6b722)
---
 LEARNING_SYSTEM_BUGS_P0.md | 83 ++++++++++++++++++++++++--------------
 1 file changed, 53 insertions(+), 30 deletions(-)

diff --git a/LEARNING_SYSTEM_BUGS_P0.md b/LEARNING_SYSTEM_BUGS_P0.md
index 09079f56..48487037 100644
--- a/LEARNING_SYSTEM_BUGS_P0.md
+++ b/LEARNING_SYSTEM_BUGS_P0.md
@@ -125,13 +125,25 @@ export HAKMEM_MEM_LEARN_WINDOW=20000
 
 ## 🐛 Bug #3: Larson ベンチマークで TLS SLL corruption
 
+### ⚠️ 根本原因特定済み（2025-11-26）
+
+**First Bad Commit**: `19c1abfe7` "Fix Unified Cache TLS SLL bypass"
+**Last Working Commit**: `5c8567562` "Add callsite tracking for tls_sll_push/pop"
+
+### 🔧 回避策（即座に利用可能）
+
+```bash
+# larson-fix ブランチに切り替え（動作確認済み: 51.54 M ops/s）
+git checkout larson-fix
+./build.sh larson_hakmem
+./out/release/larson_hakmem 1 5 1 1000 100 10000 42
+```
+
 ### 再現手順
 
 ```bash
-# 学習機能は OFF（デフォルト）
-unset HAKMEM_ALLOC_LEARN
-unset HAKMEM_MEM_LEARN
-
+# master ブランチ（クラッシュする）
+git checkout master
 ./out/release/larson_hakmem 1 10 1 1000 100 10000 42
 ```
 
@@ -148,48 +160,49 @@ Segmentation fault (exit code 139)
 
 学習機能OFFでもクラッシュ。
 
-### マルチスレッド版（8T）
+### 技術的分析
 
-```bash
-./out/release/larson_hakmem 8 10 1 1000 100 10000 42
-```
+**問題のコミット**: `19c1abfe7` が導入した Step 2.5 in `unified_cache_refill()`:
+- TLS SLL から pop して Unified Cache に入れる処理を追加
+- Cross-thread free されたブロックが TLS SLL に混入
+- Header restoration だけでは解決しない深い設計問題
 
-**結果**:
-```
-TLS_SLL_PUSH_META_MISMATCH: cls=0 meta_cls=1
-Segmentation fault (exit code 139)
-```
+**35+ コミットで「修正」を試みたが全て失敗**:
+- `1a301c1a2` Add header restoration for TLS SLL pop
+- `78df6756e` Fix header restoration in 4 TLS SLL pop paths
+- `a941043f2` Box Theory: Encapsulate header restoration in tls_sll_pop
+- `165c33bc2` Fix Larson regression: Add SuperSlab fallback
+- ... 全て Larson は依然クラッシュ
 
 ### 影響範囲
 
-- ❌ Larson 1T: 使用不可能（全プロファイル）
-- ❌ Larson 8T: 使用不可能（全プロファイル）
-- ❌ PROFILES.md の Larson 性能値: 全て検証不可能
+- ❌ Larson 1T: 使用不可能（master ブランチ）
+- ❌ Larson 8T: 使用不可能（master ブランチ）
+- ✅ Larson 1T: **51.54 M ops/s** (`larson-fix` ブランチ)
+- ❌ PROFILES.md の Larson 性能値: 全て検証不可能（master）
 
 ### 関連ファイル
 
-- `benchmarks/larson.c` - Larson ベンチマーク実装
+- `core/front/tiny_unified_cache.c:434-463` - Step 2.5 (問題のコード)
 - `core/box/tls_sll_box.h` - TLS SLL (Single Linked List) 実装
-- `core/hakmem_tiny.c` - TINY allocator core
+- `core/tiny_free_fast_v2.inc.h` - Fast free with cross-thread detection
 
 ### デバッグ情報
 
 **エラーメッセージの意味**:
 - `TLS_SLL_NORMALIZE_USERPTR error`: User pointer から base pointer への変換失敗
 - `TLS_SLL_PUSH_META_MISMATCH`: Metadata の class index 不一致
+- `FREE_FAST_HDR_META_MISMATCH`: Header と Meta の class 不一致（hdr_cls=-1 = 無効なヘッダー）
 
-**予想される原因**:
-- マルチスレッド環境での TLS state corruption
-- Class index の誤判定（cls=0 vs meta_cls=1）
-- Race condition in freelist management
+**根本原因**:
+- Step 2.5 が cross-thread free されたブロックを TLS SLL から pop
+- これらのブロックは他スレッドの SuperSlab に所属
+- Header restoration だけでは所有権問題を解決できない
+- `HAKMEM_TINY_LARSON_FIX=1` (cross-thread detection) を有効化しても解決しない
 
-**初期調査推奨コマンド**:
-```bash
-# ThreadSanitizer で実行
-./build.sh debug larson_hakmem
-export TSAN_OPTIONS="halt_on_error=1"
-./out/debug/larson_hakmem 1 10 1 1000 100 10000 42
-```
+**正しい修正方法**:
+1. Step 2.5 を完全に削除（`larson-fix` ブランチの状態に戻す）
+2. または、TLS SLL に cross-thread isolation を実装
 
 ---
 
@@ -208,7 +221,17 @@ export HAKMEM_SUPERSLAB_PREWARM=0
 
 **結果**: **83.19 M ops/s** ✅
 
-これは **唯一動作確認できた設定** です。
+### ✅ Larson (`larson-fix` ブランチ使用)
+
+```bash
+git checkout larson-fix
+./build.sh larson_hakmem
+./out/release/larson_hakmem 1 5 1 1000 100 10000 42
+```
+
+**結果**: **51.54 M ops/s** ✅
+
+**注意**: `master` ブランチでは Larson はクラッシュします。
 
 ---