docs: session handoff 49 — ADR-0038 done, M4 + ADR statuses in sync
This commit is contained in:
claude@clouddev1
@@ -2,11 +2,12 @@
|
||||
|
||||
## Status
|
||||
|
||||
Accepted. Design agreed with the user (2026-05-27); **Phases 1–3
|
||||
implemented and verified** by round-tripping every catalogue row
|
||||
(§7 Buckets A, B, plus the §6 category-3 prose) through the
|
||||
Accepted. Design agreed with the user (2026-05-27); **fully
|
||||
implemented and verified** — every catalogue row (§7 Buckets A, B,
|
||||
plus the §6 category-3 prose) round-trips per line through the
|
||||
advanced-mode walker (the §1 copy-paste contract; §6 category 2
|
||||
holds it per line). Shipped across three feature commits:
|
||||
holds it per line), and the §4 de-emphasised styled-runs rendering
|
||||
polish (ADR-0028) is wired. Shipped across four feature commits:
|
||||
**Phase 1 — Bucket A single-statement** (handoff-46's `04c8e42`
|
||||
delivered the channel + create-table slice; handoff-47's `90479cb`
|
||||
expanded to the full Bucket A — `Value → SQL-literal` + `Expr → SQL`,
|
||||
@@ -31,8 +32,17 @@ already surfaced via the pre-existing `client_side.auto_fill_*` /
|
||||
`change column --dont-convert` **caveat** (the only Bucket A
|
||||
caveat; every other category-3 line is illuminating), gated on an
|
||||
advanced effective mode because it references "the line above".
|
||||
**The §4 de-emphasised styled-runs rendering polish remains** — the
|
||||
echo + caveat currently surface as plain `[system]` lines.
|
||||
**Phase 4 styled-runs polish** (`2aab457`): the echoed SQL renders
|
||||
as code — a new `OutputKind::TeachingEcho` line with a dimmed
|
||||
`Executing SQL:` prefix followed by the SQL re-lexed in advanced
|
||||
mode via `input_render::lex_to_runs_in_mode` for token-class
|
||||
colouring (the same treatment the input echo gets); every
|
||||
category-3 prose line (the new caveat plus the pre-existing
|
||||
illuminating notes) renders dimmed via a new
|
||||
`OutputStyleClass::Hint` styled-runs class resolving to
|
||||
`theme.muted`. Scope went slightly beyond §4's "echo + caveat" to
|
||||
cover the illuminating cat-3 notes too — user-confirmed, in service
|
||||
of §6's "de-emphasised prose line" wording for every cat-3 line.
|
||||
**Realises ADR-0030 §10** ("The DSL → SQL teaching bridge") — the
|
||||
Phase-5 echo that **ADR-0035 §12 forward-referenced** as "a separate
|
||||
ADR." Builds on **ADR-0037** (the execution-time mode side-channel
|
||||
|
||||
+2
-2
File diff suppressed because one or more lines are too long
@@ -0,0 +1,171 @@
|
||||
# Session handoff — 2026-05-28 (49)
|
||||
|
||||
Forty-ninth handover. **ADR-0038 is done.** 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,
|
||||
and the §4 de-emphasised styled-runs rendering polish landed in
|
||||
`2aab457`. 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 `2aab457`.** **Tests: 2019 passing, 0
|
||||
failing, 0 skipped, 1 ignored.** **Clippy: clean**
|
||||
(`--all-targets -D warnings`, nursery).
|
||||
|
||||
Commits since handoff-48's `df5c4e2`:
|
||||
|
||||
```
|
||||
2aab457 feat: DSL→SQL teaching echo — §4 styled-runs polish (ADR-0038)
|
||||
```
|
||||
|
||||
(Plus this handoff + lockstep doc updates landing alongside it.)
|
||||
|
||||
## §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 the /runda DA cleanup at `5cb105b` (doc-drift + Bucket C
|
||||
explicit tests).
|
||||
|
||||
ADR-0037 and ADR-0038 both **Accepted** with implementation notes
|
||||
referencing every shipping commit.
|
||||
|
||||
## §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 pin the polish — `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), `app::tests::
|
||||
polished_echo_carries_teaching_echo_kind_and_caveat_a_hint_span`
|
||||
(App-side wiring kinds + styled_runs shape). The pre-existing echo
|
||||
tests pass unchanged — the text content is identical, only styling
|
||||
changed.
|
||||
|
||||
## §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 **2019 / 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` (2019 / 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).
|
||||
+21
-16
@@ -132,22 +132,27 @@ handoff-14 cleanup; 449 after B2/C2.)
|
||||
ADR-0030 §10 teaching echo on it: a DSL-form command run in
|
||||
advanced/one-shot mode renders the equivalent advanced-mode SQL
|
||||
beneath `[ok]`; simple-mode and SQL-entered submissions stay
|
||||
silent. Echo coverage: **Buckets A and B complete, plus
|
||||
category-3 prose** — every catalogue row in ADR-0038 §7
|
||||
round-trips per line through the advanced walker (the §1
|
||||
copy-paste contract; §6 category 2 holds it per line). Shipped
|
||||
across three commits: **Phase 1** Bucket A — single-statement DDL
|
||||
+ `show data` + `--all-rows` fall-throughs (`90479cb`); **Phase 2**
|
||||
Bucket B — resolved-name + multi-line echoes (`add index` auto- and
|
||||
user-named, positional `drop index`, `add`/`drop relationship` in
|
||||
both selector forms, `drop column --cascade`, `add relationship
|
||||
--create-fk`) (`275c726`); **Phase 3** the category-3 prose —
|
||||
`shortid` generation and type-conversion transforms via the
|
||||
pre-existing `client_side.auto_fill_*` / `client_side.transformed*`
|
||||
notes, plus the new `change column --dont-convert` caveat
|
||||
(`e6ad1ae`). The only remaining ADR-0038 item is the §4
|
||||
de-emphasised **styled-runs rendering polish** (ADR-0028) — the
|
||||
echo + caveat currently surface as plain `[system]` lines.
|
||||
silent. Echo coverage: **ADR-0038 is feature-complete** — every
|
||||
catalogue row in §7 round-trips per line through the advanced
|
||||
walker (the §1 copy-paste contract; §6 category 2 holds it per
|
||||
line), every §6 category-3 line surfaces, and the §4
|
||||
de-emphasised styled-runs rendering polish (ADR-0028) is wired.
|
||||
Shipped across four feature commits: **Phase 1** Bucket A —
|
||||
single-statement DDL + `show data` + `--all-rows` fall-throughs
|
||||
(`90479cb`); **Phase 2** Bucket B — resolved-name + multi-line
|
||||
echoes (`add index` auto- and user-named, positional
|
||||
`drop index`, `add`/`drop relationship` in both selector forms,
|
||||
`drop column --cascade`, `add relationship --create-fk`)
|
||||
(`275c726`); **Phase 3** category-3 prose — `shortid` generation
|
||||
and type-conversion transforms via the pre-existing
|
||||
`client_side.auto_fill_*` / `client_side.transformed*` notes, plus
|
||||
the new `change column --dont-convert` caveat (`e6ad1ae`); **Phase
|
||||
4 styled-runs polish** — `OutputKind::TeachingEcho` custom
|
||||
rendering branch (dimmed `Executing SQL:` prefix + the SQL re-lexed
|
||||
via `input_render::lex_to_runs_in_mode(Advanced)` for token
|
||||
highlighting, same as the input echo), `OutputStyleClass::Hint`
|
||||
for every cat-3 prose line (caveat + the existing illuminating
|
||||
notes — broader scope, visually consistent) (`2aab457`).
|
||||
|
||||
## App-level commands (per ADR-0003)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user