rdbms-playground/docs/handoff/20260519-handoff-18.md

# Session handoff — 2026-05-19 (18)

Eighteenth handover. A long **implementation run** that built
two ADRs end to end:

- **ADR-0026 (complex WHERE expressions)** — steps 1–4 + 6;
  see handoff-17 for its detail.
- **ADR-0027 (input-field validity indicator)** — all six
  build-order steps, **with ADR-0026's deferred step 5 (the
  §7 expression flagging) folded in** as the WARNING
  severity's first triggers, exactly as the user directed.

**Headline: the validity indicator works.** A debounced
`[ERR]` / `[WRN]` marker at the input row's right edge tells a
learner — before they press Enter — whether the command would
run. `S6` and `C5a` are both satisfied; nothing from ADRs
0026/0027 is left unimplemented.

## State at handoff

**Branch:** `main`. Working tree clean. **12 commits** since
handoff-16 (`ac41938`), all local — push asynchronously, not
blocking. handoff-17 (`dfd3c51`) is mid-chain; it documents
the ADR-0026 landing and is superseded by this file.

```
151ed08 hint: show the matching usage template for multi-form commands
a326849 ADR-0027: existing-cases sweep + docs (step F)
9e10997 runtime: debounce the validity indicator (ADR-0027 step E)
1a9d950 ui: validity indicator rendering + warning theme colour (ADR-0027 step D)
73c7470 walker: expression WARNING diagnostics (ADR-0027 step C, folds ADR-0026 §7)
827b47f walker: schema-existence ERROR diagnostics (ADR-0027 step B)
e22f933 walker: diagnostics-severity model + input_verdict (ADR-0027 step A)
dfd3c51 chore: handoff 17 — ADR-0026 complex WHERE expressions implemented
a50c6cd WHERE expressions: matrix cells + predicate_tail grammar fix (ADR-0026 step 6)
f75f71b WHERE expressions: wire into update/delete/show data + SQL gen (ADR-0026 steps 3-4)
59e6a54 grammar: WHERE-expression fragment + Expr AST + build_expr (ADR-0026 step 2)
f0b2043 walker: add Subgrammar node + recursion-depth cap (ADR-0026 step 1)
```

**Tests:** **1100 passing, 0 failing, 1 ignored** (`cargo
test` — up from 1039 at handoff-16). The ignored test is the
long-standing `` ```ignore `` doc-test in
`src/friendly/mod.rs`. Typing-surface matrix: **161 cells**.

**Clippy:** clean (`cargo clippy --all-targets -- -D
warnings`, nursery group).

## §1. ADR-0026 — recap (detail in handoff-17)

Complex WHERE expressions work end to end: `update` /
`delete` / `show data` take a full boolean expression
(`AND`/`OR`/`NOT`, the six comparisons, `LIKE`/`IN`/`BETWEEN`/
`IS [NOT] NULL`, parentheses); it compiles to parameterised
SQL; `show data` gained `where` and `limit`. The §3 builder
realization (option 1) and the as-built deviations are in
ADR-0026's "As-built notes". **Step 5 (the §7 diagnostic
flagging) was deferred at handoff-17 and is now done — see
§2.**

## §2. ADR-0027 — the validity indicator

Six steps, one commit each (`e22f933`..`a326849`):

- **A — diagnostics model.** `Severity` (Error/Warning,
  ordered) and `Diagnostic { severity, span, message }` in
  `walker::outcome`; a `diagnostics` field on `WalkResult`.
  `walker::input_verdict(source, schema)` is the indicator's
  entry point — the highest severity across the parse
  outcome and the diagnostics, or `None` for clean / empty
  input.
- **B — schema-existence ERRORs.** `MatchedKind::Ident` now
  carries its `IdentSource`. A post-walk pass over a
  structural `Match` flags an unknown table (`Tables` ident)
  or unknown column (`Columns` ident, scoped to the table in
  scope) as an ERROR — *new behaviour*: such names used to
  parse cleanly and fail only at execution.
- **C — expression WARNINGs (ADR-0026 §7 folded in).** A
  type-mismatched comparison, or `= NULL` / `!= NULL`, in a
  WHERE expression yields a WARNING — computed post-walk from
  the built `Command`'s `Expr` against the table's column
  types. The command still parses and runs (§7 permissive
  posture unchanged).
- **D — rendering.** `[ERR]` / `[WRN]` at the input row's
  right edge; new amber `theme.warning`. The rightmost six
  columns are reserved unconditionally so the typed command
  never shifts when the indicator appears.
- **E — debounce.** The runtime event loop time-boxes `recv`
  while a recompute is owed: a keystroke hides the indicator
  and arms a 1 s window; once typing pauses that long the
  verdict is computed and shown. `update()` stays pure.
- **F — sweep + docs.** `input_verdict` tests confirm the
  schema check fires across the identifier-taking commands.

## §2a. Post-ADR-0027 — a manual-testing pass

After ADR-0027 landed, a round of manual testing surfaced
three things; all are resolved.

- **Bug, fixed (`151ed08`).** A parse error in `add index …`
  showed the `add column` usage. `add` / `drop` are
  multi-form commands and both the ambient hint and the
  submit-time usage block picked the *first* form
  unconditionally. New `grammar::usage_key_for_input`
  disambiguates by the form word after the entry keyword;
  the hint shows the committed form, `render_usage_block`
  too (bare `add` / `drop` still shows the whole family).
- **`add index` syntax — reviewed, deliberately kept.** The
  inconsistency is real: `add column [to] [table] <T>: <col>
  (<type>)` vs `add index [as <name>] on <T> (<cols>)`. It
  was weighed and **left as-is** — `add index … on <T>
  (<cols>)` is intentionally SQL-idiomatic
  (`CREATE INDEX … ON t (cols)`), the colon shape was built
  for "one column *with a type*" and an index has neither.
  A future agent should **not** re-flag this as a bug; if
  the owner later wants the entity-command separators
  unified, that is a deliberate ADR-0025 amendment / design
  pass, not a drive-by fix.
- **No index parameters / no `unique` — by design.** ADR-0025
  scoped `add index` to plain non-unique indexes; there is
  no `unique`-index syntax and no constraint syntax at all
  (`NOT NULL` / `UNIQUE` / `CHECK` / `DEFAULT` are the
  pending `C3`). ADR-0018's `unique` handling only
  *detects + displays* an existing constraint — nothing
  creates one. Not a gap in the help; the help is accurate.

## §3. Architectural delta (vs. handoff-17)

### Diagnostics

- `walker::outcome::{Severity, Diagnostic}`;
  `WalkResult::diagnostics: Vec<Diagnostic>` (re-exported as
  `walker::{Severity, Diagnostic}`).
- `walker::input_verdict(source, schema) -> Option<Severity>`
  — the indicator entry point.
- `MatchedKind::Ident` gained `source: IdentSource`.
- Diagnostics are computed **post-walk** in `walk()` —
  `schema_existence_diagnostics` over the matched path,
  `expr_warnings` over the built `Expr` — not emitted
  incrementally (keeps them off the speculative-rollback
  paths). See ADR-0027 "As-built notes".

### App / runtime / ui

- `App::input_indicator: Option<Severity>` — the indicator's
  visible state; `App::input_validity_verdict()` — the pure
  verdict (simple mode only; advanced mode is raw SQL).
- `runtime::run` event loop: a `tokio::time::timeout`-based
  debounce (`INDICATOR_DEBOUNCE`, 1 s).
- `ui::render_input_panel` reserves a fixed six-column right
  strip and renders the `[ERR]`/`[WRN]` label.
- `theme.warning` — amber, light + dark.

### Catalog

- New `diagnostic:` section — `unknown_table`,
  `unknown_column`, `type_mismatch`, `eq_null`.

## §4. Known follow-ups (none blocking)

- **Diagnostic highlight / hint wiring.** ADR-0027 §2 says
  highlighting and the hint panel "read the individual
  diagnostics". The indicator and the model ship; routing a
  diagnostic's span into the per-byte highlight overlay, and
  its message into the hint panel beyond the existing
  parse-error path, is not yet done — the build order did
  not enumerate it as a step. WARNING spans are currently
  coarse (the whole WHERE clause) because the `Expr` AST
  carries no source spans; precise per-literal spans would
  come with that wiring. Recorded in ADR-0027 "As-built
  notes".
- **Debounce timing is integration-level, not unit-tested**
  — it is async event-loop glue. The pure pieces
  (`input_verdict`, `input_validity_verdict`, the indicator
  rendering) are covered.
- **LIKE-on-a-numeric-column** is not flagged — `LIKE` is a
  text-pattern test and "mismatch" there is fuzzier; a
  future WARNING-model extension. Compare / Between / In
  type-mismatch and `= NULL` are flagged.

## §5. What's next

- **ADR-0028 — query plans (`explain`).** The last of the
  handoff-16 design trio, still unimplemented. `show data …
  where` (now real) is the filtered query whose plan flips
  between a full scan and an index search; the diagnostics
  model and the `OutputLine` span-styling ADR-0028 describes
  are both now easier to reach.
- The §4 follow-ups, if the user wants the diagnostic
  highlight/hint detail wired now rather than later.

Other open clusters are unchanged from handoff-16/17 §3
(snapshot/undo `U`-series; constraints `C3` — `CHECK` can
reuse ADR-0026's expression grammar; `C4` m:n; `C3a`; `C1`
table rename; `H1`; `SD1`; `TT5` CI; `V4`; `I1`; `TU1`).
Prioritisation is a user product decision — ask.

## §6. How to take over

1. **Read this file, then handoff-17** (ADR-0026 detail),
   then handoff-16 (the design trio).
2. **Read `CLAUDE.md`** — working-style rules.
3. **Read `docs/adr/0027-input-validity-indicator.md`** —
   especially its "As-built notes" (post-walk diagnostics,
   the pre-rendered message, the `timeout` debounce, coarse
   spans, the deferred highlight/hint wiring).
4. **Run `cargo test`** — 1100 passing, 0 failing, 1 ignored.
5. **Run `cargo clippy --all-targets -- -D warnings`** — clean.
6. **Pick the next work from §5** — ADR-0028 is the natural
   pick; prioritisation is a user decision, so ask.

### Note on the typing-surface matrix

`tests/typing_surface/` is **161 cells**. The validity
indicator is *not* matrix-covered — the matrix harness
(`assess`) drives parse / hint / completion, not the
debounced indicator; `input_verdict` is covered directly by
walker unit tests instead. After any grammar/walker change
the matrix-snapshot discipline from handoff-17 still applies.