hakmem/docs/analysis/PHASE4_E3_ENV_CONSTRUCTOR_INIT_DESIGN.md

# Phase 4 E3-4: ENV Constructor Init 設計メモ

## 目的

E1 で統合した ENV snapshot の lazy init check（3.22% self%）を排除。

**期待**: **+0.5-1.5%** 改善

---

## 結果（A/B テスト）

### 初回観測（参考）

初回は **+4.75%** を観測したが、再現しなかった（環境/ノイズの可能性が高い）。

### 再検証（決定）

**判定**: ❌ **NO-GO / FROZEN**

| Metric | Baseline (CTOR=0) | Optimized (CTOR=1) | Delta |
|--------|-------------------|-------------------|-------|
| Mean | 47.55M ops/s | 46.86M ops/s | **-1.44%** |
| Median | 47.46M ops/s | 46.97M ops/s | **-1.03%** |

**結論**:
- constructor init は “安全” だが、性能面では **現状の hot path では得にならない**
- 研究箱として保持するが **default OFF のまま freeze**

---

## 現状分析

### E1 完了後の状態

- `hakmem_env_snapshot_enabled()`: 3.22% self%（perf profile）
- 原因: 毎回の lazy init check（`static int g = -1` + `getenv()`）

```c
// 現在の実装（core/box/hakmem_env_snapshot_box.h:51-62）
static inline bool hakmem_env_snapshot_enabled(void) {
    static int g = -1;
    if (__builtin_expect(g == -1, 0)) {  // ← この分岐が 3.22%
        const char* e = getenv("HAKMEM_ENV_SNAPSHOT");
        if (e && *e) {
            g = (*e == '1') ? 1 : 0;
        } else {
            g = 0;
        }
    }
    return g != 0;
}
```

### 問題

1. **分岐コスト**: `if (g == -1)` が hot path で毎回評価
2. **予測ミス**: first call で branch misprediction
3. **関数呼び出しオーバーヘッド**: inline でも分岐は残る

---

## 設計

### アプローチ: Constructor Init + Direct Read

```c
// 新しい実装
static int g_hakmem_env_snapshot_gate = -1;

__attribute__((constructor(101)))  // priority 101: after libc init
static void hakmem_env_snapshot_gate_init(void) {
    const char* e = getenv("HAKMEM_ENV_SNAPSHOT");
    g_hakmem_env_snapshot_gate = (e && *e == '1') ? 1 : 0;
}

static inline bool hakmem_env_snapshot_enabled(void) {
    return g_hakmem_env_snapshot_gate != 0;  // No branch (just load + compare)
}
```

### 利点

1. **分岐削減**: `if (g == -1)` 完全排除
2. **一度だけ**: `getenv()` は main() 前に 1 回のみ
3. **キャッシュ効率**: global read は TLS より高速（L1 hit 率高い）

### リスク

| リスク | 対策 |
|--------|------|
| putenv() 後の変更が反映されない | bench_profile の `hakmem_env_snapshot_refresh_from_env()` で gate/snapshot を同期 |
| constructor order | priority 101 で libc init 後を保証 |
| fork() 安全性 | hakmem は fork-safe 設計済み |

---

## Box Theory（実装計画）

### L0: Env（戻せる）

```
HAKMEM_ENV_SNAPSHOT_CTOR=0/1  # default: 0（OFF）
```

- **ON (=1)**: Constructor init を使用（lazy check なし）
- **OFF (=0)**: 従来の lazy init を使用（rollback 可能）

### L1: ENV Constructor Box（境界: 1 箇所）

#### 変更対象

- `core/box/hakmem_env_snapshot_box.h` (変更)
  - `hakmem_env_snapshot_enabled()` を 2 つのモードで実装
- `core/box/hakmem_env_snapshot_box.c` (変更)
  - Constructor 関数を追加

---

## 実装指示

### Patch 1: Constructor Init Gate

**ファイル**: `core/box/hakmem_env_snapshot_box.c`

```c
// Global gate (not static local - avoids lazy init)
int g_hakmem_env_snapshot_gate = -1;
int g_hakmem_env_snapshot_ctor_mode = -1;

// Constructor: run before main()
__attribute__((constructor(101)))
static void hakmem_env_snapshot_gate_ctor(void) {
    // Read HAKMEM_ENV_SNAPSHOT_CTOR (default OFF)
    const char* ctor_env = getenv("HAKMEM_ENV_SNAPSHOT_CTOR");
    g_hakmem_env_snapshot_ctor_mode = (ctor_env && *ctor_env == '1') ? 1 : 0;

    if (g_hakmem_env_snapshot_ctor_mode) {
        // Constructor mode: init gate now
        const char* e = getenv("HAKMEM_ENV_SNAPSHOT");
        g_hakmem_env_snapshot_gate = (e && *e == '1') ? 1 : 0;
    }
}
```

### Patch 2: Dual-Mode Enabled Check

**ファイル**: `core/box/hakmem_env_snapshot_box.h`

```c
// Global gate state (defined in .c)
extern int g_hakmem_env_snapshot_gate;
extern int g_hakmem_env_snapshot_ctor_mode;

static inline bool hakmem_env_snapshot_enabled(void) {
    // Fast path: constructor mode (no lazy check, just global read).
    // Note: do not attach a fixed branch hint here; it will be wrong for one mode.
    if (g_hakmem_env_snapshot_ctor_mode == 1) {
        return g_hakmem_env_snapshot_gate != 0;
    }

    // Slow path: legacy lazy init (fallback)
    if (__builtin_expect(g_hakmem_env_snapshot_gate == -1, 0)) {
        const char* e = getenv("HAKMEM_ENV_SNAPSHOT");
        g_hakmem_env_snapshot_gate = (e && *e == '1') ? 1 : 0;
    }
    return g_hakmem_env_snapshot_gate != 0;
}
```

---

## A/B テスト計画

### Test Matrix

| Profile | Iterations | Runs | Command |
|---------|-----------|------|---------|
| Mixed | 20M | 10 | `./bench_random_mixed_hakmem 20000000 400 1` |

### Baseline

```bash
HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE HAKMEM_ENV_SNAPSHOT=1 HAKMEM_ENV_SNAPSHOT_CTOR=0 \
  ./bench_random_mixed_hakmem 20000000 400 1
```

### Optimized

```bash
HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE HAKMEM_ENV_SNAPSHOT=1 HAKMEM_ENV_SNAPSHOT_CTOR=1 \
  ./bench_random_mixed_hakmem 20000000 400 1
```

### 判定基準

- **GO**: +0.5% 以上
- **NEUTRAL**: ±0.5%（研究箱維持）
- **NO-GO**: -0.5% 以下

---

## 期待値の根拠

**なぜ +0.5-1.5% か？**

1. **現在のオーバーヘッド**: 3.22% self%
2. **削減分**: lazy init check の分岐コスト（~10-15 cycles per call）
3. **削減率**: ~15-30% of 3.22% → 0.5-1.0%
4. **追加効果**: better branch prediction（warm path に分岐なし）

---

## 非目標

- snapshot refresh API の変更（putenv sync は既存 API で対応）
- E1 の構造変更（consolidation は維持）
- 他の ENV gate の constructor 化（E3-4 は hakmem_env_snapshot_enabled のみ）