hakorune/docs/private/roadmap/phases/phase-20.21/PLAN.md

Plan — Phase 20.21（Manual Memory Management / C‑ABI）

マイルストーン

• M1: libc ベースの hako_alloc/free（realloc は任意）
• M2: Opaque Handle（HakoHandle）retain/release（atomic）
• M3: SSOT ドキュメント（所有権/並行性/失敗時挙動）
• M4: スモーク（alloc/free, retain/release, 二重解放Fail, NULL 安全）
• M5: hakmem 差し替え導線（ENV ガードのみ、実装は次フェーズ可）

タスク詳細

1. API スケルトン（ヘッダ & 実装・最小）

• include/hako_mem.h（生成 or 手書き）
  • void* hako_alloc(size_t);
  • void hako_free(void*);
  • typedef uint64_t HakoHandle; HakoHandle hako_retain(HakoHandle); void hako_release(HakoHandle);
• src/abi/c/mem_libc.c（libc 実装）
• ENV: HAKO_C_ABI_ALLOC={libc|hakmem}（既定 libc, 未対応値は Fail）

2. retain/release（atomic）

• 参照カウントテーブル（ハンドル→rc）を内部に保持（最小実装）
• 0 → free で解放（ハンドルの登録解除）
• 再入/並行性はatomic＋スピンロックで最小実装（将来改善）

3. SSOT ドキュ

• docs/development/abi/README.md に Memory Ownership Rules を追記
• Fail‑Fast 文言（double free／unknown handle／allocator mismatch）を固定

4. スモーク

• alloc/write/free 正常ケース
• double free → 失敗タグ（rc!=0）
• retain/release の基本（rc 増減、0到達で解放）
• （任意）ASan/Valgrind 実行のガイド

5. hakmem 導線

• ENV のみ（実装は次）。切替点・責務・将来の整合を README に明記

リスクと対策

• 二重解放／unknown handle → Fail‑Fast（安定タグ）
• 競合 → atomic＋最小ロック、将来は hazard pointers 等で最適化
• ABI 変更 → _copy と _borrow を命名で分離（本フェーズは _copy のみ）