# macOS Apple Silicon (native arm64) port — implementation plan

Session 2026-09-18. Scope decision: **native arm64 only** (no Rosetta/x86_64
build). Nothing in this plan has run yet; §1 is measured, §2 is design, §3 is
the work. Companion: `LINUX-PORT.md` (same shape, earlier platform).

Execution model: research/design/integration items are run by the session
model ("integrator"); items marked **mechanic** are self-contained briefs for
the Sonnet-backed `.opencode/agents/mechanic.md` subagent. Every mechanic
item lists files, recipe, budget, verify. Items in the same phase that touch
disjoint files may run in parallel (dev-process.md §3).

---

## 0. Summary

The compiler is not the problem. Apple clang builds 235/237 C TUs of the
existing tree with `-fms-extensions` (in place of GCC's `-fplan9-extensions`)
plus small fixes. fast3d already selects a 4.1 Core GL context on macOS and
uses no compat or >4.1 features.

**The blocker is the port's address model.** The port realises the N64's
32-bit address space as *host* addresses: DRAM at `0x70000000` (+ KSEG0
mirror at `0x80000000`), cart at `0x10000000`, and ~1700 linker-absolute
symbols with those values; `osVirtualToPhysical` is a `u32` truncation and
`u32 → pointer` is an identity cast. That works on Windows/Linux because the
image and all mappings sit below 4 GiB. On native arm64 macOS **nothing can be
mapped below 4 GiB**: `__PAGEZERO` covers it, `-pagezero_size` gets the
process SIGKILLed, PIE is mandatory, and `MAP_32BIT` fails.

The fix (§2) is a **shifted window**: keep the N64 32-bit space intact but
place it at a fixed host base `B` (`PORT_ADDR_BASE`), so every game-visible
32-bit value is *identical* to today's Windows values and only the
`u32 → host pointer` direction changes (add `B`). `B = 0` on Windows/Linux, so
those builds are byte-for-byte unchanged. All conversions go through a
port-owned chokepoint; the residue is a compiler-driven census of raw
`u32 → pointer` casts in game code, each rewritten through a `PORT_*` macro
(the sanctioned D3x ABI/layout class — no logic change).

Phases: **M0** compile+link on macOS → **M1** address model in `port/` →
**M2** game-code cast census + rewrites → **M3** runtime bring-up (Cocoa
threading, first frame, level sweep) → **M4** packaging/CI/docs.

---

## 0b. Base change (2026-09-18, later): rebased onto PR #88 + GCC

After M0/M1 were working on Apple clang, PR #88 ("Add native Intel macOS
support", JunielKatarn) turned up: a single commit on this repo's exact base,
targeting **Intel** macOS and explicitly leaving Apple Silicon unsupported. The
arm64 work was rebased onto it rather than maintained in parallel. Branch:
**`macos-arm64-gcc`** (the earlier clang branch `macos-arm64` is superseded).

**Adopted from #88 — this deletes the corresponding work in §3 M0:**
- Homebrew GNU GCC (`gcc-16`) + libstdc++. Removes every clang workaround:
  no `-fms-extensions`/`-Wno-microsoft-anon-tag`, no libc++ wrapper header
  shims (the old D295), no `-D_FORTIFY_SOURCE=0`.
- `scripts/gen_macho_syms.py` — build-tree Mach-O symbol generation; the
  committed `*.darwin.s` duplicates are gone.
- `scripts/strip_weak_pragmas.py` + `port/src/macho_weak_aliases.s` — the
  `#pragma weak` handling, so **`src/` carries no macOS edit for it** (the old
  D294 in-source `#if defined(PORT) && defined(__APPLE__)` equates are gone).
- POSIX `shm_open` DRAM backing, Darwin crash handling, and the AppKit
  main-thread event-pump guard in `gfx_sdl2.cpp` (that last one was §3 M3.1).

**Kept from this plan — the arm64 delta:**
- §2's shifted-window address model (M1 / D298). `-pagezero_size 0x10000`,
  the core of #88's Intel approach, is fatal on arm64 (shrinking `__PAGEZERO`
  gets the process SIGKILLed), so CMake now sets it for x86_64 only and arm64
  uses `PORT_ADDR_BASE`.
- D296 (`__x86_64__` → `PLATFORM_64BIT`). Without it #88's tree does not even
  *link* on arm64 — 23 undefined `_ANIM_DATA_*`.
- `gen_macho_syms.py --base` (bakes `PORT_ADDR_BASE` into the absolute
  symbols; `--base 0` output is byte-identical to #88's transform).
- arm64 crash registers (`__ss.__pc/__lr/__sp/__fp`) and
  `_dyld_get_image_header` / `_NSGetExecutablePath`.
- All of M2 (the game-code re-basing sweep).

Mergeability consequence: the arm64 contribution is now a small additive delta
on top of #88, and `src/` has no macOS-specific toolchain/alias edits.

## 1. Measured facts (this machine: macOS 26.3, arm64, Apple clang 21, SDL2 via `sdl2-compat` 2.32)

| # | Test | Result |
|---|------|--------|
| F1 | `mmap(MAP_FIXED)` at `0x10000000` / `0x70000000` / `0x80000000`, native arm64 | **ENOMEM** — first 4 GiB is `__PAGEZERO` |
| F2 | Link with `-Wl,-pagezero_size,0x4000` (and 0x1000…0x90000000), native arm64 | links; **process SIGKILLed at exec (exit 137)** |
| F3 | `-Wl,-no_pie`, `-Wl,-image_base` | ignored ("Linking with PIE"); image lands at `0x1_0000_0000 + slide`, slide observed `0x32_0000`–`0x4EF_8000` (varies per run) |
| F4 | `mmap(MAP_32BIT)` | defined, **fails**; default thread stacks at `0x16b_xxxx_xxxx` |
| F5 | Same code as x86_64 + `-pagezero_size 0x1000` under Rosetta | all fixed maps succeed (not our target; recorded for completeness) |
| F6 | `mmap(MAP_FIXED)` at `B + n64addr` for `B ∈ {1,2,3,4} << 32` | all succeed — **but `MAP_FIXED` silently replaces existing mappings on macOS** (no `MAP_FIXED_NOREPLACE`), so success ≠ range was free. A 64 MiB `malloc` was observed at `0x4_8400_0000`. |
| F7 | Non-clobbering 4 GiB `PROT_NONE` reservation via `mach_vm_map(VM_FLAGS_FIXED)` (no `OVERWRITE`) | `0x3<<32` free (this run); `0x2,0x4,0x8,0x10,0x20,0x40 <<32` **occupied** (libmalloc/VM regions, varies); **`0x100_0000_0000` (1 TiB), `0x400_0000_0000`, `0x1000_0000_0000` (16 TiB) reserved cleanly**, DRAM+cart carved inside OK |
| F8 | Hinted `mmap` without `MAP_FIXED` | hint ignored (relocated to `0x70_0000_0000`) — cannot rely on hints; must reserve |
| F9 | `shm_open`+`ftruncate`+2×`mmap(MAP_SHARED\|MAP_FIXED)` at `B+0x70000000` / `B+0x80000000` | works; alias verified (`memfd_create` replacement) |
| F10 | `.set _cfb_16, 0x470000000` (64-bit-valued absolute symbol) referenced from C | links, `nm` type `A`, **no rebase fixups** (`dyld_info -fixups`) → ASLR-stable; clang emits GOT loads |
| F11 | `-fplan9-extensions` | unknown argument (hard error). `-fms-extensions` accepts `inherits struct`; derived→base pointer passing becomes `-Wincompatible-pointer-types` (already demoted) |
| F12 | `-fpermissive` (C), `-Og`, `-Wno-unused-but-set-variable`, `-fno-pie` | accepted (`-fpermissive` is a silent no-op in C) |
| F13 | `-Wl,--disable-dynamicbase`, `-Wl,-Ttext-segment=` | ld64 unknown options (already not applied on APPLE) |
| F14 | `.section .data` in both `.s` files | assembler error; `.data` works. `.global LameE` (88 `L*` names in `romassets_u.s`) → "non-local symbol required" until `_`-prefixed |
| F15 | `#pragma weak X = Y` (sinf.c, cosf.c, objective_status.c, lv.c, spectrum.c) | Darwin emits a *local* alias: cross-TU users get undefined symbol; same-TU `extern` + use → "reference to X is ambiguous" (lv.c:603-606, spectrum.c:266) |
| F16 | `-fsyntax-only` sweep, 237 C TUs, with `-fms-extensions -D_FORTIFY_SOURCE=0` + corrected host-header shim paths | **235/237 pass** (fails: lv.c, spectrum.c — F15). 4 fast3d `.cpp` TUs fail on libc++ header shadowing (`include/math.h`, `limits.h`, `assert.h` ahead of the SDK) |
| F17 | `port/include/pc_protos.h:34` is gated on `__x86_64__` | on arm64 all ~400 D38 prototypes vanish → 45–63 implicit-declaration warnings per big TU (bg.c, chrai.c, propobj.c, front.c, boss.c) = silent pointer-return truncation. 23 game/asset sites use the same gate |
| F18 | GL | fallback table lands on `{4,1,CORE}` on macOS; GLSL `#version 410 core`; VAO created for Core; no compat/>4.1 entry points. 2.1 compat is **not** enough (GLSL 1.30 min, FBO/blit/MSAA, `GL_DEPTH_CLAMP`) |

---

## 2. Design: the shifted-window address model

### 2.1 Invariant

Let `B = PORT_ADDR_BASE` (compile-time, per platform). Every host pointer that
game code may truncate to 32 bits lives in the window `W = [B, B + 4 GiB)`,
at host address `B + n64addr`. Therefore:

- `(u32)host_ptr` for any `host_ptr ∈ W` yields **exactly today's Windows
  value**. The pointer→u32 direction needs no game-code edits for in-window
  pointers.
- `u32 → host pointer` becomes `B + u32`. This is the only direction that
  changes, and it is funnelled through one chokepoint.
- On Windows/Linux `B = 0`: every chokepoint is an identity, behaviour and
  codegen are unchanged.

### 2.2 N64-space layout inside `W` (window offsets; unchanged from today)

| Range | Content | Host mapping |
|---|---|---|
| `[0x0000_0000, 0x1000_0000)` | segmented DL addresses (never host memory) | none (reserved `PROT_NONE`) |
| `[0x1000_0000, 0x2000_0000)` | cart image + sidecars (`CART_BASE`) | `MAP_FIXED` carve (romdata.c) |
| `[0x4000_0000, 0x7000_0000)` | **image-relative encoding** (§2.4) — virtual, never mapped | none |
| `[0x7000_0000, +8 MiB)` | DRAM V1 | `shm_open` view 1 (dram.c) |
| `[0x8000_0000, +8 MiB)` | DRAM V2 / KSEG0 mirror | `shm_open` view 2 |
| `[0xA000_0000, 0xC000_0000)` | game-thread stacks, 8 MiB + guard page each (replaces `MAP_32BIT`) | `MAP_FIXED` carve (libultra.c) |
| everything else | reserved, unmapped | `PROT_NONE` |

`B` proposal: **`0x1000_0000_0000` (16 TiB)** — reserved cleanly (F7), far
above libmalloc's regions (`0x1..0x8 <<32`, observed) and the mmap hint region
(`0x70_0000_0000`), below `fast3d_ptr_ok`'s `0x8000_0000_0000` bound. Fallback
candidate `0x100_0000_0000`. Item **M1.1** confirms on a second machine and
fixes the constant.

### 2.3 Startup contract

`portAddrInit()` is the **first thing in `main()`** (before SDL, before any
large allocation): `mach_vm_map(task, &B, 4 GiB, VM_FLAGS_FIXED, PROT_NONE)`.
Failure is fatal with a clear message — the same contract as the Windows
build's `0x140000000` load-base check (`main.c:176`). Once reserved, carving
sub-ranges with `MAP_FIXED` is safe (we own the range). No heap-copy
fallbacks on macOS: `romdata` cart map failure is fatal, not degraded.

### 2.4 Chokepoint API — `port/include/port_addr.h` (new)

```c
#define PORT_ADDR_BASE  /* 0 on Windows/Linux; B on PLATFORM_MACOS && PLATFORM_ARM */
/* u32 (N64/"physical") -> host pointer. */
static inline void *portN64ToHost(u32 a) {
    if (a >= 0x40000000u && a < 0x70000000u)          /* image-relative (D131 generalised) */
        return (void *)(portImageBase() + (a - 0x40000000u));
    return (void *)(PORT_ADDR_BASE + (uintptr_t)a);
}
/* host pointer -> u32. In-window: window offset. In-image: 0x40000000 + image offset. */
static inline u32 portHostToN64(const void *p);
/* Cast-site macro for game code (D3x class). Identity semantics at B == 0. */
#define PORT_N64PTR(T, expr) ((T *)portN64ToHost((u32)(expr)))
```

Rewired to it (all in `port/`): `osVirtualToPhysical`/`osPhysicalToVirtual`
(`libultra.c:1442-1443`), `OS_K0_TO_PHYSICAL`/`OS_PHYSICAL_TO_K0`
(`port/shim/PR/os.h:34,37` — subtract/add `B + 0x70000000`), `PHYS_TO_K0`
(`port/shim/PR/R4300.h:25`, `port/shim/R4300.h:14`), fast3d `seg_addr`
(`gfx_pc.cpp:2881-2935` — replace the `mod_hi` block with the image-relative
rule; add `B` to the `< 0x800000` and pass-through returns), the fast3d
range classifier (`gfx_pc.cpp:630-635` — compare `p - B`), `G_MW_SEGMENT`
(`:2324-2327`) and `G_MW_NUMLIGHT` (`:2317`), mixer `osPhysicalToVirtual`
users (`mixer.c:147,152,297`), `piServiceDma` (`libultra.c:1001`),
`dramHostAddrValid` (`libultra.c:909-911`), `romdataIsCartAddr`
(`romdata.c:441-451`), `n64stubs.c:94-107` (`0x70700000` literal).

**Why image-relative reproduces D131 exactly on Windows:** the image base is
`0x1_4000_0000`, so `0x40000000 + (p - image_base) == (u32)p` — the current
truncation result. On Linux (`-Ttext-segment=0x20000000`) `&sym` currently
passes through `seg_addr` untouched; under the new rule it round-trips
through `0x4xxxxxxx` to the same pointer. No behaviour change either way.

### 2.5 Absolute symbols

`dram_syms.s` (3 symbols) and `romassets_<region>.s` (1685 cart symbols) are
generated with `B +` added on Darwin, Mach-O syntax (`.data`, `_` prefix).
Verified viable by F10. The generator (`scripts/gen_romassets.py`) grows a
`--darwin --base 0x...` mode; `B` is defined in exactly two places
(`port_addr.h` and the CMake variable that feeds the generator) with a
`_Static_assert`/CMake check that they agree.

### 2.6 The residue: raw casts in game code

Game code sites that turn a `u32` back into a pointer without going through a
chokepoint are the only thing the model cannot fix by construction. Grep
estimates (heuristic, noisy): 117 `(u32|s32)&sym` in 21 files, ~278
`(T *)obj->field`-shaped casts, 7 `romptr_t`, 5 existing `PORT_PTRADD`. The
authoritative census is the compiler (item **M2.1**): clang's
`-Wint-to-pointer-cast`, `-Wpointer-to-int-cast` and `-Wint-conversion`
(all warnings, none demoted to off) list every site precisely once M0 links.
Each `u32 → pointer` site becomes `PORT_N64PTR(T, expr)`; each
`&image_symbol → u32` site becomes `portHostToN64(&sym)`; in-window
`ptr → u32` truncations are left alone. Every edit is identity at `B = 0`.

### 2.7 What this model deliberately does NOT do

- No PD-style relocatable/offset addressing rewrite of game structures.
- No change to `Gwords {uintptr_t w0, w1}` (already 64-bit-safe).
- No attempt to place the executable inside `W` (F3: not controllable).

---

## 3. Work items

Sizes: **S** ≤1 h, **M** 1–3 h, **L** half-day+. "mechanic" = Sonnet subagent
with the brief below; "integrator" = session model. Budgets are per
dev-process.md §1; on expiry: revert probes, leave the tree buildable, write up.

Common to every item — **READ FIRST:** this doc §2; `docs/porting-notes.md`
(headers); `AGENTS.md` non-negotiables. **CONSTRAINTS:** no game-logic
changes; `src/`/`assets/` edits only where an item lists them and only in the
sanctioned mechanical classes; N64 build (`Makefile`, `tools/`, `rsp/`, `ld/`)
untouched; new findings appended to `docs/dev/findings.md` §F/§H under the
next free `Dxx` (last used at time of writing: D293) and indexed at the top of
§F. **VERIFY** for build-affecting items always ends with
`./build-pc.sh ntsc-final` (or the explicit target-only build the item names).

### Phase M0 — compile and link on macOS arm64 (no runtime expected)

Goal: `./build-pc.sh ntsc-final` produces `build-pc/ge007.*` on this Mac.
`B` is still 0 in this phase (address model stubbed), so the binary will not
boot; the milestone is a clean link + the M2 census becoming available.

| ID | Title | Who | Size | Deps | Files |
|---|---|---|---|---|---|
| M0.1 | CMake: Apple-clang toolchain path | mechanic | M | — | `CMakeLists.txt`, `cmake/*.cmake`, `build-pc.sh`, `docs/building.md` |
| M0.2 | `__x86_64__` → `PLATFORM_64BIT` as the 64-bit-PC gate | mechanic | S | — | `port/include/pc_protos.h`, `port/include/platform.h`, + the 23 game/asset sites listed |
| M0.3 | Darwin mode for generated assembly | mechanic | M | M0.1 | `scripts/gen_romassets.py`, `port/src/dram_syms.s` (→ generated), `CMakeLists.txt` (gen invocation) |
| M0.4 | `#pragma weak X = Y` on Darwin | integrator → mechanic | S | — | `src/libultra/gu/sinf.c`, `cosf.c`, `src/game/objective_status.c`, `lv.c`, `spectrum.c`, `port/src/darwin_compat.c` (new) |
| M0.5 | Header/libc clashes on Darwin | mechanic | M | M0.1 | `port/include/pc_protos.h`, `port/src/pc_netorder.c`, `port/shim/*`, `port/src/{romdata,romconvert,pccg,pcmodels,fs}.c`, `port/src/system.c` |
| M0.6 | fast3d C++ TUs vs libc++ header shadowing | mechanic | M | M0.1 | `port/shim/` (new C++-route shims for `math.h`/`limits.h`/`assert.h`), `CMakeLists.txt` |
| M0.7 | macOS branches: `crash.c`, `system.c` | mechanic | M | — | `port/src/crash.c`, `port/src/system.c` |
| M0.8 | macOS stubs for `dram.c`/`romdata.c`/`libultra.c` low-stack (compile-only) | mechanic | S | — | `port/src/dram.c`, `port/src/romdata.c`, `port/src/libultra.c` |
| M0.9 | Link-check + first `findings.md` batch | integrator | S | M0.1–M0.8 | `docs/dev/findings.md` |

**M0.1 — CMake: Apple-clang toolchain path.**
Recipe: (a) detect clang (`CMAKE_C_COMPILER_ID STREQUAL "Clang"` or
`AppleClang`) and in the `if(NOT MINGW)` block at `CMakeLists.txt:289-298`
emit `-fms-extensions -Wno-microsoft-anon-tag` for clang instead of
`-fplan9-extensions`; drop `-fpermissive` for clang; keep the GCC branch
intact. (b) For clang add `-Wno-error=implicit-int
-Wno-error=incompatible-function-pointer-types` next to the existing
`-Wno-error=` set (`:273-277`); do **not** silence `-Wint-to-pointer-cast`,
`-Wpointer-to-int-cast`, `-Wint-conversion` (they are the M2 census).
(c) `add_definitions(-D_FORTIFY_SOURCE=0)` on APPLE (F16: the N64
`sprintf` prototype vs `__builtin___sprintf_chk`). (d) Host-header shim
derivation at `:165-205`: on APPLE derive from
`execute_process(xcrun --show-sdk-path)` / `CMAKE_OSX_SYSROOT` →
`${SDK}/usr/include/{string,sched,stdlib}.h` instead of
`${_PORT_GCC_DIR}/../include`. (e) `:39-45`: set
`CMAKE_OSX_DEPLOYMENT_TARGET 11.0` when `CMAKE_SYSTEM_PROCESSOR` is
`arm64`/`aarch64` (currently keys off empty `CMAKE_OSX_ARCHITECTURES` →
10.13). (f) `find_program(gcc)` at `:27-37` — prefer `clang` on APPLE and
update the comment (it says clang rejects `inherits`; F11 shows it does not
with `-fms-extensions`). (g) `build-pc.sh`: brew line already right; add a
note that `zlib` is keg-only (CMake's `find_package(ZLIB)` finds the SDK
zlib — verify, and if so say brew zlib is optional). Budget: 6 configure/build
cycles. Verify: `cmake -S . -B build-pc -DROMID=ntsc-final` succeeds; `cmake
--build build-pc --target ge007 -- -k 2>&1 | tee /tmp/m01.log`; report the
distinct remaining error classes (expected: F14 asm, F15 pragma weak, F17
implicit decls, libc++ shadowing, `memfd_create`, `crashDumpThreads`) — those
belong to M0.2–M0.8, not this item.

**M0.2 — `__x86_64__` → `PLATFORM_64BIT`.** Sites (from
`grep -rn __x86_64__ src assets include port`): `port/include/pc_protos.h:34`
(the gate for the whole D38 header — critical, F17); `src/memp.c:66`;
`src/music.c:55,688,711`; `src/game/objecthandler.c:7` (D40 — N64 branch
overruns `.bss` by 12 KB on any 64-bit host); `src/game/initunk_005450.c:41`;
`src/game/rsp.c:276`; `src/game/image_bank.c:170`;
`assets/animationtable_data.h:200-575` (D34); `src/audi.c:10,666,734`;
`src/libultra/audio/load.c:26,200,393,496`; `synthesizer.c:23,125`;
`synsetfxmix.c:22`, `synsetpan.c:22`, `synsetvol.c:22`; `src/save.c:24`;
`port/src/system.c:177` (keep — that one really is x86: `_mm_pause`). Recipe:
replace `defined(__x86_64__)` with `defined(PLATFORM_64BIT)` at each listed
site (spelling change only; every site is an existing, documented port-class
edit); ensure `platform.h` is reachable from those TUs (it is included via
`versioninfo.h`/`-include`? — check; if not, `pc_protos.h`-style
`-include` or add `#include "platform.h"` to `port/shim/bondconstants.h`).
`CMakeLists.txt:217-219` already defines `PLATFORM_64BIT=1` for aarch64 via
`cmake/TargetArch.cmake`. Budget: 2 build cycles. Verify: `grep -rn
__x86_64__ src assets include port` shows only `system.c:177`; build of
`bg.c`, `chrai.c`, `propobj.c`, `front.c`, `boss.c` shows **0**
`-Wimplicit-function-declaration` (was 45–63 each).

**M0.3 — Darwin mode for generated assembly.** Recipe: add
`--darwin` (and `--base 0xHEX`, default 0) to `scripts/gen_romassets.py`:
emit `.data` not `.section .data`; prefix every symbol with `_`; emit `.set
_sym, (base + value)` — 64-bit values are fine (F10). Regenerate
`port/src/romassets_u.s` (and `_e`/`_j` if the generator supports them — note
they are currently absent, `CMakeLists.txt:417-420`). Convert
`port/src/dram_syms.s` into generator output (or a tiny Darwin twin selected
by CMake) with the same `--base`. Wire the CMake invocation (pass
`PORT_ADDR_BASE` from a cache var; default 0 in M0). Keep ELF output
byte-identical when `--darwin` is absent (diff the regenerated file against
git). Budget: 4 cycles. Verify: `nm build-pc/CMakeFiles/.../romassets_u.s.o
| head` shows `A`-type `_`-prefixed symbols; `nm ... | grep -c ' A '` = 1685;
`dyld_info -fixups build-pc/ge007.* | grep -c romassets-symbol-name` = 0 once
linked (M0.9).

**M0.4 — `#pragma weak X = Y` on Darwin.** Integrator first (30 min):
read the five sites (`sinf.c:33-34`, `cosf.c:33-34`, `objective_status.c:162`
+ consumer `chrai.c:41,2538`, `lv.c:208-216,603-606`, `spectrum.c:49-50,266`)
and decide per site the minimal semantics-preserving form under
`#if defined(PORT) && defined(__APPLE__)`: for `sinf`/`cosf` a strong
definition in a **new port file** `port/src/darwin_compat.c`
(`float sinf(float x){return __sinf(x);}` …) so the 25 game TUs keep binding
to Rare's polynomial, not libSystem's (fidelity); for the three game-file
aliases, a `PORT`-gated `#define X Y` or wrapper — record the choice as a
`Dxx` (symbol-aliasing mechanism, ABI class). Then mechanic applies it.
Budget: 3 cycles. Verify: `lv.c`, `spectrum.c` compile; link has no
undefined `objectiveGetStatus_WEAK`; `nm build-pc/ge007.* | grep -E
' T _(sinf|cosf)$'` shows both defined in the executable.

**M0.5 — Header/libc clashes.** Recipe: (a) `ntohl/ntohs`: on APPLE
`<sys/_endian.h>` defines them as macros with `__uint32_t` prototypes;
guard the K&R declarations in `pc_protos.h:54-60` and the definitions in
`pc_netorder.c:24-32` with `#if !defined(__APPLE__)` (the game's own macros
are already `#undef`'d in `port/shim/bondconstants.h:37-38`). (b) K&R
redeclarations spelling `size_t` as `unsigned long long`
(`romdata.c:25`, `romconvert.c:28`, `pccg.c:24`, `pcmodels.c:26`,
`fs.c:18`) → `size_t` (identical on all shipping platforms; hard error the
moment the SDK prototype is visible). (c) `system.c:26` `_POSIX_C_SOURCE
199309L` hides `readlink` on Darwin → add `_DARWIN_C_SOURCE` on APPLE.
(d) Anything else M0.1's log lists under this class. Budget: 3 cycles.
Verify: the listed TUs compile warning-free for these classes.

**M0.6 — fast3d C++ vs libc++.** Recipe: the four `port/fast3d/*.cpp` TUs
fail because `include/math.h`, `include/limits.h`, `include/assert.h`
shadow the SDK ahead of libc++'s `<cmath>`/`<climits>`/`<cassert>` (F16).
Add C++-routed shims in `port/shim/` following the existing pattern
(`port/shim/stdlib.h:16-30`: `#ifdef __cplusplus` → host header by absolute
SDK path via the CMake-generated `host*.h`, else N64 header). Alternative if
that fights libc++: compile the four fast3d TUs with a private include order
(`target_include_directories` on an OBJECT library, SDK first). Budget: 5
cycles. Verify: all four `.cpp` TUs compile.

**M0.7 — macOS branches in `crash.c` and `system.c`.** Recipe (crash.c):
change the `PLATFORM_LINUX` block guard (`:306-473`) to `PLATFORM_LINUX ||
PLATFORM_MACOS`; replace the glibc `uc_mcontext.gregs[REG_*]` reads
(`:344-358, 413-417`) with a `PLATFORM_MACOS && PLATFORM_ARM` variant
reading `uc->uc_mcontext->__ss.__pc/__fp/__sp/__lr/__x[]`
(`<mach/arm/_structs.h>`); keep `backtrace`/`backtrace_symbols`/`dladdr`;
ensure `crashDumpThreads` is defined (it is referenced by
`libultra.c:264`); note in the log that symbolication is
`atos -o ge007 -l <slide>` and print `_dyld_get_image_vmaddr_slide(0)` at
crash time. Recipe (system.c): `sysImageBase()` → `(uintptr_t)
_dyld_get_image_header(0)` on APPLE; `sysGetExeDir()` → `_NSGetExecutablePath`
+ `dirname` (or `SDL_GetBasePath`) instead of `"."`; `$S/` resolution at
`:260` (`/proc/self/exe`) → same helper. Budget: 4 cycles. Verify: both TUs
compile; `nm | grep crashDumpThreads` defined once.

**M0.8 — compile-only macOS stubs (address model lands in M1).** Recipe:
`dram.c`: add a `PLATFORM_MACOS` branch that compiles (`shm_open` skeleton
per F9, addresses still `0x70000000`/`0x80000000` — will fail at runtime,
expected); `romdata.c`: `MAP_FIXED_NOREPLACE` path already `#ifdef`'d — no
change unless the log says otherwise; `libultra.c:417-438`
`portAllocLowStack`: compiles as-is (`MAP_32BIT` exists). Budget: 2 cycles.
Verify: link completes.

**M0.9 — link-check + findings batch (integrator).** Run the AGENTS.md
verification ritual (`/linkcheck`): undefined/duplicate symbols across the
compiled set; record M0's findings as one `findings.md` batch (F11–F17 each
get a `Dxx` row or are folded into one "macOS toolchain" row) and update
`docs/building.md` "macOS: compiles, does not run yet (address model: M1)".

### Phase M1 — the address model in `port/`

Goal: the macOS binary boots to the first frame with `B ≠ 0`, with the
game-code census still pending (expect crashes at un-rewritten cast sites —
those are M2). All items here are `port/`-only.

| ID | Title | Who | Size | Deps | Files |
|---|---|---|---|---|---|
| M1.1 | Fix `B`; write `port_addr.h` + `portAddrInit()` | integrator | S | M0.9 | `port/include/port_addr.h` (new), `port/src/main.c`, `CMakeLists.txt` |
| M1.2 | Rewire OS chokepoints | mechanic | M | M1.1 | `port/src/libultra.c`, `port/shim/PR/os.h`, `port/shim/PR/R4300.h`, `port/shim/R4300.h`, `port/src/n64stubs.c` |
| M1.3 | DRAM double-map + cart map + stacks inside `W` | mechanic | M | M1.1 | `port/src/dram.c`, `port/src/romdata.c`, `port/src/libultra.c` (`portAllocLowStack`) |
| M1.4 | fast3d `seg_addr` / classifier / moveword on `B` | mechanic | M | M1.1 | `port/fast3d/gfx_pc.cpp` |
| M1.5 | Mixer + PI DMA + validity helpers on `B` | mechanic | S | M1.1 | `port/src/mixer.c`, `port/src/libultra.c` (`piServiceDma`, `dramHostAddrValid`), `port/src/romdata.c` (`romdataIsCartAddr`) |
| M1.6 | Absolute symbols regenerated with `B` | mechanic | S | M0.3, M1.1 | generated `.s` via CMake var |
| M1.7 | Boot attempt + triage | integrator | M | M1.2–M1.6 | — |

**M1.1 (integrator).** Confirm `B` on a second Mac if available (run the
F7 probe: reserve 4 GiB `PROT_NONE` at candidates via `mach_vm_map
VM_FLAGS_FIXED`); fix `PORT_ADDR_BASE = 0x1000_0000_0000` (fallback
`0x100_0000_0000`). Write `port_addr.h` per §2.4 with `portImageBase()`
(`_dyld_get_image_header(0)` on macOS; `sysImageBase()` elsewhere — on
Windows this must equal `0x140000000` so the image-relative rule reproduces
D131 exactly; assert it). `portAddrInit()` as §2.3, called first in
`main()`; on non-macOS it is a no-op. Expose `PORT_ADDR_BASE` to CMake
(`-DPORT_ADDR_BASE=` cache var, APPLE default the constant, else 0) so M1.6
can feed the generator; add a `_Static_assert` tying the two.

**M1.2 (mechanic).** Recipe: `osVirtualToPhysical` → `portHostToN64`,
`osPhysicalToVirtual` → `portN64ToHost` (`libultra.c:1442-1443`);
`OS_K0_TO_PHYSICAL(x)` → `(u32)((uintptr_t)(x) - (PORT_ADDR_BASE +
0x70000000))`, `OS_PHYSICAL_TO_K0(x)` → `portN64ToHost(x)`
(`port/shim/PR/os.h:34,37`); `PHYS_TO_K0` likewise (`port/shim/PR/R4300.h:25`,
`port/shim/R4300.h:14`); `n64stubs.c:94-107` `0x70700000` literal →
`portN64ToHost(0x70700000)`. Budget: 3 cycles. Verify: Windows/Linux
semantics unchanged is provable by inspection (`B = 0` ⇒ identity) — state
it; macOS builds.

**M1.3 (mechanic).** Recipe: `dram.c` macOS branch: `shm_open` (unique
name, `shm_unlink` immediately) + `ftruncate(8 MiB)` + two
`mmap(MAP_SHARED|MAP_FIXED)` at `B+0x70000000` and `B+0x80000000` (F9); fatal
on any failure (no fallback). `romdata.c`: on macOS `mmap(MAP_FIXED)` at
`B+CART_BASE` (safe post-reservation), fatal on failure — do **not** take the
heap-copy path on macOS (comment why: window invariant). `libultra.c`
`portAllocLowStack`: macOS branch carves 8 MiB + 16 KiB guard per thread from
`[B+0xA0000000, B+0xC0000000)` with a simple bump allocator + free list;
`pthread_attr_setstack` as today. Budget: 4 cycles. Verify: a debug log line
per mapping with the host address; run `build-pc/ge007 -level_09` far enough
to see "DRAM V1 @0x1000_7000_0000 … cart @ … stacks @ …" (crash afterwards is
expected in M1).

**M1.4 (mechanic).** Recipe (`gfx_pc.cpp`): `seg_addr` (`:2881-2935`) —
the `w1 < 0x800000` branch returns `portN64ToHost(w1 + 0x80000000)`; the
D131 `mod_hi` block is replaced by the image-relative rule (`0x40000000 ≤ w1
< 0x70000000` → `portN64ToHost(w1)`); the final pass-through stays for
full-width host pointers but a `w1 < 0x1_0000_0000` value there means
"in-window N64 address" → `portN64ToHost`. `G_MW_SEGMENT` (`:2324-2327`)
and `G_MW_NUMLIGHT` (`:2317`) same treatment. Range classifier
(`:630-635`): compare `(uintptr_t)p - PORT_ADDR_BASE` against the cart and
DRAM windows. `fast3d_ptr_ok`/`addr_bad` bounds: unchanged (16 TiB <
128 TiB). Budget: 3 cycles. Verify: builds; on Windows semantics unchanged
(identity) — state the argument per site.

**M1.5 (mechanic).** `mixer.c:147,152,297` already call
`osPhysicalToVirtual` → covered by M1.2; check `mixer.h`'s `u32 dramAddr`
ABI needs nothing. `piServiceDma` (`libultra.c:1001`): `memcpy` source from
`portN64ToHost(srcPA)`. `dramHostAddrValid` (`:909-911`) and
`romdataIsCartAddr` (`romdata.c:441-451`): ranges offset by `B`. Budget: 2
cycles.

**M1.7 (integrator).** Boot `-level_09` (the standard sweep level); triage
the first crash against the census (M2.1), which by now exists. Expect the
first failures at `(T *)u32field` sites in game code.

### Phase M2 — game-code cast census and rewrites (the D3x class)

| ID | Title | Who | Size | Deps | Files |
|---|---|---|---|---|---|
| M2.1 | Compiler census | mechanic | S | M0.9 | none (report only) |
| M2.2 | Classify census → work packets by file | integrator | M | M2.1 | `docs/dev/MACOS-ARM64-PLAN.md` (this doc, §3 table) |
| M2.3a–n | Rewrite packets (one per file group, disjoint) | mechanic ×N (parallel) | S–M each | M2.2 | per packet |
| M2.4 | Re-run census; assert zero unclassified | mechanic | S | M2.3 | — |

**M2.1 — census (mechanic).** Recipe: `cmake --build build-pc -- -k 2>&1 |
tee /tmp/census.log`; extract `grep -E 'warning: .*\[-W(int-to-pointer-cast|
pointer-to-int-cast|int-conversion)\]' /tmp/census.log | sort -u` into
`/tmp/census.txt`; also grep `src/ assets/` for `(u32)&`, `(s32)&`,
`romptr_t`, `PORT_PTRADD`; produce a table `file:line | direction (u32→ptr /
ptr→u32 / implicit) | operand kind (field / &global / local / call result)`.
No edits. Budget: 45 min.

**M2.2 — classify (integrator).** Per site decide: **(a)** `u32 → pointer`
where the `u32` holds an N64 address (DRAM/cart/stack) →
`PORT_N64PTR(T, expr)`; **(b)** `&global → u32` (image pointer) →
`portHostToN64(&sym)` (identical value on Windows); **(c)** in-window
`pointer → u32` truncation → leave; **(d)** ROM-serialized field (D3x) →
already handled or `PORT_PTRADD`/`romptr_t` pattern; **(e)** genuine
integer (not an address) → leave. Group (a)+(b) into packets by file so
mechanics never collide (dev-process.md §3); each packet lists exact
`file:line` sites and the replacement. Record the class counts in this doc.

**M2.3 packets (mechanic, parallel).** Per packet brief: FILES = the
packet's files only; recipe = the per-site replacement table; every edit is
one of the two macro forms — no other change; add a one-line `/* D3x/M2:
window-model cast, identity at PORT_ADDR_BASE==0 */`-style comment only
where the file has no adjacent D3x comment already. Budget: 2 cycles per
packet. Verify: packet TUs compile; census diff shows the packet's sites
gone; `./build-pc.sh ntsc-final` green.

### Phase M3 — runtime bring-up

| ID | Title | Who | Size | Deps | Files |
|---|---|---|---|---|---|
| M3.1 | Cocoa main-thread hygiene | mechanic | M | M0 | `port/fast3d/gfx_sdl2.cpp`, `port/src/video.c`, `port/src/input.c` |
| M3.2 | Two Core-profile GL bugs + MSAA clamp | mechanic | S | M0 | `port/fast3d/gfx_opengl.cpp`, `port/src/video.c` |
| M3.3 | First frame → intro → menu → `-level_09` | integrator | L | M1.7, M2.4, M3.1 | triage only |
| M3.4 | arm64 float→int semantics check | integrator | M | M3.3 | `docs/dev/findings.md` |
| M3.5 | Level sweep (21 levels, unattended window) | mechanic (runs) + integrator (triage) | L | M3.3 | `docs/dev/LEVEL-STATUS.md` |
| M3.6 | Weak-memory-ordering audit of cross-thread flags | integrator | M | M3.3 | `port/src/video.c`, `optionsoverlay.c`, `libultra.c` |

**M3.1 (mechanic).** Recipe: remove the render-thread `SDL_PollEvent` pump
(`gfx_sdl2.cpp:311-360`, called from `gfx_pc.cpp:3301`) — the host thread
already pumps (`video.c:502-591`); route Alt+Enter through
`videoRequestFullscreen` (`video.c:298-309`); replace the render-thread
`exit(0)` calls (`gfx_sdl2.cpp:322/348/356`) with a quit request the host
loop honours. Marshal `SDL_SetRelativeMouseMode`/`SDL_ShowCursor`
(`input.c:1227,1256,1310,1313`, reached from render + game threads) onto the
host thread via the existing `winReq*` queue. `SDL_GameControllerUpdate`
(`input.c:622`, game thread) — move to the host pump, snapshot state under
the existing lock. Budget: 5 cycles (Windows/Linux behaviour must be
unchanged — this is a correctness fix everywhere). Verify: builds; on macOS
no `NSInternalInconsistencyException`/main-thread assertions in the log once
M3.3 boots.

**M3.2 (mechanic).** `gfx_opengl.cpp:1271` binds the vector *index* instead
of `.fbo` (cf. correct `:1335`) — fix; `:1328` `glReadBuffer(GL_FRONT)` when
`use_back=false` (`video.c:722`) is undefined on Cocoa → read the back buffer
or the FBO; clamp `gfx_msaa_level` to `GL_MAX_SAMPLES` before `:1187/:1199`.
Budget: 2 cycles.

**M3.4 (integrator).** arm64 `fcvtzs` **saturates** and yields 0 for NaN;
x86 `cvttss2si` yields `0x80000000` for overflow and NaN; MIPS yields
`0x7FFFFFFF`. Sites validated against x86 behaviour: `floorFloatToInt`
(`src/game/math_floor.c:42`, 19 call sites), `FTOFIX32` in `guMtxF2L`
(`include/PR/gu.h:38` — also `long` = 64-bit on LP64), D73/D155/D156 guards
(`src/game/model.c`). Re-read each; where behaviour differs for
out-of-range/NaN inputs, decide whether a port-side helper is needed to
match the x86-validated behaviour (a `port/` change; no game-code edit).
Record as a `Dxx`.

### Phase M4 — packaging, CI, docs

| ID | Title | Who | Size | Files |
|---|---|---|---|---|
| M4.1 | `.app` bundle target + `Info.plist` + `$S/` under `~/Library/Application Support/ge007` when bundled | mechanic | M | `CMakeLists.txt`, `port/src/system.c`, `port/src/romconvert.c` |
| M4.2 | GitHub Actions `macos-14` (arm64) compile job (mirror of the Ubuntu job) | mechanic | S | `.github/workflows/ci.yml` |
| M4.3 | `docs/building.md` macOS section; README "Status"; AGENTS.md build note (currently says MSYS2 only) | mechanic | S | docs |
| M4.4 | Bundle script (`bundle-mac.sh`, mirrors `bundle-win.sh`; reuse `prepare-assets.py`) | mechanic | M | scripts |

---

## 4. Decisions needed from a human

1. **`B` value** — `0x1000_0000_0000` proposed (F7). Needs one more machine's
   probe before M1.1 fixes it. If no second Mac: accept the fatal-on-failure
   contract and revisit if a user report shows the range occupied.
2. **`#pragma weak` handling (M0.4)** touches three game files with a
   `PORT`-gated alias/wrapper. Sanctioned as ABI/linker-mechanism class?
   (Recommendation: yes, documented as one `Dxx`.)
3. **Heap-copy fallback on macOS = fatal** (§2.3). Confirms we never run
   degraded on macOS; a Mac that cannot reserve 4 GiB `PROT_NONE` at `B`
   cannot run the port. (Recommendation: yes; it costs nothing — `PROT_NONE`
   reservations are free.)
4. **M3.1 changes Windows/Linux behaviour too** (removing the render-thread
   event pump). Recommendation: yes — it is an SDL-rules violation on every
   platform; verify Windows once after.

## 5. Risks (ranked)

1. **Census size (M2).** If the compiler census exceeds a few hundred
   `u32 → pointer` sites, M2 becomes the dominant cost. Mitigation: the
   rewrites are mechanical and file-partitioned; run 4–6 mechanics in parallel.
2. **Game code keeping host pointers in `u32` fields *implicitly*** (no cast,
   `-Wint-conversion`): each is a latent truncation today too; the census
   catches them, but classification needs judgement (integrator time).
3. **Pointers reaching game code from host allocations outside `W`** (e.g. a
   port-side `malloc` result handed into a game struct) — invisible to the
   census. Mitigation: M1.7/M3.3 triage; `dramHostAddrValid`-style debug
   assert in `portHostToN64` (env-gated) that logs any out-of-window,
   out-of-image pointer.
4. **arm64 float→int and weak memory ordering** (M3.4, M3.6): subtle,
   non-crashing divergences; needs framediff against the Windows reference.
5. **SDL2 on macOS is `sdl2-compat` over SDL3** (brew default): behaviour
   differences in relative mouse mode / HiDPI are possible; pin to real SDL2
   (`brew install sdl2` gives compat; real SDL2 is `sdl2@2`? — verify in M0.1).
6. **`fast3d_ptr_ok` 47-bit bound** and any other `< 0x8000_0000_0000`
   checks are fine at 16 TiB but would not be at ≥128 TiB — do not raise `B`
   above that without checking.

## 6. Status

| Phase | State | Notes |
|---|---|---|
| Research | done | §1 F1–F18, measured 2026-09-18 |
| M0 | **superseded by #88** | the clang build/toolchain work is replaced by PR #88's GCC-based macOS layer; only D296 + `gen_macho_syms --base` survive (§0b) |
| M1 | **done** | shifted-window address model (D298); self-test ALL PASS on the #88 base |
| M2 | **done** | game-code re-basing sweep complete; **21/21 solo levels boot, render and run crash-free**, including with full controller input |
| M3 | **done (core)** | #88's AppKit main-thread guard; `tools_pc/level_sweep_mac.sh` (crash + rendered-pixel check); the two Core-profile GL nits are cosmetic and parked in `docs/dev/GRAPHICS-BACKLOG.md` |
| M4 | **done (core)** | `tools_pc/bundle-mac.sh` → signed, double-clickable `GoldenEye.app` (+ zip/sha256); `docs/building.md` macOS section + `tools_pc/README.md`. Outstanding: CI for macOS, and a live run of the `.app` from Finder |

**Verified state (2026-09-18).** `build-pc/ge007.aarch64` (Homebrew GCC 16.2)
opens a window, renders, plays music **and sound effects**, and runs every solo
level crash-free:

- `tools_pc/level_sweep_mac.sh` — 21/21, all with non-clear pixels
  (76–92%).
- Full-control sweep (`GE_INPUTSCRIPT`: every button + 8-way stick, 26 s per
  level) — 21/21, with SFX voices allocating on every level.
- Findings D294–D300; D299 (silent SFX) and D300 (stage-unload truncation)
  were both arm64-specific and are fixed.

### Prerequisites to run (easy to miss)

Two things must be in `data/` before the binary will render anything, both
documented in `docs/building.md`:

1. **The ROM** as `data/ge007.ntsc-final.z64` (SHA-1 `abe01e4a…`, matching the
   repo's `ge007.u.sha1`).
2. **The PC asset sidecars** — `data/pcmodels-ntsc-final/` and
   `data/pccg-ntsc-final/`. These are ROM-derived and **gitignored**, so a
   fresh clone has empty directories and the game will look like it has an
   address bug when it is really serving raw big-endian ROM bytes (that is
   finding **D69** reproducing). Generate them once:

   ```sh
   python3 tools_pc/d43_emit.py ntsc-final          # 512 model sidecars
   python3 tools_pc/d69_emit.py ntsc-final          # 25 bg + 27 stan
   python3 tools_pc/d88_emit.py ntsc-final --regen  # + 21 stage-setup
   ```

   This cost a detour during M2: the `bg.c` big-endian-header crash looked like
   an un-rebased pointer but was the missing sidecars. PR #88's author ran the
   same three passes before their 1,500-frame `-level_09` run.

### Where the boot is (2026-09-18, branch `macos-arm64-gcc`)

`./build-pc/ge007.aarch64 -level_09`, ROM `data/ge007.ntsc-final.z64`
(SHA-1 `abe01e4a…`, matching the repo's `ge007.u.sha1`):

- ROM load, config, EEPROM, GL 4.1 core, audio, input, threads, VI, timers — OK
- language banks, animation tables, `texReset`/`texLoad`, `gimgSync…` — OK
- faults in `bg.c` `load_bg_file` (level geometry) — the next M2 site

M2 batches so far (all `#if defined(PORT)` and identity at
`PORT_ADDR_BASE == 0`): the mempool boundary; `language.c` `g_LangBanks`;
`initanitable.c` `expand_ani_table_entries`; `initactorpropstuff.c` anim
groups / `ANIM_PTR`; `model.c` `bitDescriptors`/`bitStream`; `image_bank.c`
`globalbank_rdram_offset` (structural, ~43 sites at once) + `texSetBitstring`;
`image.c` `texLoadFromDisplayList`; `bg.c` `BG_SEG_TO_PTR`/`ptr_bg_data`
(**under review** — the fold's value depends on the stack address, which
differs between Windows and the macOS window, so it needs a careful look).

### The M2 census is a checklist, not a scoreboard

The clang census is ~474 game-code rows (`-Wint-conversion` 253,
`-Wpointer-to-int-cast` 122, `-Wint-to-pointer-cast` 54,
`-Wint-to-void-pointer-cast` 35, `-Wvoid-pointer-to-int-cast` 10). Re-basing
edits *add* explicit `u32 → pointer` conversions, so the raw count can rise
while progress is made, and one structural fix can clear dozens of rows. The
honest progress metric is boot-path reach.

### Next

1. Finish the `bg.c` level-geometry re-basing (the current fault), then keep
   triaging `-level_09` until a frame renders.
2. Refresh §1/§3 for the #88/GCC base (the M0 rows elsewhere in this doc are
   historical).
3. M3: the two Core-profile GL bugs (`gfx_opengl.cpp:1271` binds the FBO
   index instead of `.fbo`; `glReadBuffer(GL_FRONT)`), the MSAA clamp, then
   the level sweep and the arm64 float→int / memory-ordering checks.