# Session handoff — 2026-05-28 (49)

Forty-ninth handover. **ADR-0038 is done** — and twice DA-audited.
Every catalogue row of the DSL → SQL teaching echo is implemented,
every echo round-trips per line per the §1 copy-paste contract,
every §6 category-3 line surfaces, the §4 de-emphasised styled-runs
rendering polish landed in `2aab457`, and a closing /runda Devil's-
Advocate pass over the polish (`6840b92`) pinned three minor wiring
gaps. Docs in sync. If you continue, pick a fresh feature; if you're
triaging, ADR-0038 won't surprise you.

## §1. State at handoff

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

Commits since handoff-48's `df5c4e2`:

```
6840b92 test: /runda round 2 — pin TeachingEcho kind + cat-3 prose wiring
63b2927 docs: session handoff 49 — ADR-0038 done, M4 + ADR statuses in sync
2aab457 feat: DSL→SQL teaching echo — §4 styled-runs polish (ADR-0038)
```

The first version of this handoff went out with `63b2927` at HEAD;
this amendment (committed after `6840b92`) records the closing
/runda round 2 below.

## §2. ADR-0038 — done

The feature shipped across **five** commits, the last of which is the
§4 polish:

| Commit | Phase | What |
|---|---|---|
| handoff-46 `04c8e42` | 1 (start) | channel + create-table slice |
| `90479cb` | 1 (rest) | Bucket A renderer — every single-statement DDL row + `show data` + `--all-rows` fall-throughs; create-table contract-gap fix |
| `275c726` | 2 | Bucket B — resolved-name + multi-statement (auto- and user-named `add index`, positional `drop index`, `add`/`drop relationship` in both selector forms, `drop column --cascade`, `add relationship --create-fk`) |
| `e6ad1ae` | 3 | category-3 prose — `change column --dont-convert` *caveat* (the other two cat-3 lines were already in place via `client_side.*` keys) |
| `2aab457` | 4 (polish) | §4 styled-runs rendering — `OutputKind::TeachingEcho` with dimmed prefix + advanced-mode lex of the SQL; `OutputStyleClass::Hint` for every cat-3 prose line |

Plus **two** /runda Devil's-Advocate passes — `5cb105b` after
Phase 3 (doc-drift + Bucket C explicit no-echo tests) and
`6840b92` after the polish (kind assertions on every echo arm +
the broader-scope `client_side` notes pinning, see §3a below).
Neither pass escalated.

ADR-0037 and ADR-0038 both **Accepted** with implementation notes
referencing every shipping commit.

## §2a. /runda round 2 findings (closed by `6840b92`)

A second Devil's-Advocate pass over the polish surfaced three
test-coverage gaps the polish itself had left behind. All three were
closed in `6840b92`; tests-only commit (+98 lines in `src/app.rs`),
no production code touched.

- **`bucket_a_success_events_render_the_teaching_echo_beneath_ok`** and
  **`bucket_b_multi_line_echo_renders_one_line_per_statement_beneath_ok`**
  only checked line *text*. After the polish, every echo line is
  pushed via `push_teaching_echo` and carries
  `OutputKind::TeachingEcho` — and the kind is what fires
  `ui::render_output_line`'s dim-prefix + advanced-lex branch. A
  regression to plain `System` would leave the text intact while
  silently breaking the styling. The `assert_echo_beneath_ok`
  helper now pins `kind == TeachingEcho` on every event arm the
  bucket_a test covers (six arms in one shot); the bucket_b test
  pins it on each of the three multi-statement lines.
- **`add_column_client_side_notes_render_as_category_three_prose`**
  (new) pins the broader-scope polish: `handle_dsl_add_column_success`'s
  illuminating `client_side_notes` (shortid / serial auto-fill, per
  `client_side.auto_fill_*` keys) now route through
  `push_category_three_prose`, producing a System line with a
  whole-text Hint span. The closely-related caveat path was already
  pinned by `polished_echo_carries_teaching_echo_kind_and_caveat_a_hint_span`;
  this completes the cat-3 prose coverage symmetrically.

What the round-2 pass *verified clean* (no action needed) — kept
here as a flight log so the next session doesn't re-walk the same
ground:

- All four `OutputKind` matches in `ui.rs` (tag_len, tag, Echo-
  branch detection, body_style) handle the new variant; no other
  code matches on `OutputKind`.
- `OutputStyleClass::Hint` resolution works on both light + dark
  (`hint_class_resolves_to_muted_foreground`).
- ADR-0028 §7 OOS "no re-styling existing output" is not violated:
  ADR-0038 takes ownership of styling its own cat-3 content; the
  broader-scope was user-confirmed and recorded.
- The hybrid styling (custom path for SQL via `lex_to_runs` +
  `styled_runs` for prose) follows the precedent established by
  `OutputKind::Echo` / ADR-0022 §5; ADR-0028 §5 anticipates this
  ("any output line may now carry rich styling").
- Replay bypass unchanged; no AI attribution anywhere; clippy clean.

Acceptable observations the round-2 pass left *documented but not
fixed* — none warranted escalation:

- The `2aab457` commit message and the `en-US.yaml` comment overstate
  the reason `TEACHING_ECHO_LABEL` became a const ("i18n template
  couldn't provide that"). Reality: simpler + avoids resolving i18n
  per render (a hot path). Historic — not amending; this handoff
  is the more accurate forward-looking reference.
- The two rendering-path tests
  (`teaching_echo_line_renders_dim_prefix_and_lexed_sql`,
  `category_three_prose_line_renders_all_dim`) only use the dark
  theme; the rendering logic is theme-agnostic and the class
  resolution is pinned for both, so this is pedantic-incomplete
  rather than a real gap.
- No full-pipeline integration test driving submit → spawn → render
  (same observation as §4 below, restated for completeness).

## §3. What the polish (Phase 4) does, in shape

Per ADR-0038 §4 + §6, the de-emphasised styled-runs treatment landed
in `2aab457`. The user-confirmed scope (per session discussion) went
slightly beyond §4's "echo + caveat" to cover the existing
illuminating cat-3 notes too — visual consistency for every cat-3
prose line, matching §6's "de-emphasised prose line" wording.

**The polish in code:**

- **`OutputKind::TeachingEcho`** (new). Lines with this kind go through
  a custom `ui::render_output_line` branch that mirrors the
  `OutputKind::Echo` simple-mode input-echo path: strip the canonical
  `crate::echo::TEACHING_ECHO_LABEL` ("Executing SQL: "), render the
  prefix dimmed (`theme.muted`), then lex the rest in `Mode::Advanced`
  via `input_render::lex_to_runs_in_mode` and emit one span per token.
  Tag stays `[system]` for visual consistency with other system
  output.
- **`OutputStyleClass::Hint`** (new), resolved to `theme.muted` by
  `output_span_style`. Carried on category-3 prose lines as a single
  styled-runs span covering the whole text (so the body renders
  dimmed; the `[system]` tag keeps its kind tint).
- **`crate::echo::TEACHING_ECHO_LABEL`** (new pub const) — the fixed
  byte boundary the ui.rs branch needs. The label moved out of the
  `echo.executing_sql` i18n key (now retired in en-US.yaml + keys.rs;
  a comment in en-US.yaml points future locales at re-introducing
  it).
- **App-side helpers**: `App::push_teaching_echo(sql)` builds the
  TeachingEcho line; `App::push_category_three_prose(text)` builds a
  System line with a whole-text Hint span. `note_ok_summary` and
  `handle_dsl_change_column_success` / `handle_dsl_add_column_success`
  use these instead of plain `note_system` for the echo, the
  DontConvert caveat, and the illuminating client-side notes.

**Where each rendering rule lives:**

| Line | Built by | Renders as |
|---|---|---|
| `[ok] verb subject` | `note_ok_summary` via `note_system` | `[system]` tag + `system` green body (unchanged) |
| `Executing SQL: <sql>` (one per echo line) | `push_teaching_echo` | `[system]` tag + dimmed prefix + token-coloured SQL |
| `[client-side] N row(s) were transformed …` | `push_category_three_prose` (auto_fill_*, transformed*) | `[system]` tag + whole-body dim |
| `[client-side] --dont-convert kept …` | `push_category_three_prose` (caveat path) | `[system]` tag + whole-body dim |
| structure render, row counts, etc. | `note_system` | unchanged |

**Coverage:** four new tests landed with the polish itself
(`2aab457`) — `ui::tests::teaching_echo_line_renders_dim_prefix_and_lexed_sql`
(asserts the dim prefix span + keyword-coloured SQL spans confirm
advanced-mode lex), `ui::tests::category_three_prose_line_renders_all_dim`
(whole-text Hint coverage), `ui::tests::hint_class_resolves_to_muted_foreground`
(theme resolution across both palettes), and
`app::tests::polished_echo_carries_teaching_echo_kind_and_caveat_a_hint_span`
(App-side wiring kinds + styled_runs shape on the caveat path). The
pre-existing echo tests pass unchanged — the text content is
identical, only styling changed. The /runda round 2 (`6840b92`)
added three more (see §2a): kind assertions on every event arm
covered by the bucket_a / bucket_b multi-statement tests, plus a
focused test pinning the broader-scope `client_side_notes` →
`push_category_three_prose` path on add column.

## §4. Notable observations carried over from handoff-48

These are the same ones flagged before the polish — none became
blockers, the polish didn't introduce new ones.

- **Unquoted-identifier round-trip caveat.** Echo style is bare
  identifiers (matching the original create-table echo aesthetic). A
  user-created column or table named after a SQL keyword (e.g.
  `ORDER`, `SELECT`) would produce an echo whose round-trip is
  fragile. Pre-existing limitation; the §1 contract is only formally
  violated for this edge case. Fix is identifier-quoting if it ever
  bites a learner.
- **No full-spawn integration test for the echo pipeline.** Coverage
  is layered (pure renderers + runtime-helper unit tests with real
  Database + App-level rendering tests + ui.rs styling tests). The
  unwired glue is small; a Tier-3 end-to-end test would complete the
  picture, not blocking.
- **Pure-Command Schema commands double-compute echo.** `echo_for` is
  called for every command; the Schema arm recomputes via
  `build_schema_echo` (whose catch-all redelegates to
  `command_to_sql`). Minor inefficiency, no behaviour bug.

## §5. What's next

Up to you. ADR-0038 won't pull on any more rope. Candidate features:

- **ADR-0039 — EXPLAIN over advanced-mode SQL queries** (`Accepted`,
  implementation deferred). Self-contained: lets `explain` wrap the
  advanced SQL commands (`Select`/`SqlInsert`/`SqlUpdate`/
  `SqlDelete`) in addition to the DSL `ShowData`/`Update`/`Delete` it
  already covers (ADR-0028). Test-first when picked up.
- **Other tracks** from `requirements.md` — see the file for the
  pending list. Likely candidates: track 2 (project storage Iter 5/6
  — export/import + `--resume` + persistent input history + migration
  framework), `C3a` (modify relationship), `C4` (m:n convenience),
  `H1`/`H1a` (friendly error layer + syntax-help in parse errors),
  the tutorial/lesson system, V4 session log + Markdown export, the
  remaining input UX items (`I1`/`I1b` multi-line + readline
  shortcuts, `I3` tab completion polish, `I4` syntax highlighting
  beyond input echo).
- **Polish-spawned ideas** from this session — none currently
  outstanding; the OutputStyleClass vocabulary now has `Hint` and
  could grow further if another consumer needs it.

## §6. Process pins (unchanged)

- **Confirm every commit** (propose message, wait). **No AI attribution.**
- **Test-first**; green + clippy-clean is the only acceptable end
  state; current baseline **2020 / 0 / 1**.
- **Keep docs lockstep**: ADR + `README.md` index + `requirements.md`.
  This session's polish commit ships alongside this handoff and the
  three doc-update edits (M4 / ADR-0038 Status / ADR-0037 + ADR-0038
  README index entries).
- **Round-trip every catalogue row** (the §1 copy-paste contract; for
  multi-statement, *per line*).

## §7. How to take over

1. **Read, in order:** this file → `requirements.md` for the open
   tracks → the relevant ADR for whatever feature you pick up.
   ADR-0038 / ADR-0037 are done and well-documented; touch them only
   to amend if a real correction comes up.
2. **Baseline:** `cargo test` (2020 / 0 / 1) + `cargo clippy
   --all-targets -- -D warnings` (clean).
3. **For a fresh feature**: write the ADR (or extend an existing
   one), run `/runda` over the design before building, then build
   test-first.
4. **The ADR-0028 styled-runs vocabulary** is now richer: `Neutral`,
   `Efficient`, `Expensive`, `AutomaticIndex`, `Hint`. Adding a new
   consumer? Pattern is one variant per semantic class, theme-resolved
   in `ui::output_span_style`, used via `OutputLine::styled` or a
   dedicated kind + custom render branch (as `TeachingEcho` does for
   the dim-prefix + lex-rest case).