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

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

@@ -0,0 +1,34 @@
+## Plan — Phase 20.18（Null/Void 固定＋Result ケース別＋糖衣）
+
+0) Null/Void の固定（P0）
+- 言語: 予約語 `null`/`void` をリテラルとして受理
+- MIR JSON v0: ConstValue に `Null`/`Void` を追加
+- VM: `VMValue::Null` を追加（boolean/equality/stringify 対応）
+- Singletons: `NullBox`/`VoidBox` を Lazy static に（to_nyash_box() で変換）
+
+1) API 最小追加（Core/Gate‑C 実装→Hakorune VM 委譲）
+- Array.try_get/1, Array.try_pop/0, Map.try_get/1
+- String.to_i64/0, String.to_f64/0
+
+2) 糖衣の受理と Lowering（ゼロアロケーション）
+- Parser: `let a?=/a!=` と `if let ok(..)` を受理
+- Builder: `?`→`select(ok,value,Void)`, `!`→`br ok/ trap`, if-let→`br ok/else`
+
+3) 例外タグの安定化
+- E_OOB / E_EMPTY / E_NOT_FOUND / E_PARSE を固定
+
+4) スモーク（opt‑in, quick）
+- try_get/try_pop（ok/err）+ `?`/`!`/if-let ok
+- to_i64/to_f64（ok/err）
+
+5) Gate & Docs
+- Gate: `HAKO_TRY_API=1`（既定OFF）
+- Docs: result-semantics（case-by-case）/ optional-semantics（link更新）/ testing-guide 補足
+- Docs: vm-core に Null/Void/rc 規則を追記、phase-20.18 README/TASKS を同期
+
+6) Plugins（互換-段階更新）
+- Map/Array の意味論を SSOT に揃える（get/pop 欠落→Null、push/set/clear→Void、delete→値 or Null、set の不正→Fail）
+- HostHandleRouter/内蔵ルーターで未更新プラグインを回避できる経路を優先（Core先行）
+
+7) 後段（20.19+ 任意）
+- Result を“値版”へ（{i1 ok, payload}）。最適化の効果測定とゼロコストの検証。

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

@@ -0,0 +1,79 @@
+# Phase 20.18 — Result（ケースバイケース）+ 軽量糖衣 + Null/Void 固定
+
+目的（要約）
+- 「全部 Result は重い」を回避しつつ、一貫した失敗取り扱いを提供する。
+- Null/Void の言語レベル固定（予約語）と VM 値表現（Null タグ）を導入し、欠落/手続きの意味を明確化。
+- ケース別の最小主義：検索=sentinel、境界=Fail‑Fast＋try_系、変換/I/O=Result 既定。
+- 糖衣は左辺だけ（`let a?=/a!=`）に限定し、ゼロアロケーションで Lowering。
+
+適用範囲（MVP）
+- Null/Void の固定（言語+VM）
+  - 言語: `null`, `void` を予約語にする（リテラル）。
+  - MIR JSON v0: `Const` に `{"type":"Null"|"Void"}` を追加。
+  - VM/Interpreter: `VMValue::Null` を追加（0 アロケーション、比較高速）。
+- 既定挙動（SSOT）
+  - `String.indexOf/1` → not found は `-1`（sentinelのまま）。
+  - `Array.get/1` → 範囲外は `null`（Fail しない）。
+  - `Array.pop/0` → 空配列は `null`（Fail しない）。
+  - `Array.set/2` → i<0 または i>len は `E_OOB`、i==len は append、0<=i<len は置換。戻りは `void`。
+  - `Map.get/1` → 欠落は `null`（Fail しない）。
+  - `Map.set/2` → 不正キー= `E_INVALID_KEY`、不正値= `E_INVALID_VALUE`、戻りは `void`。
+  - `Map.delete/1` → 削除値 or `null`。`Map.clear/0` → `void`。
+- 追加API（5つ）
+  - `Array.try_get/1`, `Array.try_pop/0`
+  - `Map.try_get/1`
+  - `String.to_i64/0`, `String.to_f64/0`
+
+糖衣（任意・軽実装）
+- `let r  = arr.try_get(0)`  … Resultのまま
+- `let x? = arr.try_get(0)`  … `ok→値 / err→VoidBox`
+- `let x! = arr.try_get(0)`  … `ok→値 / err→即Fail`
+- `if let ok(v) = arr.try_get(0) { … } else { … }`
+
+実装方針（段階導入）
+- Phase A（本フェーズ）
+  - Null/Void: 予約語・MIR・VM の三層で固定（VMValue::Null、singleton 変換）。
+  - Core/Gate‑C: Array/Map の SSOT へ挙動を収束（上記 既定挙動）。
+  - Parser: 左辺の `?`/`!` と `if let ok(..)` を受理。
+  - Lowering: `?`/`!`/if-let を branch/select に展開（ゼロアロケーション）。
+  - Verifier: 例外タグ `E_OOB/E_EMPTY/E_NOT_FOUND/E_PARSE` を安定化。
+  - Gate: `HAKO_TRY_API=1`（既定OFF）でスモーク有効化。
+- Phase B（20.19+ 任意）
+  - MIR/LLVM を“値版Result” `{i1 ok, T payload}` に寄せる（SROA/mem2reg 合流）
+  - Box化は保存/境界（FFI/ABI）のみで行いゼロコスト化を徹底
+
+受入れ基準（MVP）
+- quick（opt‑in）で try_* + 糖衣（`?`/`!`/if-let ok）スモークが緑。
+- Fail‑Fastタグが安定（E_OOB/E_EMPTY/E_NOT_FOUND/E_PARSE）。
+- Array/Map の SSOT（Null/void 既定）が Gate‑C/Core/VM で一致。
+
+---
+
+完了サマリ（2025‑10‑29 現在）
+- Bridge‑B（Ny/Core直行）: include ベースで安定。Gate‑C(Core) の file/pipe は緑。
+- Core canary（直行）: array_get/push/set_get は緑。string indexOf bang は TTL 互換で緑（タグ優先、未到達時は -1/rc=0 を暫定許容）。
+- Runner: Core ラッパー出力はタグ行を優先採用。Gate‑C(Core) はタグ→stderr+rc=1、数値→rc=(num&0xFF)。
+- Docs: VM README/Smokes README/CURRENT_TASK を更新（Bridge‑B方針、カナリア導線、TTL注記）。
+
+残タスク（短期）
+- Core からの Fail‑Fast を state 経由の戻り値へ統一して、タグを必ず last line にする（print 依存解消）。
+- 上記完了後、string indexOf bang の TTL 互換（-1容認）を撤去し、タグ必須に戻す。
+
+ノート
+- 20.17 は self‑hosting 完了を優先。実装は本フェーズでまとめて入れる。
+- 糖衣は左辺のみ（公開名の二重化を避ける）。Result は段階で“値版”へ移行予定。
+
+---
+
+## Plugins への影響（互換ポリシー）
+
+ABI 変更は不要（Box 戻りのまま）。ただし意味論は SSOT に合わせる：
+
+- ArrayBox（プラグイン実装がある場合）
+  - get: 範囲外→NullBox、pop: 空→NullBox、push/set/clear: 戻りは VoidBox。
+  - set: i<0 or i>len は `E_OOB`。i==len は append、0<=i<len は置換。
+- MapBox（プラグイン実装がある場合）
+  - get: 欠落→NullBox、delete: 削除値 or NullBox、clear: VoidBox、set: VoidBox。
+  - set: Null key/不正型→ `E_INVALID_KEY`、不正値→ `E_INVALID_VALUE`。暗黙変換は禁止。
+
+Core/Gate‑C が先行で SSOT を満たすため、プラグインが未更新でも Gate‑C(Core) 直行経路は安定。VM 経路でプラグイン実装が呼ばれる場合は、上記の意味論に合わせて段階更新する。

docs/private/roadmap/phases/phase-20.18/TASKS.md

@@ -0,0 +1,42 @@
+## Phase 20.18 — Tasks & Checklist
+
+P0 — Null/Void 固定（言語+VM+Core+Docs）
+- [ ] Parser: `null`/`void` を予約語として受理（AST: NullLiteral/VoidLiteral）
+- [ ] MIR: ConstValue に Null/Void を追加（emit/reader/verifier/print）
+- [ ] VM: VMValue::Null 追加、`to_bool_vm/eq_vm/to_string_vm` に Null を追加
+- [ ] Singleton: NullBox/VoidBox の Lazy static 化（to_nyash_box で変換）
+- [ ] Core: Array/Map の SSOT へ収束（get/pop→Null、set/clear/push→Void、delete→値 or Null、set 不正→Fail）
+- [ ] Smokes: null/void identity/boolean、array/map（get/pop/delete/invalid set）
+- [ ] Docs: vm-core / gate-c-core-routing / INDEX / phase-20.18 README を更新
+
+Core/API
+- [ ] Array.try_get/1（ok=value, err=E_OOB）
+- [ ] Array.try_pop/0（ok=value, err=E_EMPTY）
+- [ ] Map.try_get/1（ok=value, err=E_NOT_FOUND）
+- [ ] String.to_i64/0（ok=i64, err=E_PARSE）
+- [ ] String.to_f64/0（ok=f64, err=E_PARSE）
+
+Parser/Lowering
+- [ ] `let a?=/a!=` の受理
+- [ ] `if let ok(v) = …` の受理
+- [ ] Lowering: `?` → select, `!` → branch+trap, if‑let → branch（allocなし）
+
+Verifier/Diagnostics
+- [ ] 例外タグ（E_OOB/E_EMPTY/E_NOT_FOUND/E_PARSE）の固定
+- [ ] `HAKO_TRY_API=1` gate での動作保証
+
+Plugins（段階更新）
+- [ ] MapBox: get 欠落→Null、delete→値 or Null、clear→Void、set→Void／不正→E_INVALID_*
+- [ ] ArrayBox: get/pop 欠落→Null、push/set/clear→Void、set OOB→E_OOB
+- [ ] HostHandleRouter: Core 先行経路の優先（未更新プラグインの影響を遮断）
+
+Smokes（quick, opt‑in）
+- [ ] try_get: ok/err + `a?`/`a!`/if-let ok
+- [ ] try_pop: ok/err + `a?`/`a!`
+- [ ] map.try_get: ok/err + 糖衣
+- [ ] string.to_i64/to_f64: ok/err（stdout/rc/タグ）
+
+Docs
+- [ ] result-semantics.md（case-by-case）
+- [ ] optional-semantics.md に 20.18 方針リンク追記
+- [ ] guides/testing-guide.md に観測方法（stdout/rc/タグ）補足