vdm/docs/agents/AGENT-PKG-QA.md

Agent brief — PKG/QA (build, packaging, test infrastructure)

Starts in M0 alongside PROTO. You unblock everyone else and you own the release.

You own

packaging/**   .github/workflows/**   tools/testserver/**   tests/integration/**   tests/e2e/**
CMakeLists.txt   CMakePresets.json   .clang-format   .clang-tidy   .editorconfig   .gitignore

Do not write feature code in any lane's directory.

M0 — unblock the lanes (do these first, in this order)

1. Toolchain script — tools/bootstrap.sh installing the apt list in the README, verified on a clean 26.04 VM. The dev machine already has git 2.53, CMake 4.2.3, g++ 15.2, ninja, Qt 6 dev, libcurl, SQLite, nlohmann-json and ffmpeg; only qt6-svg-dev, libsecret-1-dev, nodejs/npm and (optionally) clang are missing. The script must still install the full list for clean machines. ⚠ CMake 4.x rejects cmake_minimum_required below 3.5 — check every dependency.
2. CMake — top-level CMakeLists.txt + CMakePresets.json with presets: dev (Debug + ASan/UBSan), tsan, release (RelWithDebInfo + LTO), ci. Ninja, C++23, -Wall -Wextra -Werror.
3. tools/testserver — the hostile HTTP server every lane tests against. Modes, each toggleable by URL path or flag: no-range · lies-about-accept-ranges · etag-changes · flaky-reset · slow-loris · redirect-chain · 401-basic · 401-digest · 403-without-referer · 416-always · content-length-mismatch · expiring-signed-url · throttled · chunked-no-length · utf8-content-disposition · legacy-content-disposition. CORE's definition of done is written in terms of this server, so it must exist first.
4. CI — GitHub Actions: build matrix (gcc + clang), unit tests, ASan/UBSan/TSan jobs, clang-format --dry-run -Werror, clang-tidy, web-ext lint, and conformance as a required check on every PR.

M1–M5 — keep it honest

• Nightly integration run: real veloxd + testserver, 50 concurrent downloads, assert checksums and zero leaked FDs.
• tests/e2e/ with Playwright: real Firefox + real daemon + a real file on disk.
• 72-hour soak job (M7 gate): 500 queued tasks, memory and FD graphs must be flat.
• tools/bench results published per commit so a performance regression is visible the day it lands, not in M7.

M6 — packaging

• .deb (primary): veloxd, velox-gui, velox, velox-nmhost, desktop entry, systemd user units, icons, man pages, and native-messaging manifests installed to /usr/lib/mozilla/native-messaging-hosts/ plus a postinst that also drops the per-user snap and flatpak copies where applicable. lintian clean. Publish via PPA.
• Flatpak (secondary): note that the sandbox changes the native-messaging story again — test it, don't assume it.
• AppImage (optional): if you bundle Qt, bundle it as shared objects and honour LGPLv3 relink requirements (docs/06 R5).
• AMO: signed XPI, reproducible build script, permission justification from EXT.
• Uninstall test: removes manifests, units, and sockets; leaves user data alone unless purged.
• Upgrade test: install N-1, create tasks, upgrade, confirm the DB migrates and in-flight .veloxpart files still resume.

Definition of done

• One command builds everything from a clean checkout on a clean 26.04 VM.
• CI red on: format, tidy, sanitizer failure, conformance failure, web-ext lint failure.
• A fresh VM can install the .deb, install the extension, and complete the M2 vertical slice with snap Firefox — no manual steps beyond clicking "Allow" once at pairing.