# Session handoff — 2026-05-27 (46)

Forty-sixth handover. **We are mid-feature** — the DSL → SQL teaching
echo (ADR-0038) is partially built (a working walking skeleton). Read
this carefully before continuing; §4 and §5 are the load-bearing parts.

## §1. State at handoff

**Branch:** `main`. **HEAD `04c8e42`.** **Tests: 1970 passing, 0 failing,
0 skipped, 1 ignored.** **Clippy: clean** (`--all-targets -D warnings`,
nursery).

This session designed the **DSL → SQL teaching echo** (ADR-0030 §10) as a
`/runda`'d design set and began building it. Commits since handoff-45's
`2bcc55f`:

```
04c8e42 feat: DSL→SQL teaching echo — channel + create-table slice (ADR-0037 + ADR-0038)
9a23e28 fix: update … --all-rows falls back to the DSL instead of misparsing (ADR-0033 Am4)
338dc8a feat: advanced ALTER COLUMN SET/DROP NOT NULL & DEFAULT, SET DATA TYPE (ADR-0035 Am2)
9f15f38 docs(adr): design the DSL→SQL teaching echo (ADR-0038) + dependencies
```

## §2. The feature & its build plan

**Goal:** when a **DSL-form** command runs **in advanced mode**, echo the
equivalent SQL beneath `[ok]`, so a learner reads off the SQL spelling
(ADR-0030 §10). Authoritative spec: **ADR-0038** (read it — the catalogue
in §7, the copy-paste contract §1, the three-category framework §6).

Five ADRs, all **Accepted/Proposed and `/runda`'d** (the design `/runda`
verdict was PASS with fixes applied — see the ADRs):

| ADR | What | Build status |
|---|---|---|
| **ADR-0035 Am2** | standard-first dialect + `ALTER COLUMN SET/DROP NOT NULL`, `SET/DROP DEFAULT`, ISO `SET DATA TYPE` | ✅ **done** (`338dc8a`) |
| **ADR-0033 Am4** | `update … --all-rows` falls back to DSL (was a misparse) | ✅ **done** (`9a23e28`) |
| **ADR-0037** | `EffectiveMode` execution-time side-channel (the echo's gate) | ✅ channel **done** (`04c8e42`) |
| **ADR-0038** | the echo + full catalogue | 🚧 **skeleton only** — `create table` echoes; rest of the catalogue pending |
| **ADR-0039** | EXPLAIN over advanced SQL | ⏸ **deferred follow-up** — decision recorded, NOT this feature |

Build order was Am2 → Am4 → (0037+0038 merged). **0037 and 0038 were
merged into one build step** because the channel is dead code without its
consumer (`-D warnings` rejects it) — see ADR-0037 Implementation notes.

## §3. The doc-drift fix (already committed, FYI)

`9f15f38` also reconciled stale notes: **simple-mode column ops (B2/C2)
are implemented**, not pending. `requirements.md` C2/B2 were already
`[x]`; the project `CLAUDE.md` was corrected. (Don't re-flag this.)

## §4. The echo architecture — how it works NOW (read before editing)

Data flow for the **interactive** path (replay is separate — see below):

1. **`app.rs::submit`** computes the three-way **`EffectiveMode`**
   (`Simple` / `AdvancedPersistent` / `AdvancedOneShot`) — *reusing the
   pre-existing `EffectiveMode` enum*, NOT a new `SubmissionMode` (ADR-0037
   was corrected to reuse it). Passes it to `dispatch_dsl`.
2. **`app.rs::dispatch_dsl(input, submission_mode: EffectiveMode)`** parses
   with `submission_mode.as_mode()` (the two-way `Mode` the walker needs),
   and emits **`Action::ExecuteDsl { command, source, submission_mode }`**
   (new field, `action.rs`).
3. **`runtime.rs` Action::ExecuteDsl handler** → `spawn_dsl_dispatch(…,
   submission_mode)`.
4. **`runtime.rs::spawn_dsl_dispatch`**: computes
   `echo = crate::echo::echo_for(&command, submission_mode)` →
   `Option<String>`, executes the command, and attaches `echo` to the
   **`AppEvent::DslSucceeded { …, echo }`** (new field, `event.rs`).
5. **`app.rs` update() DslSucceeded arm** stashes `self.pending_echo = echo`
   just before calling `handle_dsl_success`.
6. **`app.rs::note_ok_summary`** (the shared `[ok]` pusher, called by every
   success handler) pushes `[ok] …` then, if `pending_echo` is `Some`,
   pushes the echo line `Executing SQL: <sql>` (i18n key
   `echo.executing_sql`). The stash is set+consumed within one synchronous
   `update()`, so it's safe (no interleaving).

**The renderer:** `src/echo.rs`. `echo_for(command, mode)` gates (advanced
effective mode + DSL-form) and calls `command_to_sql(command) ->
Option<String>`. **`command_to_sql` currently handles only
`Command::CreateTable`** → `CREATE TABLE T (id serial PRIMARY KEY)`
(single inline / compound table-level PK, playground type vocabulary).
Everything else returns `None` (no echo yet).

**Replay is silent for free:** `run_replay` calls `execute_command_typed`
**directly**, bypassing `spawn_dsl_dispatch`, so replayed lines never
reach the echo path. No `interactive` flag needed.

**Where the echo is built (ADR correction):** NOT in the db.rs worker —
the worker gets *decomposed* calls, not the `Command`. The runtime's
dispatch is where `Command` + mode + result converge. ADR-0037 §3 /
ADR-0038 §4 were corrected to say so.

## §5. What's next — expanding the renderer (the actual work)

Per ADR-0038 §8 phasing. **The catalogue (ADR-0038 §7) is the spec** —
each row is a round-trip test (parse the echo in advanced mode → a
same-effect command; the §1 contract). Order:

### Phase 1 — rest of Bucket A (single-statement)
Expand `command_to_sql` for: `add column`, `drop column` (non-cascade),
`rename column`, `change column` (→ `ALTER COLUMN c SET DATA TYPE ty` —
**now runnable, Am2 shipped**), `add constraint` (NotNull→`SET NOT NULL`,
Default→`SET DEFAULT v`, Unique→`ADD UNIQUE (c)`, Check→`ADD CHECK (e)`),
`drop constraint` (NotNull/Default only; Unique/Check column-level →
Bucket C), `show data` (→ `SELECT * FROM T [WHERE …] [ORDER BY <pk> LIMIT
n]`), and the `delete … --all-rows` / `update … --all-rows` fall-throughs
(**now fall back, Am4 shipped**).

For EACH new command, also:
- add an `echo: Option<String>` field to its success event
  (`DslAddColumnSucceeded`, `DslDropColumnSucceeded`,
  `DslChangeColumnSucceeded`, `DslDataSucceeded`, `DslUpdateSucceeded`,
  `DslDeleteSucceeded`),
- set it from `echo` in `spawn_dsl_dispatch`'s matching arm,
- stash `self.pending_echo = echo` in the App's matching update() arm.
  (`note_ok_summary` already renders it for all.)

**Needs Expr→SQL + Value→SQL-literal renderers** (ADR-0038 §5 literal
table): for `show data` WHERE filters, `add constraint check`/`default`
values, etc. `blob` has no literal (moot — no blob literal syntax). Auto-
gen columns omitted from INSERT echoes.

### ⚠️ CRITICAL gotcha for Bucket B + category-3
The skeleton computes `echo` **BEFORE** `execute_command_typed` (it only
needs the `Command`). **Bucket B (resolved auto-names) and category-3
(generated shortids, conversion counts) need the *execution result*.** So
when you implement those, **move/augment the echo build to AFTER
execution**, reading the `CommandOutcome`/result (the resolved index name,
the `client_side.*` notes — ADR-0017 §6 / ADR-0018 §9). The runtime has
both (it builds the event from command + outcome). This is the one place
the current skeleton structure must change.

### Phase 2 — Bucket B
Resolved names (`drop index on T(cols)` → `DROP INDEX <resolved>`, drop/
add relationship, auto-named `add index`) and **multi-line** echoes (one
statement per line: `drop column --cascade`, `add relationship
--create-fk`). ADR-0038 §6 category 2. The echo payload likely becomes
`Vec<String>` (one per statement) — generalise `Option<String>`.

### Phase 3 — category-3 prose expansion
shortid generation, type-conversion transforms, and the `change column
--dont-convert` **caveat** (ADR-0038 §6). De-emphasised prose from the
worker's `client_side.*` notes.

### Polish (not yet done)
The echo line is currently a **plain `[system]` line** via `note_system`.
ADR-0038 §4 wants it **de-emphasised** (styled-runs, ADR-0028). Refine the
rendering (an `OutputLine` with `styled_runs`, dimmed `Executing SQL:`
prefix) — a TODO, deferred so the skeleton stayed small.

## §6. Catalogue cheat-sheet (authoritative: ADR-0038 §7)

- **Echoes** (DSL-only spellings in advanced mode): all DDL forms +
  `show data` + `delete/update … --all-rows`. DSL column-op syntax is
  `<verb> column in/from/to T: c (type)` (**colon + parens**); index/rel
  naming is `as N` (not `named`).
- **NOT echoed**: `insert`/`update … where`/`delete … where` (SQL-first →
  `Sql*` = already SQL), `drop table`, `drop index <name>` (→ `Sql*`),
  `show table`, `explain`, `replay`, app commands, column-level
  UNIQUE/CHECK *drop* (residual gap, ADR-0035 Am2). `change column
  --dont-convert` → echoes the headline + a category-3 **caveat**.

## §7. Process pins (unchanged)

- **Confirm every commit** (propose message, wait). **No AI attribution.**
- **Test-first**; green + clippy-clean is the only acceptable end state;
  baseline **1970 / 0 / 1**.
- **Keep docs lockstep**: ADR + `README.md` index + `requirements.md`.
  Amend ADRs, don't re-litigate. **Raise implementation deviations and
  update the ADR** (this session corrected ADR-0035 Am2's SET DEFAULT
  executor, ADR-0037's enum + build-layer, ADR-0038 §4 in-place).
- **Round-trip every catalogue row** (the §1 copy-paste contract).

## §8. How to take over

1. **Read, in order:** this file → **ADR-0038** (§1 contract, §6
   categories, §7 catalogue, §8 phasing) → **ADR-0037** (channel +
   Implementation notes) → the four commits above → **`src/echo.rs`** (the
   renderer to expand).
2. **Baseline:** `cargo test` (1970 / 0 / 1) + `cargo clippy --all-targets
   -- -D warnings` (clean).
3. **Continue** with §5 Phase 1 (rest of Bucket A), test-first, one
   command at a time, round-tripping each echo. Heed the §5 ⚠️ gotcha
   before touching Bucket B / category-3.
4. ADR-0039 (EXPLAIN over advanced SQL) is a **separate deferred
   follow-up**, not this feature.