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

docs/private/roadmap/selfhosting/front_mvp.md

@@ -0,0 +1,96 @@
+# Self-Hosting Front MVP — Ny → JSON v0
+
+Status: drafting (Phase 15.9 entry)
+
+## Purpose
+- Deliver a Ny-written front-end that lowers Stage-3 Ny source into JSON v0 accepted by the existing MIR/VM/LLVM lines.
+- Keep Core (`src/`) untouched; all implementation resides under `lang/src/compiler/`（旧 `apps/selfhost-compiler/` は互換ライン）。
+- Fail fast: unsupported syntax must abort with a precise diagnostic, never fall back to Rust-side parser.
+
+## Scope (Day 1–2)
+- Expressions: integer literal, boolean literal, null, binary ops (`+ - * / %`, comparisons `== != < <= > >=`), logical `&& ||`, grouped `(...)`.
+- Statements: `return`, `local`, `assignment`, `if/else`, `loop` (while-style), `break`, `continue`.
+- Calls: direct function call (`foo()`), method call sugar (`obj.method()`), builtin boxes (Array/Map/String minimal) deferred to Day 3–4.
+- Metadata: `meta.usings` populated from `ParserBox.extract_usings` (already implemented).
+- JSON normalization: `JsonProgramBox` fixes key orderと既定値を整備（Local/Const/If/Loop/Return/Call、空配列は常に`[]`、null配列は[]に正規化）。
+
+## Interfaces
+| box | responsibility |
+| --- | --- |
+| `ParserBox` | Tokenize/parse Ny source into Stage-1 AST JSON. Already handles Stage-2 constructs; ensure Stage-3 gating by `stage3_enable`. |
+| `EmitterBox` | Convert Stage-1 AST JSON to JSON v0 Program. Delegates normalization/meta injection to `JsonProgramBox`. Must guarantee single-line output when `NYASH_JSON_ONLY=1`. |
+| `MirEmitterBox` | Out of scope for Day 1–2 (stub remains). |
+
+### Contracts
+- `ParserBox.parse_program2(src)` returns a `Program` JSON string with `version/kind/body/meta` keys.
+- `EmitterBox.emit_program(ast_json, usings_json)` injects metadata and *must* avoid altering the AST when `ast_json` already conforms to JSON v0.
+- `Main.main(args)` (`lang/src/compiler/entry/compiler.hako`) orchestrates: read source → parse → emit → print.
+
+## Deliverables
+1. **Documentation**
+   - This file (living roadmap).
+   - Update `CURRENT_TASK_SELFHOST.md` with checklists and timeline (done).
+   - README snippet explaining how to run the front MVP via `hakorune` flags.
+2. **Code**
+   - Extend `ParserBox` where gaps exist (Stage-3 gating, diagnostics).
+   - Add `lang/src/compiler/stage1/json_program_box.hako` — normalization box for Program/Stmt/Expr + `meta.usings` injection.
+   - Keep `EmitterBox` thin by delegating to `JsonProgramBox`.
+3. **Tests**
+   - Quick smokes: `tools/smokes/v2/profiles/quick/selfhost/selfhost_min_const_ret_vm.sh` など。
+  - Normalization shape: `tools/smokes/v2/profiles/quick/selfhost/selfhost_json_normalize_shapes.sh`（If/Loop/Call/Return, meta.usings 確認）。
+  - Edge normalization: `tools/smokes/v2/profiles/quick/selfhost/selfhost_json_normalize_edges.sh`（Loop body null→[]、Call args null→[]、Null ノード維持）。
+   - Harness comparator: `tools/smokes/v2/run.sh --profile quick` の `selfhost_front_min_vm_llvm.sh`（LLVM 環境があれば）
+
+## Fail-Fast Checklist
+- Parser errors include position info (gpos) and stop compilation.
+- Unsupported statements/expressions raise `StageUnsupported` error (box-based), not silent drop.
+- JSON builder ensures key order (`version`, `kind`, `body`, `meta`) for deterministic output.
+
+## Box Layout Proposal (migrated)
+```
+lang/src/compiler/
+├── parser/                    # Stage-1/2/3 parser boxes
+│   ├── parser_box.hako
+│   ├── parser_expr_box.hako
+│   └── parser_stmt_box.hako
+├── emitter/                   # emit helpers and normalization
+│   ├── emitter_box.hako
+│   └── json_program_box.hako
+├── entry/
+│   └── compiler.hako          # entry (Ny→JSON v0)
+└── docs/
+    └── front_mvp.md           # this file
+```
+
+## Execution Examples
+Emit-only (JSON header, pipeline v2):
+```
+NYASH_USE_NY_COMPILER=1 \
+NYASH_NY_COMPILER_MIN_JSON=1 \
+NYASH_NY_COMPILER_CHILD_ARGS="--pipeline-v2" \
+NYASH_NY_COMPILER_EMIT_ONLY=1 \
+NYASH_JSON_ONLY=1 \
+./target/release/hakorune --backend vm apps/tests/selfhost_min/const_ret.hako
+```
+Expected output: `{"version":0,...}` single-line JSON.
+
+Execute via VM (Result comparison):
+```
+NYASH_USE_NY_COMPILER=1 \
+NYASH_NY_COMPILER_EMIT_ONLY=0 \
+NYASH_SELFHOST_READ_TMP=1 \
+./target/release/hakorune --backend vm apps/tests/selfhost_min/const_ret.hako
+```
+Expected output: `Result: 42`
+
+## Timeline (rolling)
+- **Day 1**: Docs + const/return + binop. Add selfhost_min_const_ret smoke.
+- **Day 2**: if/else, loop sum smoke, branch diagnostics.
+- **Day 3**: Calls/BoxCall minimal, DP integration reuse.
+- **Day 4**: externcall string primitives, verify via `run_llvm_extended.sh`.
+- **Day 5**: CLI polish + docs cleanup + bench harness alignment.
+
+## Open Questions
+- Should Stage-3 acceptance (`break`, `continue`, `throw`) be gated by CLI flag? (Currently via `--stage3`.)
+- JSON v0 normalization: do we normalize binary op names (`+` → `Add`) or keep literal symbols? (Existing Stage-1 uses symbols; MIR builder already maps them.)
+- How much of `ParserBox` should move into dedicated modules for maintainability? (Deferred; focus on MVP shipping.)