docs(tt4,nfr): record Tier-4 + NFR verification (ADR-0008 A1, ADR-0057)

Document the regression-hardening work from this session:

- ADR-0008 Amendment 1 — Tier 4 realized: the portable-pty + vt100 harness,
  expectrl dropped, serial/fail-fast design, the four flows, sidebar-region
  reads, command pacing (issue #39), CI default-target (advances TT5).
- ADR-0057 (new) — NFR verification strategy: contrast + ΔE2000 gates
  (NFR-5/7), startup/RSS measured (NFR-1/3: release ~29 ms / ~10 MB),
  NFR-2 by architecture, NFR-4/6 reviewer note. Records the two shipped
  light-theme contrast defects this work caught and fixed.
- requirements.md: TT4 [~]->[x], TT5 [/] (only a Windows exec runner left),
  NFR-1/2/3/5/7 ->[x], NFR-4/6 ->[/], each with evidence.
- CHANGELOG.md (new): Keep a Changelog + SemVer, [Unreleased] + [0.2.0].
- README ADR index updated; handoff-76; the working plan.

Docs-only (CI gate skips via paths-ignore).

docs/adr/0008-testing-approach.md

@@ -146,4 +146,57 @@ and on a nightly schedule for any extended coverage.
 - CI cost is real but bounded: Tiers 1–3 are fast; Tier 4 is the
   only slow tier and is kept narrow.
 - Adding a feature implies adding tests at the appropriate tier
-  (or tiers); coverage is not retrofitted later.
+  (or tiers); coverage is not retrofitted later.
+
+## Amendment 1 — 2026-06-22: Tier 4 realized (TT4)
+
+Tier 4 was a specification only (no PTY deps, no tests) until this
+amendment. It is now implemented in `tests/e2e_pty.rs`, and the realized
+shape refines the original decision in three ways.
+
+**Tooling — `expectrl` dropped.** The decision named
+`portable-pty` + `expectrl` + `vt100`. We kept **`portable-pty`** (0.9, to
+spawn the real binary in a PTY at a fixed size) and **`vt100`** (0.16, to
+parse the output stream into an inspectable cell grid), both current and
+maintained. We **dropped `expectrl`**: it bundles its own PTY abstraction
+(which conflicts with `portable-pty`) and matches line-by-line, a poor fit
+for a full-screen TUI. A small hand-rolled `wait_for(predicate, timeout)`
+that polls the vt100 screen replaces it — fewer dependencies, and assertions
+read the actual rendered grid.
+
+**Harness shape.** Each test spawns the binary
+(`env!("CARGO_BIN_EXE_rdbms-playground")`) under a fresh PTY at **100×30**
+(the wide three-region layout, ADR-0046), with its **own temp `--data-dir`**
+so it never touches real projects or resume state, and `--theme dark` for
+deterministic styling. Tests run **serially** (one PTY + child at a time)
+via a poison-tolerant global lock, so timing stays predictable on the
+low-parallelism self-hosted runner. Waits are **tight and fail-fast** (3 s):
+a slow wait is a genuine hang, and a timeout panics with a full screen dump
+for debuggability.
+
+Two non-obvious robustness rules the harness encodes:
+- **Read table presence from the Tables *sidebar* region, not the whole
+  screen** — the Output panel echoes every command, so a table name typed
+  in a command would pollute a whole-screen match.
+- **Pace each command to completion before the next** (real-user / cast
+  cadence). A command submitted while the previous one's worker rebuild is
+  still in flight can be misread against a stale schema cache (issue #39,
+  discovered here — interactive use is unaffected).
+
+**The four flows** mirror this ADR's Tier-4 scope: (1) cold launch → first
+DDL → graceful quit (Ctrl-C); (2) create → quit → reopen via `--resume`,
+asserting the *column* (not just the table name) round-trips; (3) export →
+import into a fresh project → schema **and** data rebuilt; (4) `undo` after
+`DROP TABLE`, through the Y/N confirm modal.
+
+**CI.** The target runs by default in `cargo test`, so the existing Linux
+gate exercises it on every push — this **advances TT5** (Tier 4 now runs in
+CI on Linux). PTY-in-container was validated (openpty + child spawn work
+under the Docker runtime the Gitea runner uses); the first real CI run is
+the final confirmation. **Windows execution remains out of scope** (no
+Windows runner), and the original Tier-4 note about a *nightly broader
+coverage* schedule is **not** implemented — the focused four flows are the
+committed TT4 scope; broader coverage is deferred.
+
+**Piggybacked NFR measurement.** The same harness measures NFR-1 (startup
+to first frame) and NFR-3 (idle RSS, Linux) — see ADR-0057.

docs/adr/0057-nfr-verification-strategy.md

@@ -0,0 +1,122 @@
+# ADR-0057: Non-functional-requirement verification strategy
+
+## Status
+
+Accepted (2026-06-22).
+
+## Context
+
+The non-functional requirements (`requirements.md` NFR-1..7 — startup,
+input latency, memory, distinctive design, colour use, cross-platform
+parity, light/dark legibility) were quality bars that had **never been
+formally verified**, even though v0.2.0 ships public binaries. With users
+now pulling updates, we want each NFR either **gated by an automated test**
+(so a regression fails CI) or **measured-and-documented** with a recorded
+figure and a reviewer judgement — not left as an aspiration.
+
+The decision below was taken with the user: contrast is a hard gate;
+startup and memory are measured against generous bounds (not the literal
+target — a tight timing/RSS gate would flake on a shared runner); the
+qualitative bars are verified by argument and reviewer note.
+
+## Decision
+
+### NFR-5 / NFR-7 — colour contrast & legibility: **gated**
+
+Unit tests in `src/theme.rs` (Tier 1, run by the existing gate):
+
+- **`all_text_colours_meet_wcag_aa_contrast`** — every text-bearing
+  foreground (`fg`, `muted`, mode labels, `system`/`error`/`warning`,
+  `plan_efficient`, and all `tok_*`) must clear **WCAG-AA 4.5:1** against
+  `bg`, in **both** themes.
+- **`advanced_mode_border_meets_ui_contrast`** — the advanced-mode border
+  carries a mode-warning signal, so it meets the **3:1** non-text /
+  UI-component threshold. The plain `border` is decorative structural
+  chrome and is **deliberately exempt** (it sits at 2.20:1 dark / 1.82:1
+  light by design, so panel borders recede behind content — recorded here
+  rather than silently tolerated).
+- **`syntax_token_colours_are_perceptually_distinct`** — contrast against
+  the background is necessary but not sufficient: two token colours can
+  each clear 4.5:1 yet be hard to tell *apart* on a good screen. Every pair
+  of syntax-token classes that can share a line must clear **CIEDE2000
+  (ΔE2000) ≥ 15** (post-tuning minimum is ~18). The metric is itself
+  validated against the Sharma et al. reference vectors
+  (`delta_e_2000_matches_reference_vectors`).
+
+Computing the real ratios while writing these tests **uncovered two
+shipped defects** in the v0.2.0 light theme — `tok_string` at 4.42:1 and
+`tok_flag` at 3.15:1, both below the 4.5:1 the scheme promises — plus two
+dark-theme token pairs that were perceptually close despite distinct hex
+(`tok_type`↔`tok_keyword`, `tok_function`↔`tok_identifier`, ΔE2000 ~14).
+All four were fixed in the same change (commit `65eab71`); the gates now
+hold the palette to both bars permanently. A dev tool,
+`scripts/palette-preview.py`, renders the live palette with contrast +
+ΔE2000 for future palette work.
+
+### NFR-1 / NFR-3 — startup & memory: **measured, generously bounded**
+
+The Tier-4 PTY harness (ADR-0008 Amendment 1) measures both:
+
+- **`startup_to_first_frame_is_reasonable`** — spawn → first rendered frame.
+- **`idle_memory_footprint_is_reasonable`** — child `/proc/<pid>` VmRSS
+  after the app is idle (Linux only).
+
+These run against the **debug** binary, so they assert *generous* bounds
+(startup < 2000 ms, RSS < 150 MB) for **gross-regression detection**, not
+the literal NFR targets — a tight 500 ms / 50 MB gate on a debug binary
+under a loaded shared runner would flake. The **real release figures**
+(measured 2026-06-22, 5 trials each, this dev machine) are the documented
+verification:
+
+| NFR | Target | Release median | Margin |
+| --- | --- | --- | --- |
+| NFR-1 startup → first frame | < 500 ms | **~29 ms** | ~17× under |
+| NFR-3 idle RSS | < 50 MB | **~10 MB** | ~5× under |
+
+(Measurement granularity is the harness poll interval, ~20 ms — figures
+are "tens of ms", not sub-ms precise.) Per the user decision these are
+**not** wired as tight CI gates; the generous debug-bound tests are the
+ongoing regression signal.
+
+### NFR-2 — input responsiveness: **verified by architecture**
+
+"Long-running queries execute off the UI thread so the interface stays
+responsive." This is structural and already true: database work runs on a
+dedicated **worker thread** (ADR-0010), and terminal input is read on a
+**separate Tokio task** (`spawn_event_reader` in `src/runtime.rs`), so a
+running query cannot block keystroke handling or rendering. There is no
+automated keystroke-latency test — a deterministic sub-16 ms measurement
+in a PTY harness would be flaky and low-value — so NFR-2 is verified by
+this architectural argument rather than a gate.
+
+### NFR-4 / NFR-6 — distinctive design & cross-platform parity: **reviewer note**
+
+Qualitative bars. **NFR-4** (deliberate, identifiable palette/layout using
+box-drawing) is satisfied by the bespoke two-theme palette, the
+three-region framed layout, and the annotated plan/relationship rendering —
+reviewer judgement, not automatable. **NFR-6** is partly evidenced by the
+CI matrix (Linux + macOS **execute** the suite; Windows is **build-only**,
+no runner) and is otherwise a reviewer judgement; one documented divergence:
+on terminals/multiplexers without true-colour passthrough (e.g. a tmux
+session missing `Tc`/`RGB`), the 24-bit palette is quantised to the
+256-colour cube and near hues can collide — a terminal-capability issue,
+not a palette one.
+
+## Consequences
+
+- Contrast and perceptual distinctness are now **permanently gated** — the
+  palette cannot regress below WCAG-AA or into look-alike token colours
+  without failing the build.
+- Startup and memory have **recorded figures** and a generous
+  gross-regression test; the literal targets are met with large margins.
+- The qualitative and architectural NFRs are **documented with evidence**
+  rather than asserted.
+- A latent behaviour found during this work — fast DDL→insert misparsing
+  against a stale schema cache — is tracked as **issue #39** (deferred; no
+  interactive-user impact).
+
+## Requirements bookkeeping
+
+NFR-1, NFR-3, NFR-5, NFR-7 → `[x]` (gated test and/or measured with
+evidence). NFR-2 → `[x]` (architectural). NFR-4, NFR-6 → `[/]` (reviewer
+note; not fully automatable).