Scope the first upstream PR

[dtinth-claw]

Part of #3 (wayfinder map)

Question

Scope the first upstream PR that @dtinth will front: harness only, or harness + protocol seed suite? Is the CI workflow part of PR 1 or deferred to PR 2? Should it reference upstream jamulussoftware#3819/jamulussoftware#3821 as a regression-test story or stand alone? What is the PR narrative (title, description, motivation) — written so it is small, obviously useful, and low-burden for maintainers to review?

[dtinth-claw]

🔒 Claimed (orchestrator, 2026-07-22) — this is a grilling ticket: it resolves through @dtinth's answers, one question at a time.

All inputs are in: harness proven (#4), upstream requirements researched (#5), jamulussoftware#3819 assessed (#6), CI verified green on all platforms (#8).

Question 1 — the framing of PR 1. Upstream's still-open #2428 asks for a client/server smoke test in CI — that's their pre-agreed spec, but it is not what we built (a unit-test harness). Three honest framings:

• (a) Unit-harness PR, Automatic Client/Server Smoke Test in CI jamulussoftware/jamulus#2428 referenced as context — ship what exists (2 files + workflow, proven green). Risk: a reviewer notes "this isn't the smoke test Automatic Client/Server Smoke Test in CI jamulussoftware/jamulus#2428 asked for". Mitigation: you comment on Automatic Client/Server Smoke Test in CI jamulussoftware/jamulus#2428 first, proposing the unit harness as step 1 with the smoke test as follow-up, and let a maintainer nod before the PR opens. My recommendation — it satisfies the "agree before coding" gate in spirit and in letter, with the artifact already de-risked.
• (b) Build Automatic Client/Server Smoke Test in CI jamulussoftware/jamulus#2428's smoke test first — maximum upstream-alignment, but it's new unbuilt work (headless client+server, connection verification), a bigger and flakier artifact than a 26–66s unit job, and delays the merge of what's ready.
• (c) Bundle both — one PR with unit harness + smoke test. Directly contradicts the research finding that small single-purpose PRs merge friction-free and big ones get hammered. Not recommended.

Which framing? (Or a different one.)

On deck after Q1 (one at a time): commit authorship for the PR branch you'll front (current testing-harness commits are bot-authored with AI trailers — rebase/re-author vs. keep as-is with disclosure); whether the ASan/UBSan variant belongs in PR 1 or later; and the exact PR title/description draft for your review.

[dtinth]

Let's not rush to create a PR yet!

I think we should eventually have both smoke tests and unit tests. They provide different benefits and have different limitations, and give us different levels of confidence.

So I would like to explore the smoke testing aspect of this too, but I doubt they would be in the same PR. So smoke testing should be on our map too as that is a part of getting the software under test - while the first PR would be setting up a simple unit test harness with CI wired up, but I wouldn't call that the destination. In fact, I think this map doesn't have a fixed destination. We can explore more as we go (I find the mapping part of wayfinding more useful than reaching a fixed destination)

[dtinth-claw]

Acknowledged — no PR yet. Recorded from your answer:

• Q1 settled: the first upstream PR will be a simple unit-test harness with CI wired up; smoke tests are separate work in a separate eventual PR. Neither is "the destination".
• The map is now open-ended: I've rewritten the map's Destination section accordingly (no fixed endpoint; milestones, not destinations) and removed the out-of-scope lines that assumed the effort ends at the first merged PR.
• Smoke testing is on the map: new prototype ticket Smoke test spike: headless client/server connect in CI, seeded from upstream Automatic Client/Server Smoke Test in CI jamulussoftware/jamulus#2428's sketch. It's on the frontier, undispatched for now.

This ticket stays open for the remaining first-PR decisions when you're ready to move (commit authorship for the branch you'll front, whether an ASan/UBSan job rides along, PR title/description draft). No rush from this side.

[dtinth]

ASan/UBSan please elaborate (I am new to C++ world). Authorship of commits can be you as the agent as it is the agent who did the implementation work.

[dtinth-claw]

Recorded: commit authorship stays with the agent (it did the implementation work) — so no re-authoring; at most a mechanical squash of the CI iteration commits into a tidy branch before the PR, which I'd still recommend for reviewability.

ASan/UBSan, from zero:

C++ has no safety net: reading past the end of an array, using freed memory, or overflowing a signed integer isn't guaranteed to crash — it's undefined behavior. Often the program just quietly reads garbage, appears to work, and misbehaves somewhere far away later. That's why bugs like the ones in Jamulus's history (the 2020 ACKN out-of-bounds read found by fuzzing, the jamulussoftware#3747 out-of-bounds vector crash, the jamulussoftware#3810 out-of-range channel ID) can sit unnoticed for years: a test could execute the buggy line and still pass, because nothing visibly breaks at that moment.

Sanitizers fix exactly that. They're compiler flags (-fsanitize=address,undefined, supported by gcc/clang) that rebuild the program with instrumentation around every memory access and arithmetic operation:

• ASan (AddressSanitizer) — catches memory errors the instant they happen: out-of-bounds read/write, use-after-free, double-free. The program aborts with a report pinpointing the exact line and the memory involved.
• UBSan (UndefinedBehaviorSanitizer) — catches undefined behavior: signed overflow, invalid shifts, misaligned access, etc., again at the exact moment.

So "41 tests pass" means the observable behavior was right; "41 tests pass under ASan/UBSan" additionally means no test execution path touched memory illegally, even invisibly. For a protocol parser fed hostile network bytes, that's the guarantee that actually matters — it's the compile-time-flag equivalent of what the afl-fuzz work was hunting for by brute force. Cost: roughly 2× compile+run time, which at our scale (tests run in milliseconds) is nothing.

We already ran the suite once under both sanitizers locally during the prototype (clean). The pending question — one decision: should PR 1's workflow include a fifth matrix entry, "Linux Qt 6 + ASan/UBSan" (~10 extra lines of yml, ~40s job), or should PR 1 stay at the minimal 4-platform matrix with sanitizers as a follow-up?

My recommendation: include it — it's the cheapest possible insurance against precisely the bug class that motivated this whole effort, and it makes the PR's value proposition sharper ("tests + memory-safety net"), not bigger in any way a reviewer would push back on.

[dtinth]

I'm kinda wondering why you propose having both, testing with and without ASan/UBSan? Wouldn't just doing it with ASan/UBSan be a better choice? Not a directive. Just want your opinion on this because I noticed you didn't surface that as an option.