vdm/docs/02-roadmap.md

02 — Roadmap

Eight milestones. M0 is the only serialized one — after the contract freeze, four lanes run in parallel and only re-synchronize at integration gates.

Durations are given in "lane-weeks" for a focused agent. Treat them as sequencing weight, not a delivery promise.

---

M0 — Foundations & contract freeze (everything is blocked on this; keep it short)

#	Task	Lane
0.1	Toolchain bootstrap (apt list in README), git init, branch policy	PKG
0.2	CMake presets, top-level targets, clang-format/tidy, ASan/UBSan/TSan CI	PKG
0.3	Write every schema in contracts/schema/ for the v1 method surface	PROTO
0.4	gen_cpp.py + gen_ts.py, generated code committed	PROTO
0.5	Golden fixtures for every method; tests/conformance/ runner (C++ + TS)	PROTO
0.6	tools/mockd serving fixtures + synthetic progress events	PROTO
0.7	tools/testserver — a hostile HTTP server: no-Range, flaky, redirect chains, 401, slow-loris, changing ETag	QA
0.8	Decide product name + icon set licence; ADR for each M0 decision	PKG

Exit gate: tools/mockd answers every fixture; the generated C++ and TS clients both round-trip every fixture; CI is green on an empty repo. Freeze VERSION at 1.0.0.

---

M1 — Four lanes in parallel (the long stretch)

1A · CORE — engine ⏱ 4–5

Probe → segmentation → dynamic stealing → sparse preallocation → ring-buffered pwrite → .veloxpart.meta resume → token-bucket limiter → retry policy. DoD: downloads a 5 GB file at line rate; kill -9 at 60 % and resume finishes with a byte-identical SHA-256; every tools/testserver hostile mode handled; ASan/TSan clean; tools/bench numbers recorded as the baseline.

1B · DAEMON — RPC + state ⏱ 3–4

Unix socket + WS listeners, JSON-RPC dispatcher, subscriptions and event batching, SQLite schema + migrations, queues, scheduler, settings, pairing/token store, systemd user units. DoD: passes the full conformance suite as a server; velox CLI can add/list/pause/ resume; survives daemon restart with all tasks intact.

1C · GUI — Qt shell against mockd ⏱ 4–5

Main window, model/delegate table, category tree, Add-URL + File-Info dialogs, progress dialog with segment bars and speed graph, Options tabs wired to settings.*, tray, drop target, QSS theming. DoD: every screen in docs/03-gui-spec.md exists and is driven entirely by mockd; 10 000 synthetic rows scroll at 60 fps; zero download logic in the GUI tree.

1D · EXT — extension against mockd ⏱ 3–4

Capture pipeline, both transports + pairing, context menus, popup with live progress, options page, media detection. DoD: intercepts a real download in real Firefox and hands it to mockd; fail-open verified by test (daemon killed → Firefox downloads normally); web-ext lint clean.

Lanes touch only their own directories. The sole shared surface is contracts/, and only PROTO writes there. See CLAUDE.md.

---

M2 — First vertical slice ⏱ 1–2 (all lanes, one week, together)

Swap mockd for the real veloxd. Click a link in Firefox → extension captures → File-Info dialog appears → download runs multi-segment → progress in GUI and popup → file lands in the right category folder → checksum verified.

Exit gate: that flow works end-to-end on a clean Ubuntu 26.04 VM, from a .deb, with snap Firefox. This is the moment the snap native-messaging risk is settled for real.

---

M3 — IDM parity ⏱ 3–4 (parallel again)

Categories & automatic file distribution · rules engine (extension/MIME/host/size → folder) · queues + scheduler UI · speed limiter · batch download (wildcards + clipboard blob) · Site Grabber wizard · Site Logins via Secret Service · proxy/SOCKS5 · duplicate handling · "Refresh download address" · post-download commands · virus-scan hook.

Exit gate: the IDM feature checklist in this doc's appendix is ticked or has a written "won't do, because…".

---

M4 — Media grabber ⏱ 2–3

HLS/DASH manifest parsing in the daemon, variant enumeration, segment-parallel fetch, mux via ffmpeg, in-page video panel in the extension. DRM streams detected and clearly refused.

M5 — Polish ⏱ 2

Theming light/dark, i18n + RTL, accessibility pass, notifications, sounds, global shortcut via the portal, Wayland clipboard spike resolved, first-run wizard, tray/drop-target behaviour, --help and man pages.

M6 — Packaging & release ⏱ 1–2

.deb + PPA, Flatpak manifest, native-messaging manifests installed to all four locations, AMO submission (signed XPI), autostart, upgrade/migration test from a previous DB version, uninstall leaves no orphan sockets or manifests.

M7 — Hardening ⏱ 2

libFuzzer on every parser (Content-Disposition, HLS, DASH, meta file, JSON-RPC), 72-hour soak with 500 queued tasks, perf targets from docs/04 §8 enforced in CI, threat-model review of the WS transport, crash reporting (local only, opt-in, no telemetry).

---

Dependency graph

M0 ──┬──► 1A CORE ──┐
     ├──► 1B DAEMON ─┼──► M2 ──► M3 ──► M4 ──► M5 ──► M6 ──► M7
     ├──► 1C GUI ────┤
     └──► 1D EXT ────┘
        (all four against mockd, no cross-lane blocking)

Critical path: M0 → 1A/1B → M2. GUI and EXT can absorb schedule slack because mockd never blocks them. If you must cut scope, cut M4 (media) before anything else — it is the largest chunk of work with the least effect on core parity.

---

Appendix — IDM feature checklist

IDM feature	Milestone	Notes
Multi-segment accelerated download	M1	Dynamic stealing, not static split
Resume broken/interrupted downloads	M1	With If-Range revalidation
Browser integration / auto-capture	M1D+M2	Firefox first; Chrome later if wanted
Download categories + auto file distribution	M3	Rules engine
Queues + scheduler	M3	Per-queue time windows
Speed limiter	M1/M3	Engine in M1, UI in M3
Batch downloads / wildcards	M3
Site Grabber	M3	Depth-limited crawler with filters
Video/media grabber	M4	HLS/DASH; no DRM
Drag-and-drop drop target	M1C
Clipboard monitoring	M5	Wayland-limited; see risks
Proxy / SOCKS5 / site logins	M3	Credentials in Secret Service
Checksum verification	M1	MD5/SHA-256
On-completion actions (open/shutdown)	M1C/M3	Shutdown via logind, confirmed
ZIP preview	—	Won't do. Low value on Linux
Dial-up / VPN auto-redial	—	Won't do. Obsolete