rdbms-playground/docs/handoff/20260622-handoff-76.md

Session handoff — 2026-06-22 (76)

Continues from handoff-75 (D3 package managers). This session took up the regression-hardening trio identified as "what's next" now that public binaries ship: TT4 (Tier-4 PTY tests), NFR verification, and a CHANGELOG — plus a real palette accessibility fix the work uncovered.

§1. State

Branch main. Three commits this session:

• 65eab71 fix(theme) — WCAG-AA palette fix + contrast/ΔE2000 gates + scripts/palette-preview.py.
• fd63de3 test(tt4) — Tier-4 PTY end-to-end suite (tests/e2e_pty.rs).
• (pending) a docs commit — ADR-0008 Amendment 1, ADR-0057, README index, requirements.md, CHANGELOG.md, this handoff, and the plan doc docs/plans/20260622-tt4-nfr-changelog.md. (Propose + confirm before committing; not yet committed at time of writing.)

Test baseline: 2519 passed / 0 failed / 1 ignored (was 2509; +4 theme gates, +6 e2e_pty). clippy --all-targets -D warnings + fmt --check clean. Full suite verified green 3× under parallel load.

§2. What shipped

Palette accessibility (ADR-0057, commit 65eab71). Computing real WCAG ratios while writing the gate found two shipped defects in v0.2.0's light theme — tok_string (4.42:1) and tok_flag (3.15:1), below the 4.5:1 the scheme promises — and two dark token pairs that were perceptually close despite distinct hex. All four fixed (only theme.rs colours changed, 4 values). New gated tests in src/theme.rs:

• all_text_colours_meet_wcag_aa_contrast (≥4.5:1, both themes),
• advanced_mode_border_meets_ui_contrast (≥3:1; plain border exempt),
• delta_e_2000_matches_reference_vectors (CIEDE2000 validated vs Sharma data),
• syntax_token_colours_are_perceptually_distinct (ΔE2000 ≥15). Dev tool scripts/palette-preview.py renders the live palette (truecolor swatch + contrast + ΔE2000), supports theme:key=HEX overrides for previewing changes.

TT4 — Tier-4 PTY tests (ADR-0008 Amendment 1, commit fd63de3). tests/e2e_pty.rs drives the real built binary in a pseudo-terminal: portable-pty 0.9 + vt100 0.16 (expectrl dropped — conflicting PTY layer; replaced by a hand-rolled wait_for on the vt100 grid). 100×30, temp --data-dir, serial, tight 3 s fail-fast waits. The four ADR-0008 flows all green. Runs by default in cargo test → the Linux gate now exercises Tier 4 (advances TT5). PTY-in-container validated (openpty+spawn under Docker).

• Gotchas baked into the harness: read table presence from the Tables sidebar region (the Output panel echoes commands, polluting whole-screen matches); pace commands to completion (a command sent mid-rebuild misparses — issue #39); simple-mode insert needs the values keyword and a single-value insert needs add column (a 2nd col in with pk … makes a compound PK).

NFR verification (ADR-0057). All seven NFRs formally verified:

• NFR-1/3 measured via the PTY harness — release figures ~29 ms startup / ~10 MB idle RSS (well under 500 ms / 50 MB). Harness tests gate generous debug-binary bounds for gross-regression detection (tight gates declined as flaky — user decision).
• NFR-5/7 gated (the contrast/ΔE2000 tests above).
• NFR-2 by architecture (worker thread ADR-0010 + separate input task).
• NFR-4/6 reviewer note ([/]).

CHANGELOG.md — Keep a Changelog + SemVer; [Unreleased] + [0.2.0] (0.1.0 = pre-history). v0.2.0 tag = bd5be5e; the palette fix + package managers + TT4 are post-tag → Unreleased.

§3. Decisions taken with the user

• Palette: fix the two light contrast bugs and the two dark near-duplicates (4 hex changes, approved after a rendered preview).
• Borders <3:1 → accept + document (decorative chrome).
• Work directly on main; ADR-0057 numbered now (not draft).
• NFR perf: measured + generously bounded, not tightly CI-gated.
• CHANGELOG depth: 0.2.0 + Unreleased only.
• Schema-cache finding → file a Gitea issue, defer the fix (see §4).

§4. Open / follow-ups

• Issue #39 (filed this session): simple-mode Form-B insert (insert into T values (…)) submitted faster than the post-DDL schema-cache refresh validates against stale schema and is misparsed as SQL. No interactive-user impact (cast driver + tests pace); deferred fix. Repro + diagnosis in the issue.
• TT5 remaining: only a Windows execution runner now (macOS + Tier-4 gaps closed this session). First real CI run is the final confirmation that the PTY tests pass in the Gitea container (validated locally; very low risk).
• Untouched larger items from the "what's next" survey: hint/help issues #36/#37/#38; the big features (V4 session journal, TU1 tutorial). The CHANGELOG can later feed --release-notes-url into the CI winget job (handoff-75 §6).

§5. Process pins

• Commits user-confirmed, no AI attribution, append-only, push is the user's step.
• /runda + DA pass was run on both the plan and the implementation (it caught the two light-theme contrast bugs and the #39 schema-cache behaviour — both before finalizing).
• Consider a cargo sweep at this milestone (release build added ~ a GB).

§6. Post-finalization (same session)

• macOS fully verified. A native cargo test on macOS was fully green — 1813 lib + 5 e2e_pty + 500 integration + 200 typing. This confirms Tier 4 on macOS (the 4 flows + startup; the Linux-only RSS probe is #[cfg]-skipped, hence 5 not 6). Closes the runda "Tier-4 unverified on macOS" item.
• fix(tt4) 1ffe11c — the macOS run surfaced a method pid is never used warning: rss_kib is Linux-only and was pid's only caller, so off Linux it was dead code. The Linux clippy gate can't catch this (pid is used on Linux). Read child.process_id() inline; deleted the helper.
• Cross-platform crate downloads off-target are normal — cargo fetches the whole locked graph (Windows ConPTY bindings, Unix libc/nix from portable-pty) but only compiles host-target crates; nothing off-target is actually built.
• TT5 / Windows decision (2026-06-22): a permanent Windows CI runner stays open, no promises — standing one up is more involved than the Linux/macOS runners already in use. Interim: Windows builds ship every release (D1/D2) and are verified by running the suite on Windows by hand periodically — the same builds Windows users get, manually verified rather than per-push. The TT5 note was reworded to say this plainly and welcomingly; it stays [/] by deliberate scope. (Virtualization options explored for a future runner are not recorded here — they hinge on host specifics rather than project constraints.)