# Phase 20.21 — Manual Memory Management（C‑ABI／MVP）

目的
- C‑ABI におけるメモリ管理の単一規約（SSOT）を定義し、安全な最小APIを提供する。
- 将来の hakmem（独自アロケータ）統合を見据えつつ、既定は libc（malloc/free）で運用する。

設計原則
- 既定OFF・Fail‑Fast・SSOT（ドキュと実装を一致）。
- Box‑First（Opaque Handle で境界を切る）: C から内部表現（Box/GC）に触れさせない。
- 段階導入: MVP はコピー／解放の最小規約に限定（ビュー／借用は次フェーズ）。

API（MVP）
- 低レベル（libc 既定）
  - `void* hako_alloc(size_t size);`
  - `void  hako_free(void* ptr);`
  - `// optional: void* hako_realloc(void* ptr, size_t new_size);`（後回し推奨）
- Opaque Handle（将来の Box/GC を見据える）
  - `typedef uint64_t HakoHandle;`
  - `HakoHandle hako_retain(HakoHandle h);`（ref++／atomic）
  - `void       hako_release(HakoHandle h);`（ref--→0で解放）

所有権ルール（SSOT）
- 返却された C バッファ（`void*`／文字列／配列）は呼び出し側の所有。呼び出し側が `hako_free` で解放。
- 入力ポインタの所有権は関数が奪取しない（unless 明示）。
- Handle は「所有＝参照カウント保有」と定義。`retain/release` でカウント管理。

実装方針
- 既定: libc（malloc/free）。
- 切替: `HAKO_C_ABI_ALLOC={libc|hakmem}`（既定 libc、hakmem は将来の差し替え点）。
- 並行性: retain/release は atomic。競合時は Fail‑Fast で診断。

受入れ基準
- スモーク: alloc→write→free の基本、二重解放の Fail、NULL 安全。
- （任意）ASan/Valgrind オプトインでリーク／double‑free を検出。
- ドキュ: ルール・API・ENV・エラーポリシーを SSOT に記載。

範囲外（本フェーズ）
- 借用ビュー（ptr+len）の提供。
- from_c（C 文字列から Nyash 文字列へ）の所有権問題。
- OS／プラットフォームごとの可視性（次以降）。

タイムライン（2–3週間）
- Week1: API スケルトン＋libc 実装＋最小スモーク。
- Week2: ドキュ仕上げ＋ASan/Valgrind スモーク（任意）＋hakmem 差し替え導線（ENV）。