AArchX Atlas

This page uses about twenty words that every systems programmer takes for granted and nobody else has a reason to know. Here they are, in the order they build on each other. If you know Python or JavaScript and have used a Linux shell, you have everything you need.

What a program actually is

machine code, instruction

A program on disk is not the source you wrote; it is a long list of instructions — tiny operations the chip performs directly: "add these two numbers", "copy 8 bytes from this address", "jump to that spot if the last result was zero". Each is a few bytes. Your Python code is turned into these by the interpreter as it runs; a compiled C or Go program is turned into them once, ahead of time, and the file is the instructions.

CPU, x86-64, arm64

The chip that executes instructions. Different chip families understand different instruction languages. Intel Macs (2006–2020) speak x86-64; Apple silicon (M1 and later) speaks arm64. They are as different as two human languages — an x86-64 program is gibberish to an arm64 chip. That single fact is the reason this project exists.

register

A CPU has a handful of named, ultra-fast storage cells — sixteen general ones on x86-64 (rax, rdi, rsp…), thirty-one on arm64 (x0–x30). Nearly every instruction reads or writes registers; memory is where data lives when it is not being worked on. Think of them as the variables the chip can touch without a memory access.

flags

A few bits the CPU sets after arithmetic — was the result zero, negative, did it overflow — that the next conditional jump reads. x86 sets six of them after almost every instruction; arm64 sets four and only when asked. Faking x86 flags cheaply on arm64 is a recurring theme.

How a program lives in memory

process, thread

A process is one running program with its own memory. A thread is one line of execution inside it; a process can have many threads working at once on the same memory. In Go terms, roughly a program versus its goroutines — except OS threads really do run in parallel.

address, address space

To a process, memory is one enormous numbered byte array, and an address is an index into it — 0x7ff8033d7000 is just a big number naming one byte. Each process has its own private numbering, its address space; the same number means different bytes in different processes.

page

The operating system hands out and protects memory in fixed-size chunks called pages. Intel Macs used 4 KB pages; Apple silicon uses 16 KB. A program built for 4 KB pages asks for things a 16 KB machine cannot literally do, which is a whole stage of this atlas.

stack, heap

Two regions of a process's memory. The stack grows and shrinks with function calls — each call pushes its return address and local variables, each return pops them. The heap is where malloc hands out long-lived memory.

fault, signal

Touching an address you may not touch (unmapped, or read-only) makes the CPU stop the instruction and tell the operating system, which tells the process through a signal (SIGSEGV, SIGBUS). Programs can catch signals. ocerz relies on this constantly: it deliberately protects memory so that a fault tells it something happened.

The operating system's side

kernel, syscall

The kernel is the core of the operating system: it owns files, memory, processes and devices. A program cannot touch those directly; it asks, using a special instruction called a system call (syscall) — "open this file", "give me 1 MB", "start a thread". On macOS there are two families: the Unix-style BSD calls, and Mach, an older message-passing interface where you send a message to a port and get a reply. Both appear in this tree.

executable file, Mach-O

The file format of a macOS program or library (Linux has ELF, Windows has PE). It holds the instructions, the data, and a table of load commands that tell the loader what it needs — including which libraries. A fat or universal file holds one copy per chip type, called slices; on macOS 27 most Apple-supplied files carry only an arm64 slice.

library, linking, loader

A library is code shared by many programs — libSystem is macOS's C library plus threads, sockets and more. Linking is connecting a program's references ("call printf") to the library's actual code. When that happens at run time, the program is dynamically linked and the piece of the operating system that does it is the loader — dyld on macOS, ld.so on Linux. On macOS, every real program is dynamically linked.

shared cache

Apple pre-combines every system library into one enormous file at fixed addresses, so the loader maps one file instead of hundreds. The x86-64 version of it is what cache mode uses — and it ships as part of Rosetta.

framework, Objective-C

macOS's libraries above the C level — Foundation, AppKit, Metal — are called frameworks, and most are written in Objective-C: an object-oriented language whose method calls are messages looked up by name (a selector) at run time. Its runtime (libobjc) keeps the tables of classes and methods, and it talks to the loader constantly. Newer frameworks are in Swift, which is the project's biggest coverage gap.

Running one machine's programs on another

emulation, interpretation

Reading the foreign program's instructions one at a time and doing, in your own code, what each one would have done. Simple, exact, and about thirty times slower than the real chip. ocerz's interpreter is this.

translation, JIT

Converting a run of foreign instructions into equivalent native instructions and then running those. Done ahead of time it is a compiler; done while the program runs, on demand, it is a JIT ("just in time"). ocerz's JIT translates x86-64 into arm64 a block at a time and caches the result.

guest, host

The words this whole page hangs on. The guest is the Intel program and everything it believes: its addresses, its registers, its idea of the kernel. The host is the real arm64 machine ocerz runs on. Every mechanism in ocerz is a place where guest and host disagree and something has to give — a guest address becomes a host address, a guest syscall becomes a host syscall with translated arguments, a guest register lives in a host register. Whenever a sentence here says "guest", read "what the program thinks"; "host", read "what is actually there".

Rosetta 2

Apple's own translator, built into macOS since 2020, and the thing ocerz stands beside and — once Apple removes it — in for.

byte for byte, bit for bit

Exactly equal output, compared as raw bytes. Used here about the tests: the interpreter and the JIT must produce identical bytes, not "the same answer".

New to words like instruction, syscall or guest? The primer before this stage defines each one in a paragraph.

An Intel Mac program is a Mach-O file full of x86-64 instructions that expects three things from the machine: a CPU that executes those instructions, a kernel that answers its system calls, and a loader that puts the system libraries it links against into its address space. On Apple silicon none of the three exist for it. ocerz fakes all three, in one process, so the program cannot tell.

If you know Linux: this is the job qemu-user does for foreign binaries (with binfmt_misc), and the job Apple's Rosetta 2 does on macOS. ocerz is the open one, and the one whose native mode is designed for the day Rosetta is gone.

Two axes you will see everywhere

Think of the two engines as two ways to follow a recipe. The interpreter reads each line aloud and does it — slow, but it never skips a step, so it is the reference. The JIT reads the whole recipe once, writes it out in the cook's own shorthand, and from then on cooks from the shorthand. The differential gate is two cooks who must produce the identical dish from both versions.

Cache mode vs native mode is a hotel. An Intel program packs a list of what it needs from the hotel — libSystem, Foundation, AppKit. Cache mode is a hotel that still stocks the Intel versions of everything (Apple's shared cache). Native mode is a hotel that stocks only arm64 versions and puts an interpreter at every counter: the guest asks in x86, the interpreter relays it to the arm64 staff, and hands back the answer. Apple is about to stop stocking the Intel versions.

The shape of the tree

65,305 lines of C and assembly in 29 files, flat, one directory, a 60-line Makefile. Sizes matter: jit.c alone is 17,509 lines, a quarter of everything. That is a chosen cost, not drift.

The best way to hold the whole system in your head is to follow one launch from the shell to the first frame on screen. Every stage after this one zooms into a step of this path.

What happens at each step

1. main.c parses flags (-native, -cache, -no-jit, -path), applies Wine defaults, and asks ocerz_peek_dynamic one question: does this binary link libraries at all? A static binary (the guest test programs) goes to loader.c and a plain offset arena; everything real is dynamic and goes to dyld.c. Since 2026-09-23 a binary with no x86-64 slice is told apart here — "it is not an Intel program" — instead of dying as unreadable.
2. ocerz_dyld_run reserves the guest address space (identity mode: guest addresses are host addresses, Stage 4) and, in cache mode, maps the shared cache (cache.c). On macOS 27 that cache lives inside the Rosetta cryptex.
3. Loading the image. select_slice picks the x86-64 slice of a fat file; segments are copied into the arena; each LC_LOAD_DYLIB is resolved — a hit in the cache costs nothing (the cache is already mapped), a dylib on disk becomes a DynImage in g_dimgs.
4. Fixups. Chained fixups or classic binds: every pointer the linker left symbolic is written with a real address. Thread-local variables get their descriptors rewritten (two layouts exist; Stage 6).
5. The initial stack is laid out exactly as XNU's exec path does it, because libSystem finds apple[] by walking off the end of envp — a contract, not a convenience.
6. The initializer phase runs libSystem's initializer, then every library's +load and constructors in dependency order. This is the most invariant-laden code in the tree (Stage 6); getting the order wrong fails far away from the cause.
7. ocerz_vm_call builds a guest frame and enters main. From here the thread runs guest code and only comes back to C at syscalls, faults, and untranslated instructions.

If you know Linux: steps 2–6 are what ld.so does for a dynamic ELF binary, and step 5 is what execve does before it. ocerz has to be both, because the real dyld is an x86 program too and there is nobody to run it.

Picture the loader as a stage crew before a play. Step 3 carries the set pieces onto the stage (segments into memory). Steps 3–4 fetch the props the script names from the prop house (libraries) and tape the cue sheet to every entrance so each actor knows where to go (fixups: rebase = "we're on stage B tonight, shift every mark", bind = "the prop the script calls sword is on that table"). Step 5 lays out the programme exactly as the audience expects it (the initial stack). Step 6 is the warm-up, in a strict order — the orchestra tunes before the singers rehearse. Only then does the curtain rise (step 7, main).

Static vs dynamic is packing for a trip. Static: you packed everything, the suitcase is heavy, you need nothing from the hotel — that is a Go binary, and it is ocerz's guest test programs. Dynamic: you packed a list and are counting on the hotel to have a hair dryer — that is a Python script and its imports, and it is every real macOS program.

Where to look

• src/main.c — 280 lines, read all of it; it is the table of contents of a launch.
• src/dyld.c prose block, then ocerz_dyld_run top to bottom; skim the calls, not their bodies.
• src/stack.c — 137 lines; the contract is the comment block.

Three layers, and the contract between them is one struct.

If you know Python: decode.c is the parser producing an AST node; interp.c is CPython's eval loop, a big switch that does exactly what each node says; jit.c is PyPy — it compiles hot straight-line runs to machine code and keeps them in a cache keyed by where they came from.

The interpreter (the oracle)

One function, ocerz_interp_step, executes one instruction against an OcerzCPU — the struct holding all sixteen general registers, the flags, the xmm registers, the instruction pointer (cpu.h; its field order is load-bearing because the JIT reaches into it at fixed offsets). It is slow and it is right. flags.c is the bit-exact specification of the x86 flags; the JIT's cleverer flag handling must agree with it, and the differential gates check that it does.

The JIT (the engine)

A block is a straight run of instructions ending in a branch, call or return. The JIT translates a block into arm64 words appended to a 1 GB MAP_JIT arena, records it in a hash keyed by guest address, and jumps into it. The next time the guest reaches that address, no translation happens. The tricks that make the translated code fast are Stage 3's subject; three ideas belong here:

• Register pinning. In pin class 3 (the default) every one of the sixteen x86 registers lives permanently in an arm64 register — rdi in x28, rsi in x27, and so on — and xmm0–15 live in v16–v31. Nothing is loaded or stored just to execute an instruction. Because every block shares this one layout, blocks can jump directly into each other's bodies.
• Analogy: a chef's mise en place. Every ingredient is already in a bowl within arm's reach, so no step of the recipe begins with a walk to the pantry. And because every station in the kitchen is laid out the same way, a cook can move from one station to the next mid-recipe without looking.
• Lazy flags. x86 sets six flags after almost every instruction; computing them costs more than the instruction. flags_live.c knows which flags each instruction reads, so the JIT computes only what a later instruction will consume, and fuses cmp+jcc into one arm64 compare-and-branch.
• Analogy: a restaurant that only totals the bill when someone asks for it. Every dish "sets the flags" — but if nobody looks at the total before the next round, why add it up? The JIT keeps the receipts (a deferred-flags record) only when it cannot prove the next block will never ask.
• Fault recovery. When translated code faults (a guest bug, or a page ocerz deliberately protected), the fault happens at an arm64 address, but the guest must see exact x86 state at an x86 address. vm.c's crash_handler and the JIT's recovery recipes reconstruct it. This is the subtle part of the whole tree.
• Analogy: a flight recorder. The plane (translated arm64) crashed at some GPS point; the report must say exactly which line of the flight plan (x86 instruction) it was on and what every gauge read. The recipes are how the recorder reconstructs the gauges from the wreckage.

Once main starts, a thread lives inside translated blocks and comes out only when it must. Coming out is called a trip, and most of the performance work is about avoiding trips or making them cheap.

The mechanisms, each with the problem it solves

If you know Go: a trip is a goroutine switch that also throws away the CPU's branch history. Chains are direct calls the compiler resolved; a RAS miss or a dropped chain is an interface call through a lookup table where a direct call would do.

The numbers from 2026-09-22, as a worked example

Brawlhalla's main thread was pegged at 100.8% of a core. The attributed profile said: 42% in instruction bodies, 26% in prologues and epilogues (trips), 11% jcc, 8% returns. Three fixes, in order: return misses no longer exit through the epilogue (+33–48% throughput); veneers made every chain activate (prologue+epilogue fell to 9%, the core dropped to 71% while doing 60% more work); constant-address memory accesses lost a 7-word guard (+13% work per second). Each one was found by measurement, and each one is a mechanism in this stage.

The guest has addresses; the host has addresses; they are not the same space. Everything about memory in this tree follows from how one maps to the other.

The address map is a hotel's room numbers versus the building's floor plan. The guest knows rooms by number (guest addresses); the building has physical positions (host addresses). Identity mode: the room number is the position — no lookup at all. Offset mode: every room is on a floor that starts at some fixed offset — one addition. Low shadow: two wings with their own numbering, and every visit first checks which wing you meant — the expensive one. The arena is renting the whole floor up front so nobody else's luggage ever ends up in the guest's rooms.

The 4 KB / 16 KB problem

Intel Macs used 4 KB pages; Apple silicon uses 16 KB. A guest may protect, map or unmap a 4 KB range that is a quarter of a host page. mem.c therefore tracks slots — 4 KB pieces inside each 16 KB host page — with their own owner and protection, and the host page's real protection is the union of its four slots. Consequences: guest protection changes resolve on 16 KB boundaries; a file is mapped directly only when its offset and guest address agree modulo 16 KB; and any path that hands a guest address straight to the kernel (a forwarded Mach vm_map) can destroy the neighbouring 12 KB unless the fragments are saved and restored around the call. That last one cost Safari a Swift precondition failure nineteen million instructions after the damage.

Slots: one key per room, but the locks are per floor. The guest wants to lock a single room (a 4 KB page); the building can only lock a whole floor of four rooms (a 16 KB host page). So mem.c keeps its own ledger of which of the four rooms are meant to be locked and sets the floor lock to the strictest of them — and any request that bypasses the ledger and talks to the building directly can lock, or wipe, the neighbours by accident.

Two guards the JIT emits around a memory access

• The commpage guard. The x86 commpage — a kernel-provided page of timers and feature bits at 0x7fffffe00000 — cannot exist there on an arm64 kernel, so ocerz keeps its own and redirects accesses to it. Every access whose address is not provably a stack slot used to compare against that range at run time (7 words). For a rip-relative or absolute operand the address is a constant, so since 2026-09-22 that is decided at translation time.
• Analogy for the commpage guard: mail forwarding for one address that moved. Every letter used to be checked against the forwarding card at the post office. If the address is printed on the envelope (a constant), you can check it once, when the envelope is written.
• Ordered mode. An x86 CPU promises stronger memory ordering (TSO) than arm64. A single-threaded program runs in plain mode; the first thread, fork or shared mapping switches the process to ordered mode for good, where scalar loads and stores use acquire/release forms — and those fault on an access crossing a 16-byte granule, hence a small alignment test before each. Measured cost on the game: about 5%.
• Analogy for ordered mode: a shared kitchen. With one cook, put dishes down wherever, whenever. The moment a second cook walks in, a house rule applies to everyone for the rest of the night: tap the counter before you set anything down, so nobody grabs a half-plated dish. It slows every cook a little, and you cannot revoke a rule some cooks have already stopped following.

If you know Linux: mem.c is a tiny mm/: it keeps the VMA-like region table and decides what to mmap/mprotect on the host. The slot table is what you would need if the kernel's page size were four times your process's.

When guest code executes syscall, the JIT trips to ocerz_handle_syscall. Three classes arrive: BSD calls (class 2: files, sockets, memory, processes), Mach traps (class 1: ports, messages, threads), and machdep. Most are forwarded to the real kernel — but not blindly.

The syscall table is a switchboard operator with an index card per extension. A card says how many arguments the call takes and which of them are addresses the guest wrote down in its room numbers, so the operator can translate them to the building's before putting the call through (passthrough). Some cards say "the concierge answers this one himself" (intercept) — because the building's honest answer would be wrong for this guest, as with vm_region. And a Mach message is a letter the operator opens on the way back, rewriting the reply into the guest's room numbers before handing it over.

Spawning a child is hiring an interpreter for the new arrival — unless the new arrival already speaks arm64, in which case sending an interpreter along would only get in the way. That is the rule that landed on 2026-09-23.

What the intercepts have to fake

• Memory calls (mmap, mprotect, shmat) go through mem.c, because the host kernel's view of ocerz's arena is not the guest's view. A Mach vm_region reply is rewritten to say what the guest declared, not what the host has — Electron checks that and executes int3 if __DATA_CONST is not read-only, which is why Discord's renderers died until 2026-09-22.
• Processes. posix_spawn and execve of an Intel binary rewrite the child to ocerz -path child -- argv… with the mode and bases inherited through the environment. A child with no x86-64 slice runs natively, as Rosetta would run it.
• Signals are delivered at guest instruction boundaries with an exact x86 frame; the sigaction struct has different in and out layouts (a real bug once).
• Threads and workqueues. Each guest thread is a host thread running its own OcerzCPU. libdispatch's workqueue threads are bridged to the host's — without that, the first dispatch_sync in any Cocoa app parked its main thread forever.
• Identity. proc_pidpath of the own pid answers the program, not ocerz; sysctl.proc_translated answers 1, so programs take the same compatibility paths they take under Rosetta.

If you know Linux: read this file the way you read strace output. OCERZ_SYSFAIL=1 prints the failures a healthy program almost never earns (ENOMEM, EFAULT), and -strace prints everything.

Apple ships every Intel system library prelinked into one file, the dyld shared cache, with every library at a fixed address inside it. ocerz maps that file and the libraries simply exist. What it must still do is everything the real dyld would have done around them — and answer the questions the libraries ask dyld at run time.

The shared cache is a library whose books were all pre-shelved on one floor, in fixed positions. Cache mode does not fetch books one at a time; it opens the floor and every book is already where its catalogue number says. dyldapi.c is the librarian's desk — the books themselves walk up and ask "how many books are on the floor?", "which book is this page from?", "tell me when a new one arrives". A librarian who forgets to list a book that is plainly on the shelf is exactly the GPU bug: Metal asked for the driver's book and was told there was none.

The initializer phase and its five invariants

After libSystem's initializer, run_init_phase walks the dependency graph bottom-up and, per image, delivers the Objective-C load notification and runs the constructors. Each rule below was learned from a real failure, and each failure surfaced far from its cause:

1. Upward links are not ordering edges — they declare the back edge of a cycle. Follow them for membership, never for order (and still initialize them, at the end).
2. Prune on already-done images, or libc++abi's walk descends through libxpc into Foundation.
3. Load notifications and initializers interleave per image; two global phases put the wrong things first and blew the stack inside malloc.
4. The eager set is closed under dependencies.
5. Decode the new dylib_use_command flags, where upward and delay-init live now; reading only the command type pulled 532 images into CoreFoundation's subtree.

The initializer order is seating a dinner party where some guests must be seated before others. Dependencies sit first. An upward link is a guest saying "I know her, but do not make me wait for her" — you follow the acquaintance to decide who is invited, never to decide who sits first. Interleaving means each guest is introduced (+load) and then seated (initializer) before the next, not everyone introduced and then everyone seated. Every one of the five rules was learned from a party that went wrong.

Thread-locals and Objective-C

Thread-local variables have two descriptor layouts (classic on disk, packed in the cache); reading the wrong one aliased every thread-local in an image. Objective-C needs categories attached to classes in late-loaded images, and — the 2026-09-22 lesson — an image dlopened out of the cache must join the image list after libobjc has mapped it, or libobjc treats it as already handled and drops its categories.

Analogy for TLV: a coat check ticket per guest — every thread gets its own coat, and the ticket says where it hangs. Two ticket formats exist; read a packed ticket as a classic one and every guest is handed the same coat.

If you know Linux: the shared cache is prelink taken to its conclusion; dyldapi.c is the part of ld.so that answers dl_iterate_phdr, dladdr and the loading hooks — except here the libraries were built to talk to Apple's dyld through an object, and ocerz has to be that object.

Native mode maps no shared cache. The program still links /usr/lib/libSystem.B.dylib, Foundation, AppKit — so ocerz builds each of them, on demand, as a real x86-64 Mach-O in memory whose every export is twelve bytes: load my id, jump to the bridge. The program's own code runs through the same decoder and JIT as always; only the universe it binds against has changed.

Native mode is an embassy. The guest walks up to what looks like the Intel library's front desk (the synthesized library: a facade, every door leads to a booth). Behind each door sits an interpreter with a phrasebook (the API database: how this exact request translates), who rearranges the sentence into the other language's grammar (abi.c: registers to a frame, structs reshaped) and relays it to the real arm64 official (the host framework). A "stub" is a door with a sign reading not yet staffed. Callbacks are the guest leaving a phone number: the official cannot speak x86, so the embassy keeps 65,536 numbers that all ring an interpreter who fetches the guest.

The parts

If you know Python or Go: this is an FFI — ctypes, or cgo — built at the scale of an entire operating system's frameworks, with the bindings written as data files instead of code, and with the extra twist that the "foreign" side is the process's own frameworks.

The tree is kept honest by one command and a few rules. make check runs the gates in order and takes about twenty minutes; nothing is committed until it is green.

The gates are two accountants who must produce the same totals. One (the interpreter) works slowly with a pencil and a printed rulebook; the other (the JIT) uses every shortcut she knows. The goldens are the answer key from a real Intel machine. If the pencil matches the key and the shortcuts match the pencil, the shortcuts are right — for every ledger you gave them. A ledger you never gave them proves nothing, which is why real programs keep being added.

If you know git: "gate before every commit" is a pre-commit hook that takes twenty minutes; "a test that pins every change" is refusing to merge a fix without the regression test in the same commit; and the commit subject stating the rule is writing the message for the person running git blame in a year.

The rules, and why each one exists

• Every behavioural change gets a test that pins it, named in the commit message. A fix without a test is a fix that can silently return.
• Gate before every commit, then commit code and tests, then a separate tests: rebuild unit binaries commit, because the test binaries are tracked.
• No inline comments; one prose block per file, present tense. The why goes in the commit message and the file's prose. For a reader without C, that prose block is the whole point: each file explains itself in paragraphs before the first line of code.
• Commit subjects state the rule, not the activity: "jit: a chain that cannot reach goes through a veneer instead of being dropped" tells you the new law of the system.
• The README must stay wholly true. A row measured on an older macOS says so.

Ways a gate can lie

macOS has no timeout, so a sweep that used it "passed" everything; a benchmark binary in the wrong directory becomes a slow extra test case; a stale object file turns the i386 gate into a measurement of an older tree; the dynamic suite flakes under load, so nothing else runs while a gate runs. Each of these was found by being burned.

About 290 OCERZ_* environment variables exist. They are not ad hoc; there are three families, and they are how this codebase is debugged.

The NO_* switches are git bisect over features instead of commits. Turn one optimization off; if the symptom vanishes, the bug is inside that optimization. PERFSTAT is the car's dashboard — it will not tell you why the engine is loud, but it tells you the RPM, the temperature and the gear, and the gear is usually the answer. sample is walking the factory floor: count only the people with tools in their hands, not the ones standing around holding a clipboard (parked threads). kill -INFO two hundred times is asking every worker "what are you doing right now?" every tenth of a second.

PERFSTAT, line by line

PERFSTAT t=60.1s blocks=372106 static_insns/blk=8.51
  block_execs=27796591150 (462166628/s)  jit_step/cache_lookup=87149024 (1449004/s)
  avg EXECUTED insns per block = 11.89   insns/s = 5496038395
  HOTBLOCK # 1 rip=0x8027f67d10 execs=255960085 insns=20 words=209 …
  SLOWOP # 1 imul  3975959  23.23% of slow  (0.01% of ALL)
  RAS misses=883386978 (stale=883385785)  align-hotpatches=2832  ras_slots=0/262144
  CHAIN activated=635725 veneered=40697 out_of_range=0 (0.00% dropped)

• blocks translated so far; static_insns/blk their average length.
• block_execs/s how many blocks ran per second — the "work" rate; insns/s the same in guest instructions. At a saturated core these are the throughput; once the thread has headroom they measure how much the program chose to do.
• jit_step/cache_lookup trips that reached the C dispatcher. Judge it as a ratio to block_execs.
• HOTBLOCK the busiest blocks: address, executions, length, and words — arm64 instructions emitted, whose static count includes miss paths that rarely run.
• SLOWOP instructions the JIT hands to the interpreter, ranked. "% of ALL" is what matters; 0.01% is nothing.
• RAS misses returns that missed the host return stack (stale = the entry was there but wrong or gone). 36 million a second was the game's problem; 11 million after the fixes, and now cheap.
• CHAIN edges patched, edges patched through a veneer, edges dropped for distance. Dropped must read 0.

The other three instruments

• sample <pid> — the host profiler. It counts parked threads as fully as running ones, so keep only leaf frames and drop the blocking syscalls; ocerz's own dispatch_bsd_at/dispatch_mach leaves are parked threads, not hot code. Leaf addresses in JIT code map onto JITDIS_BRIEF's block table to give cycles per prologue, epilogue, instruction and miss path.
• kill -INFO <pid> — ocerz dumps every guest thread: its x86 rip, the syscall it is blocked in, a return-address chain. Two hundred of them at 0.1 s is a guest-level PC sampler for free.
• The probe ladder — for a compatibility failure, write the smallest C program that asks the next question down: which CGL call fails → which renderer is missing → does Metal see a device → does IOKit answer the same as native → does the driver bundle load and its symbols resolve → does objc list its classes → is the image in the dyld list. Each step halves the search; the native arm64 control, not just Rosetta, is what rules out red herrings.

Every fix that landed on 2026-09-22 followed the same shape — symptom, measurement, mechanism, fix, test — and each one lives in a stage of this atlas. Read them as the model in motion.

The method, stated once

1. Reproduce in the smallest program that shows it, under ocerz and under Rosetta or native — the control is what turns a guess into a fact.
2. Measure with the instrument that names the mechanism (Stage 9), never with a hypothesis.
3. Fix the mechanism, not the symptom; document the why in the file's prose and the commit message.
4. Pin it with a test that would have failed before; gate; commit.

guest / host

The x86 program and its view of the world / the arm64 machine and ocerz's view. g2h maps one to the other. ≈ the traveller and the country: the traveller's expectations versus what is actually there.

block

A straight run of x86 instructions ending in a branch, translated as one unit and cached by its address. ≈ one paragraph of a recipe, up to the next "then go to…".

chain

A patched direct branch from one block's exit into the next block's body, so no C runs between them. ≈ a connecting door between two hotel rooms.

trip

Any exit from translated code back to the C dispatcher: syscall, unchained edge, slow op, fault, interrupt. Costs the epilogue, the dispatcher and the prologue, and wipes the host return stack. ≈ going back down to the lobby between rooms — and the bump that knocks the bookmarks off the table.

dispatcher

The C loop (ocerz_vm_run_cpu → ocerz_jit_exec_one) that finds or translates the block for the current rip. ≈ the lobby desk that finds your next room, or has it built if it does not exist yet.

pin class

The register-assignment convention a block was built under. Class 3 pins all sixteen guest registers permanently, which is what makes body-to-body chaining legal. ≈ the kitchen's station layout; class 3 means every station is laid out identically.

RAS

Return-address stack: {guest return, host continuation} pairs pushed at a call so a ret can branch straight to the right body. Kept on the host machine stack with real bl/ret. ≈ the stack of bookmarks for "go back to where I was".

PSC / IC

Per-site cache / inline cache: a few {target, body} entries kept next to an indirect branch site, then an inline hash probe, before tripping. ≈ speed-dial at one phone.

veneer

A 16-byte ldr; br; address stub in a pool near the source block, used when a chain's b cannot reach its target. ≈ a relay runner for a door too far to reach in one stride.

superblock / flip

A block translated past forward branches with side exits; flipping retranslates it following a taken side that proved hot. ≈ paving past the fork; rebuilding the road when traffic turns the other way.

lazy flags

Computing only the x86 flags a later instruction will read, using the def/use table in flags_live.c. A deferred-flags record is stored at a block edge when the next block might read them. ≈ totalling the bill only when someone asks for it.

slow op

An instruction the JIT declines to encode; the block trips and the interpreter executes that one step. ≈ a step the shorthand cannot express, so the cook reads that one line aloud.

arena

Either the guest memory reservation (mem.c) or the 1 GB MAP_JIT region holding translated code (jit.c); context tells which. ≈ renting the whole floor up front and handing out rooms yourself.

slot

A 4 KB guest page inside a 16 KB host page; the unit mem.c tracks ownership and protection in. ≈ one room of the four behind a single floor lock.

identity / offset / low shadow

The three guest→host maps (Stage 4). ≈ room number equals position / one fixed offset per floor / two wings, check which first.

commpage

The kernel-provided page of timers and feature bits at a fixed x86 address; ocerz keeps its own and redirects accesses to it, hence the guard. ≈ the notice board that moved; every visit is forwarded.

ordered mode / TSO

The memory model x86 programs rely on; entered for good at the first thread, fork or shared mapping; loads and stores then use acquire/release forms. ≈ the shared-kitchen rule that applies to everyone once a second cook arrives.

shared cache

Apple's single prelinked file of every x86-64 system library at fixed addresses; on macOS 27 it lives inside the Rosetta cryptex. ≈ a library floor with every book pre-shelved at a fixed position.

closure

The set of images reachable from the main executable through its load commands — also the list the dyld API reports as "loaded images". ≈ the catalogue of what is on the floor.

upward dependency

A load command declaring the back edge of a dependency cycle; followed for membership, never for initialization order. ≈ "I know her, but do not make me wait for her" at the dinner party.

init phase

The dependency-ordered run of every image's +load and constructors before main. ≈ the seating order.

TLV

Thread-local variable; its descriptor has two layouts (classic on disk, packed in the cache). ≈ each guest's coat-check ticket.

DynImage

The loader's record of an image loaded from disk (or synthesized); the cache's images have no DynImage. ≈ a book brought in from outside the library and given a card of its own.

vdylib

A synthesized x86-64 system library whose exports are doorways into the bridge (native mode). ≈ the embassy's facade of the Intel library: every door is a booth.

API database

The .api files describing how each synthesized export crosses: function, data, var, special, stub, shape, struct, inplace. ≈ the interpreter's phrasebook.

bridge / crossing

The path from a guest call of a synthesized export to the real arm64 function and back, including argument placement between the two ABIs. ≈ the interpreter relaying a request to the arm64 official and back.

trampoline bank

65,536 assembled arm64 entry points, one per guest function that native code must be able to call. ≈ the 65,536 phone numbers the guest can leave for a call back.

MIG reply

The reply half of a Mach message; several are rewritten so the guest sees its own memory map and port names. ≈ the letter the operator opens and rewrites on the way back.

ulock

Darwin's futex; a wait on a stack address means "waiting for a dispatch block to run elsewhere". ≈ waiting by a mailbox for a note that another thread will drop in.

unstick

The watchdog that nudges a thread blocked too long in a kickable syscall so it re-checks for signals and suspend requests. ≈ the supervisor who taps a worker who has been waiting too long: "check your messages".

gate

One of the test suites make check runs; green before every commit. ≈ the twenty-minute pre-commit hook.