vdm/docs/agents/AGENT-PORT.md

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.