claude@clouddev1
9f15f386d5
Realises ADR-0030 §10 (the DSL→SQL teaching bridge) as a /runda'd design
set, before implementation:
- ADR-0037 (new): execution-time mode side-channel — SubmissionMode
{Simple, Advanced, AdvancedOneShot} threaded Action→worker, output-only;
redeems ADR-0033 Amendment 3's deferred follow-up. Replay stays silent.
- ADR-0038 (new): the teaching echo + full catalogue (Buckets A/B/C),
the copy-paste round-trip contract, the three-category framework, and
the Value→SQL-literal renderer. DDL + show-data centric (overlapping
DML is SQL-first, so already SQL). Build-order deps recorded.
- ADR-0035 Amendment 2: standard-first dialect stance + ALTER COLUMN
SET/DROP NOT NULL, SET/DROP DEFAULT, ISO SET DATA TYPE gap-fill.
- ADR-0033 Amendment 4: reclassifies the `update … --all-rows`
non-fall-back as a bug; it now falls back to the DSL Update and echoes
(keyed on adjacent `--`; spaced arithmetic preserved).
- ADR-0039 (new): EXPLAIN over advanced SQL — decision recorded, build
deferred; supersedes ADR-0030 §13 OOS-2.
- ADR-0000: out-of-scope discipline (deferred vs rejected). README index
updated for all of the above.
Reconcile CLAUDE.md: simple-mode column ops are implemented, not pending
(requirements.md C2/B2 already [x]).
74 lines
3.3 KiB
Markdown
74 lines
3.3 KiB
Markdown
# 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.
|