rdbms-playground/docs/handoff/20260527-handoff-45.md

# 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.