dd868aeb

docs: record the platform layer and the macOS measurements

a73x 2026-09-03 15:10

Commit message

docs: record the platform layer and the macOS measurements

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SakwJEwD9dXBoRP5kWbemW

docs/decisions.md

+the comment's. Graded by mutation: with the row translation capped at one
+row every older leg passes and only the stacked leg fails. The suite's
+scenario pin goes from 111 to 112.
+## 2026-09-03 — the platform layer (macOS port, step 2)
+Every OS-specific spelling under `src/` now lives in `src/os/`, one row per
+side. `server_os` holds what only the daemon does — the pty fork, the
+detached daemon fork, peer credentials, an anonymous fd for the upgrade
+manifest, `exitNow`, `closeFrom`, the pty's mode and foreground pgid, the
+window-size ioctl and the stale-image verdict — and `client_os` holds the
+few the wall and askpass do: pid, euid, peer credentials, the parent walk,
+window size and a pty pair. `spawn` moved in beside them. Each root is the
+CONTRACT — a doc comment per operation says what it guarantees and which
+failure it prevents — and `impl` switches on `builtin.os.tag`, so a build
+for an OS with no arm is a `@compileError` at that switch rather than a
+link error or a runtime surprise. The client row is deliberately SEPARATE
+from the server's rather than one `os` row: the client never links a fork
+or a pty, and an app that links the engine and a client must not either.
+**The gate is folder rule 7.** No production line under `src/`,
+`src/engine/`, `src/client/`, `src/tui/`, `src/server/` or `src/cli/` may
+spell `std.os.linux`, `/proc`, `memfd`, `close_range`, `exit_group`,
+`so.peercred`, `so_peercred`, `iocsptlck` or `iocgptn`. `src/os/` is absent
+from that folder list on purpose: its children may spell anything, and its
+roots have no reason to. Comments count, as they do for rule 4, because a
+comment naming a Linux mechanism is one that goes stale the day a second
+arm exists. Four needles are spelled to catch a name in both the form Zig
+writes it and the form C and our own prose do — `so.peercred` and
+`so_peercred` for `std.posix.SO.PEERCRED` and `SO_PEERCRED`, where a bare
+`peercred` would have banned `client_os.peerCred`, the very operation
+callers are supposed to reach for; `iocsptlck` and `iocgptn` drop the
+leading T so they catch `std.posix.T.IOCGPTN` as well as `TIOCGPTN`.
+**Measured before the design, on a Linux host.** zig 0.15.2 cross-compiles
+a libc program using `posix_openpt`, `kqueue`, `libproc` and `dyld` to
+aarch64-macos with no SDK, and links Mach-O with its own linker — LLD
+refuses ("using LLD to link macho files is unsupported") — so `linkerFor`
+asks for `use_lld` on every target except Darwin. ngtcp2 1.25.0 and
+wolfSSL 5.9.2 cross-build with `WOLFSSL_SYS_CA_CERTS=no` (mux is PSK-only
+and the system-CA path wants Security.framework) and a
+`CMAKE_FIND_ROOT_PATH` fence at the target prefix, without which ngtcp2
+finds the host's `libwolfssl.so`. `std.posix.socket` and `std.posix.accept`
+already emulate `SOCK_CLOEXEC`, `SOCK_NONBLOCK` and `accept4` on Darwin
+with a trailing `fcntl`, so no socket site needed a row at all. ghostty-vt
+links three C++ libraries whose build.zig files each call ghostty's
+`apple_sdk.addPaths`, which resolves the HOST libc on a Linux host and
+fails the C++ compile on glibc headers — upstream code build.zig cannot
+reach, the cross-compile blocker that leaves the build-host decision open,
+and the reason this step stops at the platform layer and writes no
+`_macos.zig` arm.
+**One amendment to the spec, made while writing the row.** The spec's
+`openPty` plus `becomeSession` are one `forkPty` instead: `forkpty(3)`
+exists on both OSes, returning pid 0 in the child exactly as `fork` does,
+so the child code stays one branch. Zig ships no `<util.h>` for Darwin,
+which is a missing HEADER and not a missing symbol — that arm declares it
+with one `extern "c" fn forkpty` line rather than reimplementing the pty
+open as `posix_openpt` + `grantpt` + `unlockpt` + `ptsname`.
+**The QUIC prefix and the linker follow the TARGET, never the host.**
+`quicDeps` names one word per prefix — `native` for the host's own libc,
+`musl` for the static release, and `<arch>-<os>` for any other cross target
+— shared with `build-deps.sh`, `make deps`, `make clean-deps` and wan.sh's
+musl cross-build, so a third OS is one more `case` arm in the script and
+nothing in build.zig. A cross build that reused the host's prefix would
+link x86_64 Linux archives into an aarch64 macOS binary.
+**Two behaviours changed shape on Linux without changing outcome.** The
+stale-image verdict is an inode compare against what the image's path held
+at boot, not the kernel's ` (deleted)` suffix: `noteBootImage` stamps the
+path and its inode once, and every later ask re-stats that path, so a
+rename-over reads stale and a file that lands there afterwards can never
+promote a stale daemon back to current. The two failures are kept apart. A
+path this OS will not name at all records NOTHING and answers false —
+unknown is not stale, and a wall must not dress a healthy box in a warning
+over a refused readlink. A path that IS named but holds nothing records a
+BORN-STALE state, the path with no ident, and answers stale for the life of
+the process, because that daemon is already executing an image no path
+holds. Second, `xdg.reapDeadPid` asks `kill(pid, 0)` rather than
+`access(/proc/PID)`: EPERM is alive-but-not-ours and keeps the entry, and
+ESRCH is the one answer that means the pid is gone.
+**`sockpath.runtimeDir` owns the default socket directory.** One switch —
+`$XDG_RUNTIME_DIR` on Linux, and still no fallback, because a guess cannot
+make two binaries agree on one daemon — so the daemon, the client and the
+askpass listener agree by construction and another OS spells its own
+default in one place.
+**The shell harness asks the OS through named helpers.** `test/e2e_lib.sh`
+holds one name per question a pin asks about a pid, an fd table, a bound
+UDP port or a file's mode: `pid_alive`, `pid_exe`, `pid_comm`, `pid_args`,
+`pid_children`, `pid_fd_count`, `pid_fd_targets`, `pid_holds_unix_sock`,
+`pid_rss_kb`, `udp_local_bound`, `udp_table`, `file_mode`, `file_size`,
+`sha256_of`. The SPELLING of the question now lives in one place per OS and
+the question itself stays in the group file, so a second OS adds a
+`case "$_os"` arm here and changes no group file. `oracle_selftest` runs
+once before the first group and is the helpers' own pin: a helper that
+quietly stopped answering — a missing binary, a `/proc` a sandbox will not
+show — would not fail a pin loudly, it would make every pin that reads it
+agree with anything, and the suite would go green having tested nothing.
+Its subject is off-origin on every dimension the helpers could accidentally
+hold constant: a child that is not pid 1, more open fds than the three any
+fixture would hold, an argv worth losing, and a child of its own. The
+socket arm is asked in both directions, of a listener that holds the path
+and of a shell that does not, because a `pid_holds_unix_sock` answering yes
+to everything would pass the one pin that reads it just as happily as a
+correct one.
+**How the wire claim was graded, and what the cross-version gate could not
+say.** `make ci` is green. `test/xversion.sh` is NOT, and was not green
+before this branch either: its preflight demands a `muxd` in the old
+prefix and it drives that side as `muxd run`, so the branch base — one
+`mux` binary since v0.0.1-16 — cannot serve as its old side at all, and
+its pins still assert a PRE-M18 old side ("the daemon created session zz —
+this is not a pre-M18 daemon", "it decoded frames an old client has no arm
+for"). Against the released v0.0.1-15 tarball it answers 5 passed, 7
+failed. So the claim was graded DIFFERENTIALLY instead: the same gate, the
+same v0.0.1-15 old side, run once with this branch's binary as the new
+side and once with the branch base's, gives the identical verdict pin for
+pin — 5 passed, 7 failed, the same seven messages. The four real
+compatibility pins are among the passes in both runs: a new client driving
+an old daemon's default session over a socket and over QUIC, an old client
+driving the new daemon's, and an old `muxa`'s empty `status_req`. The
+refactor moved no byte on the wire. The gate itself needs its old side
+re-pinned to a version that still exists; that is not this branch's work.
+Spec: `docs/superpowers/specs/2026-09-03-macos-port-design.md`.