samiandClaude Sonnet 5
5b03eff926
run.sh's TS runner only ever started mockd; veloxd existed but nothing in
the ctest -L conformance path touched it, so mockd's always-valid fixtures
were the only thing ts/replay.ts ever saw. That let a real bug through:
veloxd's download.get can return segments: 0, which TaskSummary.segments
forbids (minimum 1, required) — nothing caught it.
Add a 3b step to run.sh (still the one canonical entry, per ADR 0014):
builds veloxd, starts it isolated (its own XDG_RUNTIME_DIR/XDG_DATA_HOME/
XDG_CONFIG_HOME), seeds saveTo.allowedRoots/defaultDir directly into the
isolated velox.db (settings.set is itself a stub, and the default
~/Downloads root doesn't isolate download.add's writes), then replays
every fixture against it over both transports.
Most handlers are still stubs (daemon/docs/deferrals.md D1-D4b). Fixtures
that hit them get an expected-failure entry in the new veloxd-xfail.json,
loaded by replay.ts's new --xfail flag. This is a maintained allowlist,
not a snapshot: a listed fixture that unexpectedly *passes* is flipped
back to a failure (applyXfail), so the list can only shrink as DAEMON
lands handlers, never rot into a list nobody rechecks. download.get's
segments: 0 is deliberately *not* on it — that's the regression this
step exists to catch.
Also hardened setupBindings: a server that can't even complete fixture
binding used to take the whole runner down with an uncaught exception
before a single fixture was checked. It's now a reported Outcome instead,
so the run still produces a coherent report. That robustness fix earned
its keep immediately: veloxd's download.add crashes on startMode
"later" (a valid, documented StartMode — "the File Info dialog's
Download Later button") with a SQLite CHECK constraint violation, because
migrations/0001_initial.sql's start_mode CHECK never had 'later' added to
it (and includes 'manual'/'auto', neither a contract value). That's a
second, more severe bug this wiring found, unrelated to segments: 0 and
currently blocking most of the veloxd run — filed for DAEMON in
tests/conformance/README.md, not fixed here (out of lane). capture.offer
and capture.getRules are also stubs but missing from deferrals.md's
D-list; xfailed with a note asking DAEMON to add the row.
Verified live once against a real, isolated veloxd before this session's
sandbox became persistently contended for veloxd's single-instance lock
(UID-scoped, not namespaced by XDG_RUNTIME_DIR — daemon/src/main.cpp;
documented as a caveat in the README): it built, started isolated, seeded
settings, connected over both transports, and surfaced the startMode bug
above as a real, non-xfailed failure — confirming the whole pipeline
including --xfail end to end. segments: 0 is confirmed by direct reading
of daemon/src/store/tasks.{hpp,cpp} (TaskRow::eff_segments defaults to 0,
copied verbatim into TaskSummary.segments) rather than by a second live
run reaching that specific fixture, since setup itself fails first on the
startMode bug above. mockd path re-verified green after these changes
(200/200, up from 196/196 — the new setup/$taskId outcomes are visible
and passing).
Recommendation for PKG: don't flip this required yet. The existing
`conformance` ctest entry is already a required check, and right now the
startMode bug fails most of the veloxd run, not just the one expected
segments: 0 case — merging as-is would block every lane's PRs on two
DAEMON bugs at once, one of them unrelated to what this task set out to
catch. Required once DAEMON lands a fix for startMode "later" at minimum;
segments: 0 can stay red for a while by design, same as any other tracked
regression.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01SFeUKLbdHizrJjLBeK7ffz
Velox Download Manager (VDM)
An IDM-class download manager for Ubuntu 26.04 LTS: multi-segment accelerated HTTP(S) downloading, resume, categories and automatic file distribution, queues and scheduler, speed limiter, a Firefox extension that captures downloads automatically, and clipboard link capture.
Name is a placeholder. Binaries are
veloxd,velox-gui,velox,velox-nmhost. Rename before first release if you want something else — do it in M0, never later.
Status
Phase M0 — scaffolding. No implementation code exists yet. This repository currently contains the architecture, the wire contract, the roadmap, and one brief per build lane so that several agents can work in parallel without colliding.
Start here:
| Document | What it answers |
|---|---|
| docs/01-architecture.md | Process model, why four binaries, framework choices and why |
| docs/02-roadmap.md | Milestones M0–M7, what runs in parallel, exit gates |
| docs/03-gui-spec.md | IDM-parity UI: every window, dialog, column, menu |
| docs/04-engine-design.md | Segmentation, resume, buffers, rate limiting, disk I/O |
| docs/05-extension-spec.md | Firefox capture, transports, pairing, media grabber |
| docs/06-risks-and-spikes.md | Snap Firefox, Wayland clipboard, and the other landmines |
| docs/07-packaging.md | .deb/PPA, Flatpak, AMO signing, install layout |
| contracts/README.md | The interface. Both sides build against this |
| CLAUDE.md | Rules of engagement for agents working in this repo |
Per-lane briefs live in docs/agents/ — one per agent, each with an owned directory list, a definition of done, and the files it must never touch. To dispatch the agents, use docs/agents/PROMPTS.md — six copy-paste prompts plus the worktree commands and the wave order.
Architecture in one picture
┌────────────────────┐ native messaging (stdio JSON) ┌──────────────┐
│ Firefox extension │◄───────────── or ──────────────►│ velox-nmhost │
│ (MV3, TS) │ loopback WS 127.0.0.1 + token └──────┬───────┘
└────────────────────┘ │
│
┌────────────────────┐ ▼
│ velox-gui (Qt 6) │◄──── JSON-RPC 2.0 over Unix socket ──► ┌─────────────┐
└────────────────────┘ $XDG_RUNTIME_DIR/velox/velox.sock │ veloxd │
│ (daemon) │
┌────────────────────┐ │ │
│ velox (CLI) │◄───────────────────────────────────────┤ libveloxcore│
└────────────────────┘ └──────┬──────┘
│
SQLite + sparse files
The daemon owns all state and all sockets. The GUI is a view — closing it does not stop a download. The extension never touches the disk; it hands URL + headers + cookies to the daemon and gets a task id back.
Repository layout
vdm/
├── contracts/ ⭐ Wire contract: JSON Schema, fixtures, codegen. Frozen per version.
├── core/ C++23 libveloxcore — engine. No UI, no RPC, no SQL.
├── daemon/ C++23 veloxd — RPC server, scheduler, queues, SQLite store.
├── gui/ C++23 velox-gui — Qt 6 Widgets, IDM-parity UI.
├── cli/ C++23 velox — scriptable client.
├── nmhost/ C++23 velox-nmhost — Firefox native-messaging bridge (thin pipe).
├── extension/ TS Firefox MV3 WebExtension.
├── tools/
│ ├── mockd/ TS mock daemon — lets GUI + extension work before veloxd exists.
│ ├── testserver/ Deliberately hostile HTTP server (no Range, flaky, redirects, auth).
│ ├── bench/ Throughput and CPU benchmarks.
│ └── fuzz/ libFuzzer targets for parsers.
├── tests/
│ ├── conformance/ Protocol suite. Every lane must pass it. Gate for merging.
│ ├── integration/ veloxd + testserver.
│ └── e2e/ Playwright: real Firefox + real daemon + real file on disk.
├── packaging/ debian/, flatpak/, appimage/, native-host manifests.
└── docs/ Everything above, plus adr/ and agents/.
Toolchain bootstrap
Surveyed on this machine 2026-09-09 — most of it is already installed:
| Present | Version |
|---|---|
| git · cmake · ninja · g++ · gdb | 2.53.0 · 4.2.3 · — · 15.2.0 (C++23 ready) |
| qt6-base-dev · qt6-tools-dev · qt6-tools-dev-tools | ✓ |
| libcurl4-openssl-dev · libsqlite3-dev · nlohmann-json3-dev · libssl-dev | ✓ |
| libavformat-dev · libavcodec-dev · ffmpeg | ✓ |
| clang-format · clang-tidy · python3 · pkg-config | ✓ |
| python3-jsonschema · python3-referencing (conformance static runner) | ✓ |
Only these four are missing:
sudo apt update && sudo apt install -y \
qt6-svg-dev \ # GUI: SVG icon rendering
libsecret-1-dev \ # DAEMON: Secret Service for site logins
nodejs npm \ # EXT + PROTO: extension build, mockd, conformance runner
clang # optional: libFuzzer targets in M7
Node in the 26.04 archive may lag; if the extension toolchain needs 22+, use nvm.
Verify with cmake --preset dev && cmake --build --preset dev once lane CORE lands its
first target. Note CMake 4.2.3 is installed — newer than the 3.28 floor in
CMakeLists.txt, and it hard-errors on cmake_minimum_required below 3.5, so no
dependency may ship a pre-3.5 CMake file.