samiandClaude Opus 5
facd851824
CI / clang-format (push) Canceled after 0s
CI / testserver (push) Canceled after 0s
CI / bootstrap-script (push) Canceled after 0s
CI / bootstrap-script-2604 (push) Canceled after 0s
CI / extension-lint (push) Canceled after 0s
CI / build (clang) (push) Canceled after 0s
CI / build (gcc) (push) Canceled after 0s
CI / sanitizers (dev) (push) Canceled after 0s
CI / sanitizers (tsan) (push) Canceled after 0s
CI / clang-tidy (push) Canceled after 0s
CI / conformance (push) Canceled after 0s
CI / nightly-integration (push) Canceled after 0s
CI / gui-dod (push) Canceled after 0s
CI / gui-dod-nightly (push) Canceled after 0s
The tree is Ubuntu-first, but the Linux-specific surface is about ten files and already sits at the bottom of the I/O and RPC stacks. Rather than fork the repo or scatter ifdefs, platform differences go behind narrow seams with one backend directory per OS, selected centrally in cmake/platform.cmake. Linux stays the reference implementation and its behaviour does not change: the owning lanes (CORE, DAEMON) move today's Linux code behind the seams on Ubuntu first, with the suite still green, before any macOS code exists. A new PORT lane owns only the per-OS backends, so macOS work never writes shared logic and CLAUDE.md's lane rule stays intact. Adds ADR 0020 (the decision and phases), docs/08-porting.md (seam list, API mapping for macOS and Windows, dependency table, verification gates) and docs/agents/AGENT-PORT.md (the lane brief), plus the PORT row in the ownership table. Co-Authored-By: Claude Opus 5 <[email protected]>
51 lines
2.6 KiB
Markdown
51 lines
2.6 KiB
Markdown
# 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.
|