# Agent brief — CORE (`libveloxcore`)

**Starts when PROTO freezes `VERSION`. The critical path runs through you.**

## You own
```
core/**    tools/bench/**    tools/fuzz/**
```
You may read `contracts/` and `docs/`. You write nowhere else — in particular **you never
touch `daemon/`**: if the daemon needs something, expose it as a core API and tell DAEMON.

## Read first
`docs/04-engine-design.md` end to end. It is your specification, not background reading.

## Hard architectural constraints
- **No JSON, no SQL, no Qt, no RPC in `core/`.** Your public API takes a `DownloadSpec`
  and emits typed callbacks. If you find yourself including a protocol header, stop.
- C++23, `-Wall -Wextra -Werror`, no raw `new`/`delete`, no naked `pthread`.
- Every public header under `core/include/vdm/` compiles standalone.
- Errors are returned (`std::expected`-style `Result<T>`), not thrown, on the transfer path.
- **No allocation in the curl write callback.** The ring buffer is preallocated at task
  start. This is checked in review and by a bench assertion.

## Build order

1. `util/` — `Result<T>`, event bus, thread pool, logging, byte-span helpers.
2. `net/http_client` — libcurl multi wrapper, one `curl_multi` per worker thread, poll
   loop, proxy/auth/redirect/cookie plumbing.
3. `net/probe` — HEAD then ranged-GET fallback, header parsing, **`Content-Disposition`
   RFC 5987/6266 including the legacy forms** (this is a classic source of mojibake — give
   it its own test table and a fuzz target).
4. `io/sparse_file` + `io/write_buffer` — `posix_fallocate`, per-segment ring buffer sized
   by `buffer_bytes`, `pwrite` at absolute offsets, `posix_fadvise(DONTNEED)`, timed
   `fdatasync`.
5. `meta/veloxpart` — the resume sidecar in `docs/04` §5, CRC-verified, `fdatasync`'d at
   segment boundaries. **Write the reader first and fuzz it** — this file is attacker-
   adjacent (it lives in a world-writable-ish download dir).
6. `segment/segmenter` + `segment/stealer` — dynamic segment stealing, `min_segment_bytes`
   floor, per-host connection caps.
7. `rate/token_bucket` — hierarchical global → queue → task.
8. `task/download_task` — the state machine in `docs/04` §1, retry/backoff policy, mirrors.
9. `rules/` — filename sanitization + collision policy + category matching (pure functions;
   DAEMON supplies the rule table).
10. `media/` — **M4, not now.** Leave the directory empty.

## Definition of done (M1)
- 5 GB download saturates a 1 Gbit link at ≤ 8 % of one core (recorded in `tools/bench/`).
- `kill -9` at ~60 % → resume completes → SHA-256 matches the reference byte for byte.
- Every hostile mode in `tools/testserver` handled: no-Range, lying `Accept-Ranges`,
  ETag change mid-download, 401, 416, redirect chains, slow-loris, connection reset,
  expiring signed URL, `Content-Length` mismatch.
- ASan + UBSan + TSan clean under a 20-task load test.
- Fuzz targets for `Content-Disposition`, the `.veloxpart.meta` reader, and URL parsing run
  1 M+ execs with no crash.
- Public API documented in `core/include/vdm/README.md` and reviewed by DAEMON before M2.

## Do not
- Do not start with `io_uring`. It's a post-1.0 experiment gated on a ≥10 % bench win.
- Do not implement HLS/DASH in M1.
- Do not add a "just for testing" JSON dependency.