# Phase 13: Header Write Elimination v1 — 次の指示書（C7 preserve header）

## 0. Status

- Phase 12 で system malloc が hakmem より +63.7% 速いことが判明 → Phase 13 開始
- 方針（v1）: **ヘッダは維持**しつつ、**C7 の freelist がヘッダを壊さない**ようにして “alloc 時のヘッダ再書き込み” を削る
- 結果: ⚪ **NEUTRAL (+0.78%) → freeze (default OFF)**（副産物: E5-2 が +1.13%）

設計: `docs/analysis/PHASE13_HEADER_WRITE_ELIMINATION_1_DESIGN.md`
結果: `docs/analysis/PHASE13_HEADER_WRITE_ELIMINATION_1_AB_TEST_RESULTS.md`

---

## 1. 目的（GO 条件）

Mixed 10-run（clean env）で:
- **GO**: mean +1.0% 以上
- **NO-GO**: mean -1.0% 以下（即 rollback / freeze）
- **NEUTRAL**: ±1.0%（research box freeze）

---

## 2. 実装パッチ順（小さく積む）

### Patch 1: L0 ENV Box（戻せる）

新規:
- `core/box/tiny_c7_preserve_header_env_box.h`
- `core/box/tiny_c7_preserve_header_env_box.c`（refresh）

仕様:
- ENV: `HAKMEM_TINY_C7_PRESERVE_HEADER=0/1`（default: 0）
- API:
  - `tiny_c7_preserve_header_enabled() -> int`
  - `tiny_c7_preserve_header_env_refresh_from_env()`

要件:
- hot path では **getenv 禁止**（lazy init + cached read のみ）

### Patch 2: L1 Layout SSOT 変更（境界1箇所）

修正:
- `core/box/tiny_layout_box.h`

変更:
- `tiny_nextptr_offset(class_idx)` の C7 分だけを L0 gate で切替
  - OFF: 既存（C7 off=0）
  - ON:  C7 off=1（header-preserving）

### Patch 3: L2 NextPtr のコメント/前提を SSOT 準拠に

修正（コードの挙動変更はしない）:
- `core/tiny_nextptr.h`
- `core/box/tiny_header_box.h`（コメントの “C7=offset0 固定” 等があれば撤去）

狙い:
- C7 の offset 固定前提を残さない（設計事故の芽を摘む）

### Patch 4: Bench profile の refresh 同期（ENV 事故防止）

修正:
- `core/bench_profile.h`

追加:
- `bench_setenv_default(...)` の後に `tiny_c7_preserve_header_env_refresh_from_env()` を呼ぶ

（Phase 8 と同じパターン）

---

## 3. A/B テスト（4点マトリクス必須）

`scripts/run_mixed_10_cleanenv.sh` を使用（ENV リークを防ぐ）。

### Case A（baseline）

```sh
HAKMEM_TINY_C7_PRESERVE_HEADER=0 \
HAKMEM_TINY_HEADER_WRITE_ONCE=0 \
scripts/run_mixed_10_cleanenv.sh
```

### Case B（E5-2 only）

```sh
HAKMEM_TINY_C7_PRESERVE_HEADER=0 \
HAKMEM_TINY_HEADER_WRITE_ONCE=1 \
scripts/run_mixed_10_cleanenv.sh
```

### Case C（C7 preserve only）

```sh
HAKMEM_TINY_C7_PRESERVE_HEADER=1 \
HAKMEM_TINY_HEADER_WRITE_ONCE=0 \
scripts/run_mixed_10_cleanenv.sh
```

### Case D（Phase 13 v1 本命）

```sh
HAKMEM_TINY_C7_PRESERVE_HEADER=1 \
HAKMEM_TINY_HEADER_WRITE_ONCE=1 \
scripts/run_mixed_10_cleanenv.sh
```

追加（任意）:
- `HAKMEM_PROFILE=C6_HEAVY_LEGACY_POOLV1` でも 5-run を取る（回帰が無いこと）

---

## 4. 可視化（最小）

既存:
- `HAKMEM_TINY_HEADER_WRITE_ONCE_STATS=1` を使い、
  - `alloc_skip_count / alloc_write_count` の比率が増えることを確認する

新規を足す場合（必要最小）:
- “C7 で skip が増えている” が見えない場合のみ、C7 だけのカウンタを追加（常時 atomic は避ける）

---

## 5. 昇格（GO の場合のみ）

GO のとき:
1. `core/bench_profile.h` に default を追加
   - `bench_setenv_default("HAKMEM_TINY_C7_PRESERVE_HEADER", "1");`
   - （必要なら）`HAKMEM_TINY_HEADER_WRITE_ONCE=1` も昇格
2. `CURRENT_TASK.md` に Phase 13 v1 の結果（A/B 表）を追記
3. rollback 手順を明記
   - `export HAKMEM_TINY_C7_PRESERVE_HEADER=0`

NO-GO のとき:
- research box freeze（default OFF のまま）、設計メモに原因を記録