diff --git a/docs/handoff/20260527-handoff-45.md b/docs/handoff/20260527-handoff-45.md new file mode 100644 index 0000000..b4066ef --- /dev/null +++ b/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.