docs: ADR-0042 — continue H1a parse-error pedagogy on the grammar tree

ADR-0020/0021 specified a chumsky-based H1a; ADR-0024 replaced chumsky
with the scannerless walker, leaving both obsolete. Mark them superseded
(kept as institutional memory) and add ADR-0042, which restates H1a
against the architecture as built.

ADR-0042 records that H1a is substantially shipped already — per-command
usage block, available-commands fallback, source-derived ident slot
labels, curated parse.custom.* near-miss messages, and schema-aware
[ERR] diagnostics — and defines the remaining work: a verified
per-command near-miss matrix (the definition of done), friendlier
literal expectation labels that add role context while keeping the
exact literal visible, and advanced-mode SQL parse parity (RETURNING
scope, CROSS JOIN ON, INSERT…SELECT count), kept distinct from
ADR-0019 §OOS-2 engine-error sanitisation.

- docs/adr/0020,0021: superseded notes + README entries
- docs/adr/0042: new ADR
- docs/adr/README.md: index upkeep (ADR-0000 rule)
This commit is contained in:
claude@clouddev1
2026-06-03 14:05:09 +00:00
parent a8d0138d8b
commit 0e6f767848
4 changed files with 355 additions and 4 deletions
@@ -2,7 +2,29 @@
## Status
Accepted.
**Superseded by ADR-0024** (2026-05-14). Accepted then superseded
without being implemented.
> **Superseding note (2026-06-03).** This ADR was never built. It
> specifies a `chumsky`-over-tokens architecture — a separate lexer
> producing `Vec<Token>`, a `define_keywords!` macro, and chumsky
> grammar combinators consuming `&[Token]`. ADR-0024 (unified grammar
> tree) instead adopted a **scannerless hand-rolled walker** that
> operates directly on source bytes, and **removed chumsky from the
> project entirely** (it is no longer a dependency). The lexer,
> `keyword.rs`, and the token model described below do not exist.
>
> What this ADR got *right* survives in ADR-0024: the
> expected-set aggregation it wanted (one branch's report no longer
> swallowing the others) is delivered by the walker's structural
> `expected` derivation, and the I3 (completion) / I4 (highlighting)
> hooks it anticipated are served by the same walker. Read ADR-0024
> for the architecture as built; this ADR remains as institutional
> memory of the path not taken and the reasoning that led there.
---
*Original status (historical):* Accepted.
Amends ADR-0001 (language and TUI framework) by adding a
tokenization layer between the source string and the chumsky