rdbms-playground/docs/plans/20260622-tt4-nfr-changelog.md

# Plan — TT4 (Tier-4 PTY tests) + NFR verification + CHANGELOG

Status: **approved 2026-06-22**, implementation pending. Supersedes the
transient harness plan-mode copy. This is the persistent, version-controlled
plan per project convention (`docs/plans/`).

## Context

RDBMS Playground now ships public binaries (v0.2.0 on crates.io, plus
Scoop/Homebrew/winget). With real users pulling updates, the priority is
**regression protection before the next release**. Three tracked gaps are taken
up together:

- **TT4** (`requirements.md`, ADR-0008 Tier 4): the four critical end-to-end
  flows are specified but **no PTY harness exists** — no deps, no tests. Tiers
  1–3 never exercise the *real built binary* through a terminal.
- **NFR-1..7**: quality bars (startup, latency, memory, contrast, distinctive
  design, parity) that were **never formally verified** despite shipping.
- **CHANGELOG**: none exists; useful now that releases are public (and lets the
  CI `winget` job pass `--release-notes-url` later).

Baseline (Phase 1): `cargo test` = **2509 passed / 0 failed / 1 ignored**;
clippy + fmt clean. This is the number Phase 5 verifies against (new tests add
to it; nothing may regress).

User decisions (Phase 3):
- **TT4 in CI:** own `e2e_pty` test target, runs by default in `cargo test`
  (so the Linux gate exercises it every push). **Tight, fail-fast timeouts** —
  the runner is self-hosted, low-parallelism, low expected flakiness (so a
  failure surfaces fast rather than hanging on a generous timeout).
- **NFR:** WCAG contrast = hard gated test; startup + idle-memory = measured via
  the PTY harness against *generous* bounds + numbers recorded; NFR-2/4/6 =
  verify-by-argument + reviewer note. Each requirement → `[x]`/`[/]` with
  evidence.
- **CHANGELOG:** Keep a Changelog + SemVer; `[Unreleased]` + a single
  consolidated `[0.2.0]` only (0.1.0 treated as pre-history).

---

## Workstream 1 — TT4: Tier-4 PTY harness + 4 flows

### Tooling (refines ADR-0008's stated `portable-pty`+`expectrl`+`vt100`)
- **`portable-pty`** (wezterm, actively maintained) — spawn the real binary in a
  PTY with a fixed window size.
- **`vt100`** — parse the PTY output stream into an inspectable cell grid.
- **Drop `expectrl`** — it bundles its *own* PTY abstraction (conflicts with
  portable-pty) and is line-oriented, a poor fit for a full-screen TUI. Replace
  it with a small hand-rolled `wait_for(predicate, timeout)` polling the vt100
  screen. This deviation is recorded in the ADR-0008 amendment.
- **Checkpoint at implementation:** verify `vt100` is still maintained/current
  (global currency rule). If stale, evaluate `avt` as the screen parser before
  committing the dep. `cargo add` picks latest; pin sensibly.

### Harness (`tests/e2e_pty.rs` — new `[[test]]` target)
A `support` module providing:
- `struct PtyApp` — opens a PTY (e.g. **100×30**, the wide three-region
  layout), spawns `env!("CARGO_BIN_EXE_rdbms-playground")` with a **per-test
  temp `--data-dir`** (`tempfile::TempDir`), `--theme dark`, `TERM=xterm-256color`;
  a reader thread feeds bytes into a `vt100::Parser`.
- `send(bytes)` (raw; `\r` = Enter, `\x03` = Ctrl-C), `send_line(s)` =
  `s` + `\r`.
- `wait_for(&str, Duration)` — poll the vt100 screen text until the substring
  appears or the (tight, ~**3 s**) timeout fires; on timeout **panic with a full
  screen dump** (fail-fast + debuggable). A `screen_text()` helper for assertions.
- `quit()` — `send("\x03")`, wait for child exit, assert success.
- Run **serially** (`serial_test` dep, or a shared `Mutex`/single-threaded
  target) — PTYs + temp dirs shouldn't race; also keeps timing stable.
- **Instrument** with `eprintln!`/screen dumps on every wait so a CI failure is
  diagnosable from logs (per the project's logging discipline).

### The four flows (one `#[test]` each, mirroring ADR-0008 §Tier-4)
1. **Cold launch → DDL → quit.** Launch fresh; `wait_for("SIMPLE")` +
   `wait_for("(none yet)")`; `send_line("create table Customers with pk
   id(serial)")`; `wait_for("Customers")` in the Tables panel; `quit()`.
2. **Save → restart → reopen.** Launch project path P under the temp data-dir;
   create a table; `quit()` (autosave already persisted per-command); relaunch
   **same P**; `wait_for("Customers")` — schema restored from text/rebuild.
3. **Export → import → rebuild.** Project A: create table + insert a row;
   `send_line("export A.zip")` (explicit path under the temp dir);
   `wait_for` export-success note; `quit()`. Fresh project B:
   `send_line("import <path>/A.zip")`; `wait_for` import note (rebuild auto-runs
   on missing `.db`); assert the table + row are present (`show data` /
   Tables panel).
4. **Undo after DROP.** Create table; `send_line("drop table Customers")`;
   confirm gone; `send_line("undo")`; **`wait_for("Restore that earlier
   state?")`** (the real modal); `send("y")`; `wait_for("Customers")` restored.

### CI
No workflow edit needed for execution: `e2e_pty` is a default target, so the
existing `gate` job's `cargo test --no-fail-fast` runs it on the Linux
container. **Validate locally first** that a PTY opens inside the
`rdbms-playground-ci` image (container `/dev/ptmx`); if not, add `--init`/pts
mount notes to the ADR. Advances **TT5** (Tier-4-in-CI on Linux); Windows
execution runner stays out of scope (no runner).

---

## Workstream 2 — NFR verification

### Gated: WCAG contrast (NFR-5, NFR-7) — `src/theme.rs` `#[cfg(test)]`
- Add a `relative_luminance(Color) -> f64` + `contrast_ratio(a,b) -> f64`
  helper (WCAG 2.x sRGB formula) in the test module; a `match Color::Rgb` channel
  extractor (panics on non-RGB — also a guard against a future named-colour
  regression).
- For **both** `Theme::light()` and `Theme::dark()`, assert **≥ 4.5:1** for
  normal-text foregrounds on `bg`: `fg`, `error`, `warning`, `system`,
  `plan_efficient`, `mode_simple`, `mode_advanced`, and the info-carrying syntax
  tokens (`tok_keyword/identifier/type/number/string/flag/function/error`).
- **`muted`/`tok_punct`** (deliberately dim secondary text) and **borders**
  (`border`/`border_advanced`, non-text UI): assert the WCAG **non-text 3:1**
  threshold, with a comment citing the WCAG large-text/non-text allowance. If
  any *fails even 3:1*, that's a real finding → surface to the user, don't
  silently relax. (Supersedes the existing inequality-only theme tests.)
- This runs in the existing gate — permanent regression protection on the palette.

### Measured + documented: startup (NFR-1) + idle memory (NFR-3)
Two measurement tests in `e2e_pty.rs`:
- **Startup:** time from spawn to `wait_for("SIMPLE")` (first rendered frame);
  assert a **generous** bound (e.g. < 1500 ms locally) and `eprintln!` the actual.
- **Idle memory:** after the app is idle, read the child's `/proc/<pid>/status`
  `VmRSS` (Linux); assert a generous bound and print actual. (Linux-gated via
  `#[cfg(target_os = "linux")]`.)
The point is gross-regression detection, not a tight SLA gate (user decision).

### Verify-by-argument + reviewer note (NFR-2, NFR-4, NFR-6)
- **NFR-2** (input off-thread): already architecturally true — DB runs on the
  worker thread (ADR-0010) and input on a separate Tokio task (confirmed in
  `runtime.rs`). Record the evidence; optionally a test that a query doesn't
  block a subsequent keystroke render.
- **NFR-4** (distinctive design) / **NFR-6** (cross-platform parity): qualitative
  / partly-CI. Written reviewer verification (DA-hat) in the NFR verification doc;
  parity partly evidenced by the CI matrix (Linux+macOS execute, Windows builds).

### Requirements bookkeeping
Move NFR-5/7 → `[x]` (gated test), NFR-1/3 → `[x]` (measured + bounded test +
recorded numbers), NFR-2 → `[x]` (architectural evidence), NFR-4/6 → `[/]` with
the reviewer note (honest: not fully automatable). Each with a commit/test ref.

---

## Workstream 3 — CHANGELOG

- New **`CHANGELOG.md`** at repo root, **Keep a Changelog** + SemVer.
- `[Unreleased]` (empty/seeded) + one consolidated **`[0.2.0] - <release date>`**
  with Added/Changed/Fixed of the notable user-facing changes (install methods,
  packaging, `--version`/`version`, seed improvements, hint feature, readline
  keys, cross-mode history) mined from ADRs 0053–0056 + handoffs 73–75. 0.1.0 =
  pre-history (a one-line note).
- Optional follow-up (flag, don't auto-do): wire `--release-notes-url` into the
  CI `winget`/release path — out of scope unless you want it now.

---

## Docs / ADR updates (project discipline)

- **Amend ADR-0008** (Tier-4 section): record the realized tooling
  (`portable-pty` + `vt100` + hand-rolled `wait_for`, `expectrl` dropped),
  serial execution, tight-timeout/fail-fast stance, the default-target CI wiring,
  and the four implemented flows. Update `docs/adr/README.md` in the same edit.
- **New ADR-0057 — NFR verification strategy** (next free number; assigned at
  merge per ADR-0000): the contrast-gate + thresholds (incl. the 3:1
  muted/border allowance), the measured-not-tightly-gated stance for
  startup/memory, and the verify-by-argument treatment of NFR-2/4/6. Add a
  short **NFR verification record** (the measured numbers + reviewer notes) —
  either in the ADR or a `docs/` companion. Update the README index.
- Update `docs/requirements.md`: TT4 `[~]`→`[x]`, TT5 `[/]` note (Tier-4 now in
  Linux CI; Windows-exec still pending), NFR rows as above.
- A handoff note (next sequence number) per project convention.

---

## Verification (Phase 5)

1. `cargo test` — full suite green; new e2e_pty + contrast tests pass; **2509 +
   new, 0 failed, ≤1 ignored**; no regressions vs baseline.
2. `cargo clippy --all-targets -- -D warnings` + `cargo fmt --check` clean.
3. Run `e2e_pty` repeatedly (e.g. 5–10×) locally to confirm non-flaky under the
   tight timeouts before relying on the gate.
4. Confirm a PTY opens inside the CI image (or document the fix).
5. DA-hat pass over each workstream + the NFR reviewer judgements, written down.
6. `cargo sweep` at the milestone (CLAUDE.md build hygiene).

## Risks / checkpoints
- **vt100 currency** — verify before adding; fall back to `avt` if stale.
- **PTY-in-container** — validate early; the whole TT4 CI value depends on it.
- **muted/border contrast** — may fail even 3:1; if so it's a finding to escalate,
  not silently relax (could mean a small palette tweak — touches a decided area,
  so escalate).
- **Commits** — confirm each message; no AI attribution; append-only; never push.