hakmem/docs/archive/TINY_LEARNING_LAYER.md

# Tiny Learning Layer & Backend Integration (Phase 27 Snapshot)

> **⚠️ ARCHIVE NOTICE (2025-11-26)**
> Several ENV variables and files referenced in this document were removed in commit 6b791b97d:
> - `HAKMEM_TINY_ULTRA_FRONT` (deleted)
> - `HAKMEM_TINY_ULTRA_L0` (deleted)
> - `HAKMEM_TINY_ULTRA_HEAP_DUMP` (deleted)
> - `HAKMEM_TINY_ULTRA_PAGE_DUMP` (deleted)
> - `HAKMEM_TINY_BG_REMOTE` (deleted)
> - `HAKMEM_TINY_BG_REMOTE_BATCH` (deleted)
> - Files deleted: `core/front/tiny_ultrafront.h`, `core/ultra/tiny_ultra_heap.c`, `core/ultra/tiny_ultra_page_arena.c`
>
> This document is kept for historical reference but may contain outdated information.

**Date**: 2025-11-21
**Scope**: Tiny (0–1KB) / Shared Superslab Pool / FrozenPolicy / Ultra* Boxes
**Goal**: 学習層（FrozenPolicy / Learner）を活かして、Tiny の backend を「自動でそれなりに最適」な状態に保つための箱と境界を整理する。

---

## 1. Box Topology（Tiny 向けの学習レイヤ構成）

- **Box SP-SLOT (SharedSuperSlabPool)**  
  - ファイル: `core/hakmem_shared_pool.{h,c}`, `core/superslab/superslab_types.h`  
  - 役割:
    - Tiny クラス 0..7 向けの Superslab を **共有プール**として管理（per-class SuperSlabHead legacy を徐々に退役）。  
    - Slot state: `SLOT_UNUSED / SLOT_ACTIVE / SLOT_EMPTY` を per-slab で追跡。
  - 主要フィールド:
    - `_Atomic uint64_t g_sp_stage1_hits[cls]` … EMPTY 再利用 (Stage1)
    - `_Atomic uint64_t g_sp_stage2_hits[cls]` … UNUSED claim (Stage2)
    - `_Atomic uint64_t g_sp_stage3_hits[cls]` … 新規 SuperSlab (Stage3)
    - `uint32_t class_active_slots[TINY_NUM_CLASSES_SS]` … クラス別 ACTIVE slot 数
  - 主要 API:
    - `shared_pool_acquire_slab(int class_idx, SuperSlab** ss, int* slab_idx)`
    - `shared_pool_release_slab(SuperSlab* ss, int slab_idx)`
  - ENV:
    - `HAKMEM_SHARED_POOL_STAGE_STATS=1`  
      → プロセス終了時に Stage1/2/3 の breakdown を 1 回だけダンプ。

- **Box TinySuperslab Backend Box (`hak_tiny_alloc_superslab_box`)**  
  - ファイル: `core/hakmem_tiny_superslab.{h,c}`  
  - 役割:
    - Tiny front（Unified / UltraHeap / TLS）から Superslab backend への **唯一の出入口**。
    - shared backend / legacy backend / hint Box を 1 箇所で切り替える。
  - Backend 実装:
    - `hak_tiny_alloc_superslab_backend_shared(int class_idx)`  
      → Shared Pool / SP-SLOT 経由。
    - `hak_tiny_alloc_superslab_backend_legacy(int class_idx)`  
      → 旧 `SuperSlabHead` ベース（回帰・fallback 用）。
    - `hak_tiny_alloc_superslab_backend_hint(int class_idx)`  
      → legacy に落ちる前に、直近の (ss, slab_idx) を 1 回だけ再利用する軽量 Box。
  - ENV:
    - `HAKMEM_TINY_SS_SHARED=0`  
      → 強制 legacy backend のみ。
    - `HAKMEM_TINY_SS_LEGACY_FALLBACK=0`  
      → shared 失敗時にも legacy を使わない（完全 Unified モード）。
    - `HAKMEM_TINY_SS_C23_UNIFIED=1`  
      → **C2/C3 だけ legacy fallback を無効化**（他クラスは従来どおり shared+legacy）。
    - `HAKMEM_TINY_SS_LEGACY_HINT=1`  
      → shared 失敗 → legacy の間に hint Box を挟む。

- **Box FrozenPolicy / Learner（学習層）**  
  - ファイル: `core/hakmem_policy.{h,c}`, `core/hakmem_learner.c`  
  - 役割:
    - Mid/Large で実績がある CAP/W_MAX 調整ロジックを Tiny に拡張する足場。
  - Tiny 向けフィールド:
    - `uint16_t tiny_cap[8];  // classes 0..7`  
      → Shared Pool の「クラス別 ACTIVE slot 上限」（soft cap）。
  - Tiny CAP デフォルト（Phase 27 時点）:
    - `{2048, 1024, 96, 96, 256, 256, 128, 64}`  
      → C2/C3 は Shared Pool 実験対象として 96/96 に設定。
  - ENV:
    - `HAKMEM_CAP_TINY=2048,1024,96,96,256,256,128,64`  
      → 先頭から 8 個を `tiny_cap[0..7]` に上書き。

- **Box UltraPageArena（Tiny→Page 層の観察箱）**  
  - ファイル: `core/ultra/tiny_ultra_page_arena.{h,c}`  
  - 役割:
    - `superslab_refill(int class_idx)` をフックし、クラス別の Superslab refill 回数をカウント。
  - API:
    - `tiny_ultra_page_on_refill(int class_idx, SuperSlab* ss)`
    - `tiny_ultra_page_stats_snapshot(uint64_t refills[8], int reset)`
  - ENV:
    - `HAKMEM_TINY_ULTRA_PAGE_DUMP=1`  
      → 終了時に `[ULTRA_PAGE_STATS]` を 1 回だけダンプ。

---

## 2. 学習ループに見せるメトリクス

Tiny 学習層が見るべきメトリクスと取得元:

- **Active Slot / CAP 関連**
  - `g_shared_pool.class_active_slots[class]`  
    → クラス別 ACTIVE slot 数（Shared Pool 管理下）。
  - `FrozenPolicy.tiny_cap[class]`  
    → soft cap。`shared_pool_acquire_slab` Stage3 で `cur >= cap` なら **新規 Superslab 拒否**。

- **Acquire Stage 内訳**
  - `g_sp_stage1_hits[class]` … Stage1 (EMPTY slot 再利用)  
  - `g_sp_stage2_hits[class]` … Stage2 (UNUSED slot claim)  
  - `g_sp_stage3_hits[class]` … Stage3 (新規 SuperSlab / LRU pop)  
  - これらの合算から:
    - Stage3 割合が高い → Superslab churn が多い、CAP/Precharge/LRU を増やす候補。
    - Stage1 が長期間 0% → EMPTY スロットがほぼ生成されていない（free 側のポリシー改善候補）。

- **Page 層イベント**
  - `TinyUltraPageStats.superslab_refills[cls]`  
    → クラス別の refill 回数。Tiny front から見た「page 層イベントの多さ」を測る。

---

## 3. 現状のポリシーと挙動（Phase 27）

### 3.1 Shared Pool backend 選択

`hak_tiny_alloc_superslab_box(int class_idx)` のポリシー:

1. `HAKMEM_TINY_SS_SHARED=0` のとき:
   - 常に legacy backend (`hak_tiny_alloc_superslab_backend_legacy`) のみを使用。

2. shared 有効時:
   - 基本経路:
     - `p = hak_tiny_alloc_superslab_backend_shared(class_idx);`
     - `p != NULL` ならそのまま返す。
   - fallback 判定:
     - `HAKMEM_TINY_SS_LEGACY_FALLBACK=0`  
       → shared 失敗でも legacy へは落とさず、そのまま `NULL` 許容（完全 Unified モード）。
     - `HAKMEM_TINY_SS_C23_UNIFIED=1`  
       → C2/C3 の場合に限り `legacy_fallback=0` に上書き（他クラスは `g_ss_legacy_fallback` に従う）。
   - hint Box:
     - shared 失敗 & fallback 許可時に限り:
       - `hak_tiny_alloc_superslab_backend_hint(class_idx)` を 1 回だけ試す。
       - 直近成功した `(ss, slab_idx)` がまだ `used < capacity` なら、そこから 1 ブロックだけ追加 carve。

### 3.2 FrozenPolicy.tiny_cap と Shared Pool の連携

- `shared_pool_acquire_slab()` Stage3（新規 Superslab 確保）直前に:
  ```c
  uint32_t limit = sp_class_active_limit(class_idx); // = tiny_cap[class]
  uint32_t cur = g_shared_pool.class_active_slots[class_idx];
  if (limit > 0 && cur >= limit) {
      return -1; // Soft cap reached → caller 側で legacy fallback or NULL
  }
  ```
- 意味:
  - `tiny_cap[class]==0` → 制限なし（無限に Superslab を増やせる）。
  - `>0` → ACTIVE slot 数が cap に達したら **新規 SuperSlab を増やさない**（churn 制御）。

現状のデフォルト:

- `{2048,1024,96,96,256,256,128,64}`  
  - C2/C3 を 96 に抑えつつ、C4/C5 は 256 slots まで許容。
  - ENV `HAKMEM_CAP_TINY` で一括上書き可能。

### 3.3 C2/C3 限定「ほぼ完全 Unified」実験

- `HAKMEM_TINY_SS_C23_UNIFIED=1` のとき:
  - C2/C3:
    - shared backend のみで運転（`legacy_fallback=0`）。
    - Shared Pool から Superslab/slab が取れなかった場合は `NULL` を返し、上位が UltraFront/TinyFront 経路にフォールバック。
  - 他クラス:
    - 従来どおり shared+legacy fallback。
- Random Mixed 256B / 200K / ws=256 での挙動:
  - デフォルト設定（C2/C3 cap=96）: ≈16.8M ops/s 前後。
  - `HAKMEM_TINY_SS_C23_UNIFIED=1` の有無で差は ±数% レベル（ランダム揺らぎ内）。
  - OOM / SEGV は観測されず、C2/C3 を Shared Pool 単独で回す足場としては安定。

---

## 4. 「学習層を活かす」ための次ステップ（Tiny 向け）

今ある土台を使って、学習層を Tiny に伸ばすときの具体的なステップと現状:

1. **Learner に Tiny メトリクスを配線（済）**
   - `core/hakmem_learner.c` に Tiny 専用メトリクスを追加済み:
     - `active_slots[class] = g_shared_pool.class_active_slots[class];`
     - `stage3_ratio[class] = ΔStage3 / (ΔStage1+ΔStage2+ΔStage3);`
     - `refills[class] = tiny_ultra_page_global_stats_snapshot()` から取得。

2. **tiny_cap[] のヒルクライム調整（実装済み/チューニング中）**
   - 各 Tiny クラスごとに、ウィンドウ内の Stage3 割合を監視:
     - Stage3 が多すぎ（新規 SuperSlab が頻発） → `tiny_cap[class]` を +Δ。
     - Stage3 が少ない & ACTIVE slot が少ない → `tiny_cap[class]` を -Δ。
   - cap の下限は `max(min_tiny, active_slots[class])` にクリップし、  
     既に確保済みの Superslab を急に「上限超過」にしないようにしている。
   - 調整後は `hkm_policy_publish()` で新しい FrozenPolicy を公開。

3. **PageArena / Precharge / Cache との連携（TinyPageAuto, 実験中）**
   - UltraPageArena / SP-SLOT / PageFaultTelemetry からのメトリクスを使って、Superslab OS キャッシュ＋precharge を軽く制御:
     - `HAKMEM_TINY_PAGE_AUTO=1` のとき、Learner が各ウィンドウで
       - `refills[class]`（UltraPageArena の Superslab refill 数, C2〜C5）と
       - PageFaultTelemetry の `PF_pages(C2..C5)` および `PF_pages(SSM)` を読み取り、
       - `score = refills * PF_pages(Cn) + PF_pages(SSM)/8` を計算。
     - スコアが `HAKMEM_TINY_PAGE_MIN_REFILLS * HAKMEM_TINY_PAGE_PRE_MIN_PAGES` 以上のクラスだけに対して:
       - `tiny_ss_precharge_set_class_target(class, target)`（既定 target=1）で precharge を有効化。
       - `tiny_ss_cache_set_class_cap(class, cap)`（既定 cap=2）で OS Superslab キャッシュ枚数を small cap に設定。
     - スコアがしきい値未満のクラスは `target=0, cap=0` に戻して OFF。
   - これにより、Tiny 側から見て Superslab 層の「refill + PF が重いクラスだけ少数の Superslab を先行 fault-in / 温存」する挙動を学習層から制御できる状態まで到達している（まだパラメータ調整段階）。

4. **Near-Empty しきい値の学習統合（C2/C3）**
   - Box: `TinyNearEmptyAdvisor`（`core/box/tiny_near_empty_box.{h,c}`）
     - free パスで C2/C3 の `TinySlabMeta.used/cap` から「near-empty slab」を検出し、イベント数を集計。
     - ENV:
       - `HAKMEM_TINY_SS_PACK_C23=1` … near-empty 観測 ON。
       - `HAKMEM_TINY_NEAREMPTY_PCT=P` … 初期しきい値 (%), 1〜99, 既定 25。
       - `HAKMEM_TINY_NEAREMPTY_DUMP=1` … 終了時に `[TINY_NEAR_EMPTY_STATS]` を 1 回ダンプ。
   - Learner 側からの自動調整:
     - `HAKMEM_TINY_NEAREMPTY_AUTO=1` のとき、
       - ウィンドウ内で near-empty イベント（C2/C3 合計）が 0 の場合:
         - しきい値 P を `+STEP` だけ緩める（P_MAX まで、STEP 既定 5）。
       - near-empty イベントが多すぎる（例: 128 以上）の場合:
         - P を `-STEP` だけ締める（P_MIN まで）。
       - P_MIN/P_MAX/STEP はそれぞれ
         - `HAKMEM_TINY_NEAREMPTY_PCT_MIN`（既定 5）
         - `HAKMEM_TINY_NEAREMPTY_PCT_MAX`（既定 80）
         - `HAKMEM_TINY_NEAREMPTY_PCT_STEP`（既定 5）
         で上書き可能。
   - Random Mixed / Larson では near-empty イベント自体がほとんど発生しておらず、  
     現状は P がゆるやかに上限側へ寄るだけ（挙動への影響はごく小さい）。

5. **総合スコアでの最適化**
   - 1 ベンチ（例: Random Mixed 256B）ではなく:
     - Fixed-size Tiny
     - Random Mixed 各サイズ
     - Larson / Burst / Apps 系
   をまとめたスコア（平均 ops/s + メモリフットプリント + page fault）に対して、
   - Tiny/Learning 層が CAP/Precharge/Cache を少しずつ動かすイメージ。

---

## 6. 既知の制限と安全策

- 8192B Random Mixed で発生していた TLS SLL head=0x60 問題は:
  - `tls_sll_pop()` 内で head が低アドレスの場合に、そのクラスの SLL をリセットし slow path に逃がす形で **箱の内側で Fail-Fast** させるように修正済み。
  - これにより、長尺ベンチでも SEGV せずに回し続けられる。
- `tiny_nextptr.h` の `tiny_next_store()` には軽いガードを入れ、
  - `next` が 0 以外かつ `<0x1000` / `>0x7fff...` の場合に 1 回だけ `[NEXTPTR_GUARD]` を出すようにしてある（観測専用）。
  - 現時点の観測では C4 で一度だけ `next=0x47` が記録されており、freelist/TLS 経路のどこかに残存バグがあることは認識済み。
  - ただし Fail-Fast により箱の内側でリセットされるため、外側の挙動（ベンチ・アプリ）は安定している。

将来的に「完全退治」まで進める場合は、Tiny 向け debug ビルド構成を整えたうえで  
`NEXTPTR_GUARD` の call site を `addr2line` などで特定し、当該経路をピンポイントに修正する予定。