vdm/gui/docs/pkg-qa-requests-m1.md

GUI → PKG/QA requests (M1)

Filed by lane GUI. These touch PKG/QA-owned files (tools/bootstrap.sh, the CI jobs, docs/agents/AGENT-PKG-QA.md) and the root README.md, so GUI is not making the edits — CLAUDE.md §1. Everything below is apply-ready.

---

R1 — libqt6svg6-dev is not a real package on 26.04 (blocks the GUI DoD)

apt-cache policy libqt6svg6-dev on a clean Ubuntu 26.04 box gives Candidate: (none). The Qt 6 SVG dev package in the 26.04 archive is qt6-svg-dev (currently 6.10.2-2). libqt6svg6 (no -dev) exists as the runtime lib but carries no headers or CMake config, so find_package(Qt6 COMPONENTS Svg) fails without qt6-svg-dev.

I checked the other 38 apt names in bootstrap.sh against apt-cache policy on 26.04 — libqt6svg6-dev is the only one with no candidate. Everything else resolves.

Why it passed here anyway: this dev box already has qt6-svg-dev installed (it came in with a qt6-base-dev recommends chain at some point), so pkg-config --exists Qt6Svg succeeds and --check is green. On a clean VM the apt-get install step aborts before --check ever runs.

Fix — three files, same one-line change

tools/bootstrap.sh (in APT_GUI, ~line 87):

 APT_GUI=(
     qt6-base-dev
     qt6-tools-dev
     qt6-tools-dev-tools        # lrelease/lupdate for i18n
-    libqt6svg6-dev             # GUI: SVG icon rendering
+    qt6-svg-dev                # GUI: SVG icon rendering (was libqt6svg6-dev — no such
+                               #      package on 26.04; this is the one with headers +
+                               #      the Qt6SvgConfig.cmake find_package needs)
 )

docs/agents/AGENT-PKG-QA.md (~line 17):

-   `libqt6svg6-dev`, `libsecret-1-dev`, `nodejs`/`npm` and (optionally) `clang` are
+   `qt6-svg-dev`, `libsecret-1-dev`, `nodejs`/`npm` and (optionally) `clang` are

README.md (toolchain table, ~line 106):

 sudo apt update && sudo apt install -y \
-  libqt6svg6-dev \    # GUI: SVG icon rendering
+  qt6-svg-dev \       # GUI: SVG icon rendering
   libsecret-1-dev \   # DAEMON: Secret Service for site logins

---

R2 — --check verifies the outcome, not the thing that can break

--check today runs the "verify toolchain" block: command -v for the binaries, pkg-config --exists for the dev libs (Qt6Core, Qt6Widgets, Qt6Svg, libcurl, sqlite3, libssl, libsecret-1, libavformat), plus the cmake/g++/node version floors. Every one of those checks a result on a box that already installed everything. None of them touch the apt package names in APT_*, which is the only part of the script that can be wrong on a clean machine — as R1 just demonstrated. So --check reported green for a script that fails apt-get install on its target OS.

Proposed fix — make --check validate the install list it would actually run

Add this to the verify block (runs in both modes; in --check mode it is the point of the exercise). It needs neither root nor network — apt-cache policy reads the local package lists that apt-get update already populated:

# Every apt name this script would install must be a real, installable package on THIS
# release. This is the check that would have caught libqt6svg6-dev before the VM did.
log "validating apt package names (${#PKGS[@]})"
missing_pkgs=()
for pkg in "${PKGS[@]}"; do
    # `apt-cache policy <pkg>` prints "Candidate: (none)" for a name with no installable
    # version, and exits 0 either way — so grep the candidate line, don't trust $?.
    cand="$(apt-cache policy "$pkg" 2>/dev/null | sed -n 's/^  Candidate: //p')"
    if [[ -z "$cand" || "$cand" == "(none)" ]]; then
        printf '  \033[31m✗\033[0m %-20s no installable candidate on this release\n' "$pkg"
        missing_pkgs+=("$pkg")
        fail=1
    fi
done
if (( ${#missing_pkgs[@]} == 0 )); then
    printf '  \033[32m✓\033[0m %-20s all %d resolve\n' "apt names" "${#PKGS[@]}"
fi

Notes for whoever applies it:

• PKGS is already assembled above the CHECK_ONLY branch, and it already respects --with-clang / --with-packaging, so the loop covers exactly what would be installed.
• Belt-and-braces alternative: apt-get install -s --no-install-recommends "${PKGS[@]}" (-s = simulate, no root) also catches an un-satisfiable dependency, not just a missing name. Downside: it needs the apt lists reasonably fresh and is noisier to parse. apt-cache policy is enough to catch the whole class of bug in R1; pick whichever you want to own.
• CI: the bootstrap-script job already runs ./tools/bootstrap.sh --check after the install. With this change that job would have gone red on libqt6svg6-dev at the --check step on the 24.04 runner even before the install step failed, because the name has no candidate there either.

---

R3 (smaller) — a GUI CI job

There is no job that builds velox-gui on its own or runs its offscreen smoke. The build matrix will pick up the target and the gui_downloadtablemodel ctest once gui/ merges, but the GUI DoD items — 10k rows at 60 fps, flat memory over 10 min, --slow/--flaky/--drop-connection recovery, grep -r 'curl\|pwrite\|sqlite' gui/ empty, RTL layout — need somewhere to run. GUI can write the harness (gui/tests/… + a script); wiring it into .github/workflows/ci.yml is PKG/QA. Say the word and I'll send the harness as a follow-up request with the job stanza pre-written.