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.