docs(adr): design the DSL→SQL teaching echo (ADR-0038) + dependencies
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]).
This commit is contained in:
@@ -0,0 +1,73 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user