hakmem/LEARNING_SYSTEM_BUGS_P0.md

# P0: Learning System Critical Bugs

**発見日**: 2025-11-26
**発見者**: Benchmark validation task (LEARNING_BENCHMARK_TASK.md 実行中)
**重要度**: **P0 - CRITICAL** (本番環境使用不可)

---

## 📋 バグサマリー

学習機能を有効化すると即座にクラッシュします。PROFILES.md で推奨していた Balanced/Adaptive/Tight プロファイルは **全て使用不可能** です。

---

## 🐛 Bug #1: HAKMEM_ALLOC_LEARN=1 で即座に SEGFAULT

### 再現手順

```bash
export HAKMEM_ALLOC_LEARN=1
export HAKMEM_ALLOC_LEARN_WINDOW=10000
export HAKMEM_ALLOC_LEARN_RATE=0.08
export HAKMEM_MEM_LEARN=0
export HAKMEM_SUPERSLAB_REUSE=1
export HAKMEM_SUPERSLAB_PREWARM=0

./out/release/bench_random_mixed_hakmem 10000000 256 42
```

### 期待される動作

ベンチマークが正常に実行され、学習機能が TLS キャッシュ容量を動的に調整する。

### 実際の動作

```
Segmentation fault (exit code 139)
```

即座にクラッシュ。ベンチマークは 1 iteration も実行されない。

### 影響範囲

- ❌ Balanced Profile (HAKMEM_ALLOC_LEARN=1 使用) → 使用不可能
- ❌ Adaptive Profile (HAKMEM_ALLOC_LEARN=1 使用) → 使用不可能
- ❌ Tight Profile (HAKMEM_ALLOC_LEARN=1 使用) → 使用不可能

### 関連ファイル

- `core/hakmem_alloc_learner.c` - Allocation learning 実装
- `core/hakmem_learner.c` - Learning system 基盤
- `core/tiny_adaptive_sizing.c` - Adaptive sizing (学習駆動)

### デバッグ情報

**初期調査推奨コマンド**:
```bash
# AddressSanitizer で実行
./build.sh debug bench_random_mixed_hakmem
export HAKMEM_ALLOC_LEARN=1
export HAKMEM_ALLOC_LEARN_WINDOW=10000
export HAKMEM_ALLOC_LEARN_RATE=0.08
./out/debug/bench_random_mixed_hakmem 1000 256 42  # 短い実行で確認
```

**予想される原因**:
- 未初期化ポインタ / null pointer dereference
- Learning system constructor の初期化順序問題
- TLS storage との競合

---

## 🐛 Bug #2: HAKMEM_MEM_LEARN=1 で即座に SEGFAULT

### 再現手順

```bash
export HAKMEM_ALLOC_LEARN=0
export HAKMEM_MEM_LEARN=1
export HAKMEM_MEM_LEARN_WINDOW=20000
export HAKMEM_MEM_LEARN_THRESHOLD=0.7
export HAKMEM_SUPERSLAB_REUSE=1
export HAKMEM_SUPERSLAB_PREWARM=0

./out/release/bench_random_mixed_hakmem 10000000 256 42
```

### 期待される動作

ベンチマークが正常に実行され、Memory Learning が THP/WMAX 閾値を動的に調整する。

### 実際の動作

```
Segmentation fault (exit code 139)
```

即座にクラッシュ。

### 影響範囲

- ❌ Adaptive Profile (HAKMEM_MEM_LEARN=1 使用) → 使用不可能
- ❌ Tight Profile (HAKMEM_MEM_LEARN=1 使用) → 使用不可能

### 関連ファイル

- `core/hakmem_mem_learner.c` - Memory learning 実装
- `core/hakmem_learner.c` - Learning system 基盤

### デバッグ情報

**初期調査推奨コマンド**:
```bash
./build.sh debug bench_random_mixed_hakmem
export HAKMEM_MEM_LEARN=1
export HAKMEM_MEM_LEARN_WINDOW=20000
./out/debug/bench_random_mixed_hakmem 1000 256 42
```

**予想される原因**:
- Bug #1 と同様の初期化問題
- Memory statistics 収集インフラとの連携不備

---

## 🐛 Bug #3: Larson ベンチマークで TLS SLL corruption

### 再現手順

```bash
# 学習機能は OFF（デフォルト）
unset HAKMEM_ALLOC_LEARN
unset HAKMEM_MEM_LEARN

./out/release/larson_hakmem 1 10 1 1000 100 10000 42
```

### 期待される動作

Larson ベンチマークが正常に実行され、alloc/free の混合ワークロードを 10 秒間実行する。

### 実際の動作

```
TLS_SLL_NORMALIZE_USERPTR error
Segmentation fault (exit code 139)
```

学習機能OFFでもクラッシュ。

### マルチスレッド版（8T）

```bash
./out/release/larson_hakmem 8 10 1 1000 100 10000 42
```

**結果**:
```
TLS_SLL_PUSH_META_MISMATCH: cls=0 meta_cls=1
Segmentation fault (exit code 139)
```

### 影響範囲

- ❌ Larson 1T: 使用不可能（全プロファイル）
- ❌ Larson 8T: 使用不可能（全プロファイル）
- ❌ PROFILES.md の Larson 性能値: 全て検証不可能

### 関連ファイル

- `benchmarks/larson.c` - Larson ベンチマーク実装
- `core/box/tls_sll_box.h` - TLS SLL (Single Linked List) 実装
- `core/hakmem_tiny.c` - TINY allocator core

### デバッグ情報

**エラーメッセージの意味**:
- `TLS_SLL_NORMALIZE_USERPTR error`: User pointer から base pointer への変換失敗
- `TLS_SLL_PUSH_META_MISMATCH`: Metadata の class index 不一致

**予想される原因**:
- マルチスレッド環境での TLS state corruption
- Class index の誤判定（cls=0 vs meta_cls=1）
- Race condition in freelist management

**初期調査推奨コマンド**:
```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
```

---

## 📊 動作確認済みの設定

### ✅ Baseline (学習OFF, Random Mixed のみ)

```bash
unset HAKMEM_ALLOC_LEARN
unset HAKMEM_MEM_LEARN
export HAKMEM_SUPERSLAB_REUSE=1
export HAKMEM_SUPERSLAB_PREWARM=0

./out/release/bench_random_mixed_hakmem 10000000 256 42
```

**結果**: **83.19 M ops/s** ✅

これは **唯一動作確認できた設定** です。

---

## 🔧 修正優先順位

### P0 (即座に修正が必要)

1. **Bug #1: HAKMEM_ALLOC_LEARN=1 crash**
   - 影響: Balanced/Adaptive/Tight プロファイル全滅
   - 修正なしでは学習機能が一切使えない

2. **Bug #2: HAKMEM_MEM_LEARN=1 crash**
   - 影響: Adaptive/Tight プロファイル
   - Bug #1 と同時修正推奨（共通の初期化問題の可能性）

3. **Bug #3: Larson benchmark crash**
   - 影響: 全プロファイルで Larson が使えない
   - TLS corruption は他のワークロードにも影響の可能性

---

## 📝 次のステップ

### 1. デバッグビルドで原因特定

```bash
# ASan + TSan ビルド
./build.sh debug bench_random_mixed_hakmem
./build.sh debug larson_hakmem

# Bug #1 調査
export HAKMEM_ALLOC_LEARN=1
./out/debug/bench_random_mixed_hakmem 1000 256 42

# Bug #3 調査
./out/debug/larson_hakmem 1 10 1 1000 100 10000 42
```

### 2. Learning system の無効化パッチ（暫定対応）

学習機能を完全に無効化するコンパイル時フラグを追加:

```c
// core/hakmem_learner.c
#ifndef HAKMEM_DISABLE_LEARNING
    // learning code here
#else
    // no-op stubs
#endif
```

これにより、修正完了まで学習機能を安全に無効化できる。

### 3. ドキュメント更新（完了）

- ✅ PROFILES.md: 警告追加、学習関連数値を「未検証」に変更
- ✅ LEARNING_BENCHMARK_TASK.md: 実測結果を反映
- ✅ このバグレポート作成

---

## 📚 関連ドキュメント

- `PROFILES.md` - 設定プロファイル（学習機能が壊れていることを記載済み）
- `LEARNING_BENCHMARK_TASK.md` - ベンチマーク計測タスク（実測結果を記載済み）
- `DEPRECATED.md` - 学習関連の環境変数マッピング
- `CLAUDE.md` - 開発ログ（学習機能の期待値が記載されている）

---

**作成日**: 2025-11-26
**ステータス**: 🔴 OPEN - 修正待ち
**担当者**: TBD