rdbms-playground/docs/handoff/20260518-handoff-16.md

Session handoff — 2026-05-18 (16)

Sixteenth handover. This session was a design run: three interlocking ADRs were designed and committed — ADR-0026 (complex WHERE expressions), ADR-0027 (input-field validity indicator), ADR-0028 (query plans / EXPLAIN QUERY PLAN) — plus one small code fix (the with pk column-spec syntax).

Headline: nothing from the three ADRs is implemented yet. This was deliberate design-ahead, chosen by the user. The next session's job is implementation, and ADR-0026 is the keystone — start there (see §3).

State at handoff

Branch: main. Working tree clean. Four commits since handoff-15 (f4eedf3), all local — the user pushes asynchronously, so do not treat them as blocking:

d9a98bb Grammar: with-pk column specs use name(type), matching add column
9aa7e2e docs: add ADR-0028 — query plans (EXPLAIN QUERY PLAN)
032a050 docs: add ADR-0027 — input-field validity indicator
6e42a11 docs: add ADR-0026 — complex WHERE expressions

Tests: 1039 passing, 0 failing, 1 ignored (cargo test) — unchanged from handoff-15's baseline. The with pk fix is syntax-only, so the count did not move. The ignored test is the long-standing ```ignore doc-test in src/friendly/mod.rs. Typing-surface matrix: 152 cells (two renamed, none added/removed).

Clippy: clean (cargo clippy --all-targets -- -D warnings).

§1. What shipped

ADR-0026 — Complex WHERE expressions (6e42a11)

The C5a design. A stratified, recursive expression grammar — AND / OR / NOT, comparisons (= != <> < <= > >=), LIKE, IS [NOT] NULL, IN, BETWEEN, parentheses — for update / delete / show data filters. show data gains an optional where and an optional limit <n> (a limit implies an implicit primary-key ORDER BY).

Key decisions (settled with the user — do not re-litigate):

• In-grammar recursion (option B). A new Subgrammar(&'static Node) Node variant lets the grammar reference a fragment (incl. itself); the expression grammar is stratified to avoid left recursion. Not the opaque-leaf / pass-through approach.
• MatchedPath stays flat. The expression fragment carries its own AST-fragment builder, invoked by the walker as it recurses — structured output "selectively", only where the grammar is recursive. A new recursive Expr AST.
• SQL generation is parameterised (?-bound, type-converted literals); no raw-text pass-through. The displayed SQL renders literals inline and <> for inequality.
• Permissive type handling. Type-mismatched comparisons and = NULL are flagged (highlight + hint), never block submission, and still run — this relaxes the current bind-time rejection.

ADR-0027 — Input-field validity indicator (032a050)

A debounced [ERR] / [WRN] marker at the input row's right edge, summarising — before submit — whether the current command would run. Backed by a walker diagnostics-severity model: ERROR = known to fail (parse error, unknown table/column); WARNING = valid but likely not intended (type mismatch, = NULL). Advisory only — never blocks submission. ~1 s debounce; the marker strip is reserved unconditionally (6 columns). Needs a new warning theme colour. The WARNING severity has no triggers until ADR-0026 is implemented.

ADR-0028 — Query plans (9aa7e2e)

QA1 + QA2. An explain prefix command over show data / update / delete running EXPLAIN QUERY PLAN (which never executes — so explaining a destructive command is safe). Renders an annotated tree; engine detail text verbatim; an annotation taxonomy (full scan / index search / covering index / PK lookup / automatic index — the standout teaching moment / temp B-tree). Introduces a styled-output-line mechanism — OutputLine gains optional per-span styling, realising the per-span theming ADR-0016 deferred (its OOS-3). The explained SQL is shown above the tree as standard, copy-pasteable SQL.

with-pk grammar fix (d9a98bb)

create table … with pk column specs changed from name:type to name(type), matching add column's col(type) — column-type syntax is now consistent across the DSL. One grammar node (COL_SPEC: : → ( … )); build_create_table was unaffected (reads columns by role). Swept the test suite, the friendly catalog's usage templates, ADR-0009's example, and requirements.md. The : separating table from column in add column / drop column is unchanged.

Docs

• New docs/simple-mode-limitations.md — a running list of what simple-mode DSL queries cannot express that advanced SQL can, seeded from ADR-0026 §10. It feeds the future Q4 SQL-subset spec. Grow it as new boundaries surface.
• requirements.md: C5a [~] → [ ]; QA1 / QA2 updated and the stale QA1 note reconciled; new S6 (the validity indicator) and a new Documentation section with DOC1.

§2. Notes for the next agent

• This session produced no implementation of the three ADRs. Each ADR has an ## Implementation notes section with a step-by-step build order — follow it.
• The three ADRs interlock. ADR-0026's Subgrammar node is reused by ADR-0028's explain. ADR-0027's "general mechanism, single current consumer" shape is echoed by ADR-0028's styled-output-line mechanism.
• Loose end: CLAUDE.md's "Things deliberately deferred" list still says QA1 "needs its own QA2 rendering ADR" — that ADR (0028) now exists. Reconcile the CLAUDE.md list against ADRs 0026/0027/0028 when convenient (a small edit).
• The two follow-up ADRs the validity-indicator discussion spawned are done — ADR-0027 is the indicator ADR; the with pk fix is the other. No tracked follow-ups remain open from this session.

§3. What's next — implement ADR-0026 first

The three ADRs must be implemented. Recommended order:

1. ADR-0026 (C5a) — the keystone. Its build order: (1) the Subgrammar node; (2) the expression grammar fragment + Expr AST + the fragment-builder; (3) wire into update / delete / show data; (4) Expr → parameterised SQL + implicit PK ORDER BY for limit; (5) schema-aware type-mismatch / = NULL flagging in the walker; (6) typing-surface matrix cells.
2. ADR-0027 and ADR-0028 — in either order after 0026. ADR-0027's WARNING severity and ADR-0028's index-flipping plan payoff both depend on 0026's show data … where.

Other open clusters (unchanged from handoff-15 §4):

• Snapshot / undo (U1/U2) — designed in ADR-0006, not built.
• Constraints (C3 — NOT NULL / UNIQUE / CHECK / DEFAULT). CHECK can now reuse ADR-0026's expression grammar — the ordering problem that paused the constraints discussion this session is resolved.
• m:n convenience (C4), modify relationship (C3a), table rename (C1).
• Friendly error layer (H1), seeding (SD1), CI (TT5), session log + Markdown export (V4), multi-line input (I1), tutorials (TU1).

Prioritisation is a user product decision — ask.

§4. How to take over

1. Read this file, then handoff-15 for the chain.
2. Read CLAUDE.md — the working-style rules. This session escalated every design fork to the user before drafting each ADR.
3. Read the three new ADRs — 0026, 0027, 0028 — including each one's ## Implementation notes. Then docs/simple-mode-limitations.md.
4. Read docs/requirements.md — reconciled this session.
5. Run cargo test — 1039 passing, 0 failing, 1 ignored.
6. Run cargo clippy --all-targets -- -D warnings — clean.
7. Start implementing ADR-0026 (§3). The three ADRs are design-complete; the forks are settled in the ADR text — build to them, don't re-open them.