# ADR-0039: EXPLAIN over advanced-mode SQL queries

## Status

**Accepted** — decision recorded 2026-05-27. **Implementation deferred**
as a follow-up to the ADR-0037/ADR-0038 teaching-echo effort: the
decision below is settled, but the full design has not been `/runda`'d
or built, and is *not* part of that pass. **Supersedes ADR-0030 §13
OOS-2.**

## Context

ADR-0028 gave the DSL `explain` command: a prefix over `show data` /
`update` / `delete` that runs `EXPLAIN QUERY PLAN` and renders an
annotated, span-styled plan tree. ADR-0030 §13 **OOS-2** excluded
"`EXPLAIN` of advanced-mode SQL queries."

On readback (2026-05-27) that exclusion is a **deferred** out-of-scope
item, not a **rejected** one (see ADR-0000's out-of-scope discipline):
its own wording — *"the DSL `explain` still works for what it already
wraps"* — shows it was "not included in this surface," never "undesirable
for teaching." There was no pedagogical argument against it; it simply
fell outside the Phase-4/5 SQL-surface scope. It surfaced while
characterising advanced-mode `explain` (briefly suspected a bug; it was
OOS-2 behaving exactly as written).

Letting a learner see the plan for the SQL they *wrote* is a natural
extension of ADR-0028's intent, so OOS-2 is lifted.

## Decision

`explain` works over advanced-mode SQL queries — the SQL commands
`Select` / `SqlInsert` / `SqlUpdate` / `SqlDelete` — in addition to the
DSL `ShowData` / `Update` / `Delete` it already wraps (ADR-0028). It runs
`EXPLAIN QUERY PLAN` over the command's validated SQL text and renders
through the **existing ADR-0028 plan tree**. Advanced mode only (the SQL
commands are advanced-only); the DSL `explain` stays available in both
modes, unchanged. **Supersedes ADR-0030 §13 OOS-2.**

## Design sketch (deferred to the build)

- **Grammar.** The `explain` inner gains the SQL statement shapes in
  advanced mode, alongside the DSL trio — mirroring how `explain` already
  wraps the DSL nodes, here wrapping the SQL command shapes.
- **Execution.** Run `EXPLAIN QUERY PLAN` over the carried SQL text (the
  `Sql*` / `Select` commands already hold validated text); reuse
  ADR-0028's plan capture + renderer. `EXPLAIN QUERY PLAN` never executes
  the statement, so explaining a destructive SQL command is safe — the
  same property ADR-0028 already relies on.
- **Mode.** SQL inner only in advanced mode; DSL inner in both, unchanged.

Built test-first when picked up.

## Out of scope

- **EXPLAIN of DDL** (`CREATE` / `ALTER` / `DROP`). `EXPLAIN QUERY PLAN`
  applies to `SELECT` / `INSERT` / `UPDATE` / `DELETE`; DDL has no query
  plan. *(Deferred — may be revisited if a useful rendering emerges; per
  ADR-0000's out-of-scope discipline, this is deferred, not rejected.)*

## Consequences

- A self-contained feature, orthogonal to the DSL → SQL echo (ADR-0038):
  the echo renders SQL *from* DSL commands; this explains SQL the user
  *wrote*. They share nothing but the plan renderer's lineage.
- One OOS item in ADR-0030 §13 is now superseded; the rest stand.

## See also

- ADR-0028 — the DSL `explain` and the span-styled plan tree this reuses.
- ADR-0030 §13 — OOS-2, superseded here.
- ADR-0032 / ADR-0033 — the SQL `SELECT` / DML this explains.
- ADR-0000 — the out-of-scope discipline that reframed OOS-2 as deferred.