# Agent brief — PORT (per-OS backends)

**Starts after Phase 0: CORE and DAEMON have landed the seams on Ubuntu.**

## You own
```
core/src/**/platform/<os>/**        daemon/src/**/platform/<os>/**
cmake/platform*.cmake               packaging/macos/**   packaging/windows/**
```
You may read everything. **You never write logic** — not in `core/src/io/*.cpp`, not in
`daemon/src/rpc/*.cpp`, not in `gui/`, never in `contracts/`.

## Read first
`docs/adr/0020-cross-platform-strategy.md`, then `docs/08-porting.md` — it has the seam
list, the API mapping and the dependency table. Then `CLAUDE.md`.

## The one rule that matters
**Linux behaviour never changes.** If your port needs a seam that doesn't exist, or a seam
whose shape is wrong, you do not widen it yourself — you file a request with the owning
lane (CORE for `core/`, DAEMON for `daemon/`) exactly as every other lane does. A port that
quietly edits shared logic is how one tree becomes two.

## Build order (macOS)
1. **Configure at all.** The root `CMakeLists.txt` requires `libsecret-1` unconditionally;
   that must be Linux-gated before anything else compiles. File it with PKG/QA — root build
   files are theirs.
2. `core/` — `preallocate`, `advise_dontneed`, `flush_durable`. Use `F_FULLFSYNC`, not
   `fsync`: `.veloxpart` resume correctness depends on a real flush.
3. `daemon/` — `Wakeup` (self-pipe), `peer_of` (`getpeereid`), `instance_lock` (socket file
   + `flock`, with stale-socket cleanup), `runtime_dir` (`$TMPDIR`, `~/Library/Application
   Support/Velox`).
4. Unit tests green for both lanes.
5. `tools/testserver` (stdlib Python) and conformance (Node) — expected to run unchanged.
   If they don't, that's a bug worth reporting, not patching around.
6. GUI against Qt 6 for macOS.
7. Packaging — `.dmg`/Homebrew, `launchd`, native-messaging manifest locations. Last.

## Definition of done (Phase 1–2)
- macOS builds `libveloxcore`, `veloxd` and `velox` with `-Wall -Wextra -Werror`.
- Core and daemon unit tests pass on macOS.
- One real download completes on macOS against `tools/testserver` with a SHA-256 that
  matches the server's reference — the same gate the Linux vertical slice passed.
- `kill -9` mid-download, restart, resume completes and the checksum still matches.
- The Ubuntu suite is **still** 57/57 from the same commit.

## Do not
- Do not add `#ifdef` outside a `platform/<os>/` file.
- Do not change a fixture, a schema or a hostile-mode expectation to make macOS pass.
- Do not substitute `F_NOCACHE` for `posix_fadvise(DONTNEED)` — see `docs/08` for why.
- Do not start with packaging.