docs: session handoff 45 — X4 resolved; next direction = DSL→SQL teaching echo (ADR-0030 §10)

docs/handoff/20260527-handoff-45.md

@@ -0,0 +1,147 @@
+# Session handoff — 2026-05-27 (45)
+
+Forty-fifth handover. Short delta on top of handoff-44: this stretch
+**resolved X4** (the advanced-mode `serial` auto-fill bug) and ran a
+`/whatsnext` review. With the advanced-mode SQL milestone fully closed,
+the user picked the **DSL → SQL teaching echo (ADR-0030 §10)** as the next
+direction. That work is **design-heavy and almost certainly needs its own
+ADR first** — see §3.
+
+## §1. State at handoff
+
+**Branch:** `main`. **HEAD `42306d3`.** **Tests: 1949 passing, 0 failing,
+0 skipped, 1 ignored** (the `friendly/mod.rs` ` ```ignore ` doctest).
+**Clippy:** clean.
+
+Since handoff-44, one commit:
+
+```
+42306d3 fix: X4 — advanced-mode SQL INSERT auto-fills omitted non-PK serial (MAX+1)
+```
+
+## §2. What closed since handoff-44
+
+- **X4 — resolved.** Advanced-mode SQL `INSERT` (Form A) that omitted a
+  non-PK `serial` used to leave it **silently NULL** (the column is
+  `INTEGER UNIQUE`, not `NOT NULL`); it now auto-fills `MAX+1` per row,
+  matching simple mode and the existing `shortid` fill (ADR-0018 §1/§5
+  "auto-generated on every path"). The advanced-mode auto-fill helper was
+  renamed **`plan_shortid_autofill` → `plan_autogen_autofill`** (it fills
+  both auto-gen types now). PK serial stays on the rowid alias; Form B
+  supplies every column. Test:
+  `tests/sql_insert.rs::sql_insert_autofills_omitted_nonpk_serial`.
+  `requirements.md` X4 marked resolved. No ADR amendment (the fix
+  *complies* with ADR-0018's existing contract).
+
+With X4 closed and **ADR-0036 fully implemented** (handoff-44), the
+**advanced-mode SQL surface arc (ADRs 0030–0036) is complete** with no
+loose ends.
+
+## §3. Next direction (decided with the user) — DSL → SQL teaching echo
+
+**ADR-0030 §10 "The DSL → SQL teaching bridge".** When a **DSL-form**
+command runs **in advanced mode**, its output includes the equivalent SQL,
+so a learner who knows the simple-mode form reads off the SQL spelling.
+Per §10: a `Command → SQL` renderer (the inverse of §4's DDL translator);
+fires only for DSL-entered commands in advanced mode (a command already
+typed as SQL is not echoed; simple mode is left uncluttered); renders as a
+de-emphasised `OutputLine` (styled-runs, ADR-0028) beneath the `[ok]`
+summary; app-level commands have no SQL form and aren't echoed. OOS-5
+(ADR-0030 §13): the reverse SQL → DSL echo is out.
+
+**This is design-first, not a straight build. The first task is to settle
+the mechanism in an ADR (or an amendment to ADR-0030/0033).** The key open
+question:
+
+- **Does the echo need the deferred execution-time mode side-channel
+  (M4)?** ADR-0033 **Amendment 3** explicitly deferred "the execution-time
+  mode side-channel (three-way `Mode` threaded through `Action`→worker,
+  for mode-dependent *output* like echoing generated SQL)" to its own
+  future ADR — naming this very echo as the motivating use case. **But on
+  a closer read it may not be needed for the echo itself:**
+  - *DSL-vs-SQL form* is already intrinsic to command identity
+    (`Command::Insert` = DSL form vs `Command::SqlInsert` = SQL form;
+    ADR-0033 Amendment 3 "command identity is the mode-rooted grammar-path
+    outcome"). So "echo only DSL-form commands" needs no new signal.
+  - *Mode-at-submission* is already carried render-side by
+    `OutputLine.mode_at_submission` (ADR-0033 Amendment 3 notes this is the
+    only mode side-channel that exists today).
+  - The echo is a **render-side** concern (render the equivalent SQL from
+    the typed `Command` after `[ok]`), and the renderer is a pure
+    `Command → SQL` function — it does **not** need the worker to know the
+    mode.
+
+  So the likely finding: the echo can be delivered **render-side** from
+  (existing `mode_at_submission` + command identity + a new `Command → SQL`
+  renderer), and the broader M4 three-way-side-channel is **not** a
+  prerequisite. **Confirm this before committing** — if true, write a
+  small ADR (or ADR-0030 amendment) recording that the echo is render-side
+  and M4 stays deferred; if false, M4's ADR comes first.
+
+**Then implement:** a `Command → SQL` renderer covering the DSL command
+set (start with the high-value DDL/DML forms; decide coverage in the ADR),
+emitting a de-emphasised styled `OutputLine` beneath `[ok]` for DSL-form
+commands in advanced mode only. There is already a `Command → SQL`-shaped
+precedent to study: the §4 DDL path lowers SQL DDL to typed commands, and
+`schema_to_ddl` (`db.rs`) renders a schema back to `CREATE TABLE` DDL —
+useful reference for the inverse direction.
+
+**Scope/§13 reminders:** no SQL → DSL echo (OOS-5); app commands not
+echoed; engine-neutral SQL in the echo (ADR-0030 §5/§7 — no engine type
+names or product-specific spellings).
+
+## §4. The other tracked candidates (not chosen, for context)
+
+From the `/whatsnext` review — the menu the user chose the echo from:
+
+- **CI / TT5** — **no `.github/workflows/` exists at all**, despite 1949
+  tests and a stated Linux/macOS/Windows target (D1). Self-contained, no
+  design needed. The strongest "infrastructure hygiene" candidate; a good
+  pick any time.
+- **Simple-mode DSL column ops (B2/C2)** — advanced mode can `ALTER
+  TABLE` drop/rename/change-type a column (ADR-0035 4e/4f) but **simple
+  mode can't**; the executors exist, only the DSL grammar + dispatch are
+  missing. Closes a beginner-facing asymmetry.
+- **X5 — framework-cohesion descriptive ADR** — map the grammar/execution
+  framework + the "share a mechanic, not a command" reuse rule, with
+  ADR-0036 as a worked example. Strategic; eases maintenance.
+
+## §5. `requirements.md` accuracy — needs a reconciliation pass
+
+The `requirements.md` checkboxes are the **original Phase-1 list and are
+not reliably synced**: many `[ ]` items are in fact implemented (e.g. the
+mode items M1/M2/M3; test tiers TT1–TT3; the SQL-subset capability Q1/Q2,
+which shipped via the unified **walker**, not the `sqlparser-rs` the item
+still names). A focused set of high-confidence corrections was proposed to
+the user this session (modes, test tiers, Q1/Q2 wording); a fuller
+per-item audit against the ADRs + tree is worth doing as its own small
+task. **Treat `requirements.md` checkbox state as advisory until that pass
+lands** — cross-check against the ADR index (`docs/adr/README.md`), which
+is current. Note `CLAUDE.md` also still says `sqlparser-rs` is "reserved …
+not yet wired", which is stale (SQL is wired via the walker, ADRs
+0030–0033).
+
+## §6. Process pins (unchanged)
+
+- **Confirm every commit** (propose message, wait). No AI attribution.
+- **Escalate genuine choices / grammar + architecture forks.** The echo's
+  mechanism question (render-side vs M4) is exactly such a fork — settle it
+  in an ADR before building.
+- **Test-first**; **keep docs lockstep** (ADR + README index +
+  requirements when a decision lands); **amend ADRs, don't re-litigate**.
+- **Characterize current behaviour before fixing** — X4 turned out to be a
+  silent NULL, not an error, which changed the framing.
+
+## §7. How to take over
+
+1. **Read, in order:** this file → `CLAUDE.md` → **ADR-0030 §10** (the
+   echo) + **ADR-0033 Amendment 3** (command identity + the deferred M4
+   side-channel) → `requirements.md` **M4** → `docs/adr/0030*.md` §4/§11
+   for the DDL-translator precedent.
+2. **Baseline:** `cargo test` (1949 / 0 / 0 / 1 ignored) + `cargo clippy
+   --all-targets -- -D warnings` (clean).
+3. **First step is the ADR**, not code: resolve "render-side vs M4" (§3),
+   get the user's sign-off on mechanism + echo coverage, then implement the
+   `Command → SQL` renderer + the de-emphasised output line, test-first.
+4. Study `schema_to_ddl` (`db.rs`) and ADR-0030 §4's DDL translator as the
+   shape to invert.