docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)

docs/private/roadmap/phases/phase-20.22/CHECKLIST.md

@@ -0,0 +1,23 @@
+# Phase 20.22 — チェックリスト（String/Array C‑ABI / MVP）
+
+開始前（P1: Deferred）
+- [ ] Phase 20.21 が完了（SSOT・alloc/free・handle）
+
+実装
+- [ ] hako_string_to_c_copy(HakoHandle)
+- [ ] HakoArrayI64 / hako_array_i64_to_c_copy(HakoHandle)
+- [ ] c_header_gen.py の拡張（typedef/prototypes）
+
+テスト/スモーク
+- [ ] C リンク実行で戻り値/内容が正しい（opt‑in）
+- [ ] 文字列: 空文字・長文
+- [ ] 配列: len=0／複数要素
+- [ ] 負例: NULL／巨大サイズ→Fail（安定タグ）
+
+ドキュメント
+- [ ] abi/README.md に API 追加（所有権・失敗時挙動）
+- [ ] types.md に HakoArray を追記
+
+受入基準（着手時）
+- [ ] quick（opt‑in）緑、回帰なし
+- [ ] 既定OFFで既存挙動不変

docs/private/roadmap/phases/phase-20.22/PLAN.md

@@ -0,0 +1,31 @@
+# Plan — Phase 20.22（String/Array C‑ABI / MVP）
+
+マイルストーン
+- M1: string → C コピー API（hako_string_to_c_copy）
+- M2: array<i64> → C コピー API（HakoArray / hako_array_to_c_copy）
+- M3: ヘッダー生成拡張（typedef/プロトタイプ）
+- M4: スモーク（C リンク実行・負例）
+
+タスク詳細
+1) String copy‑out
+- 実装: 内部 StringBox から bytes を複製、末尾 NUL を付与
+- 戻り: char*（caller owns; `hako_free` 必須）
+- 失敗: NULL 返し＋安定タグ（stderr）
+
+2) Array<i64> copy‑out
+- 実装: 配列メタ（len）を読み、`HakoArrayI64{data,length}` を複製
+- 戻り: HakoArrayI64*（caller owns; `hako_mem_free(data)` と `hako_mem_free(self)` 必須）
+- 失敗: NULL 返し＋安定タグ
+
+3) ヘッダ生成
+- `typedef struct { int64_t* data; size_t length; } HakoArrayI64;`
+- プロトタイプを c_header_gen.py に追加
+
+4) スモーク
+- C からリンク: 文字列/配列を受け取り、値確認→`hako_free`
+- 負例: 空文字列／len=0／NULL 入力／巨大サイズ（Fail‑Fast）
+
+リスク/対策
+- 二重解放 → `hako_free` の多重呼び出し検知（Fail）
+- 競合 → Phase 20.21 の retain/release ルールに従う
+- ABI 拡張 → _copy と _borrow を命名で分離（本フェーズは _copy のみ）

docs/private/roadmap/phases/phase-20.22/README.md

@@ -0,0 +1,36 @@
+# Phase 20.22 — String/Array C‑ABI（MVP / P1: Deferred unless FFI required）
+
+前提
+- Phase 20.21 完了（C‑ABI メモリ管理の SSOT が確立）。
+
+目的（FFI用途）
+- C 側へ安全にコピーアウトする最小 API を提供（所有権＝呼び出し側）。
+- from_c／ビュー（借用）は扱わず、読み出し専用で進める。
+
+ステータス
+- セルフホスト優先のため P1（後回し）。FFI が必要になった時点で着手する。
+
+API（MVP）
+- 文字列（読み出し専用）
+  - `char* hako_string_to_c_copy(HakoHandle str);`（caller owns; `hako_mem_free` 必須）
+- 配列（i64 限定の最小）
+  - `typedef struct { int64_t* data; size_t length; } HakoArrayI64;`
+  - `HakoArrayI64* hako_array_i64_to_c_copy(HakoHandle arr);`（caller owns; `hako_mem_free(data)`, `hako_mem_free(self)`）
+
+設計原則
+- Box‑First（Opaque Handle 経由のみ）。
+- Fail‑Fast: NULL/長さ不整合/OOB は安定タグで失敗。
+- 既定OFF・CLI優先。ENVは短命（TTL）。
+
+受入れ基準
+- `.o + .h` を C からリンクし、`hako_string_to_c_copy`／`hako_array_to_c_copy` が期待どおり動作すること。
+- quick（opt‑in）にスモーク追加、回帰なし。
+
+範囲外（本フェーズ）
+- from_c（C string→Nyash StringBox）。
+- ビュー（borrow／ptr+len の寿命管理）。
+- 文字コード変換／ロケール依存の扱い。
+
+タイムライン（3–4週間）
+- Week1–2: String（copy‑out）実装＋スモーク＋ヘッダ生成拡張。
+- Week3–4: Array（copy‑out）実装＋スモーク＋負例テスト（NULL/len=0/OOB）。