fortrangoingonforty/afs-ld / b13dcdc

+# afs-ld

+

+**Bespoke ARM64 Mach-O linker for Apple Silicon, written in Rust, stdlib only.**

+

+## Why

+

+armfortas already owns the compiler (`armfortas`) and the assembler (`afs-as`). Every binary the toolchain produces today is still shaped by Apple's `ld` — which puts the same class of opaque, untouchable bugs back in our path that motivated abandoning LLVM in the first place. `afs-ld` closes the loop. We own every byte from `.f90` source to the final Mach-O executable on disk.

+

+This is **not** a toy or educational linker. The target is production parity with Apple `ld` for:

+

+- Everything armfortas produces today: arm64 PIE executables statically linking `libarmfortas_rt.a` and dynamically linking `libSystem`.

+- The fortsh milestone: ~57 KLoC Fortran 2018, 55 modules, `iso_c_binding`, allocatable strings, derived types.

+- Deterministic output: `-no_uuid` parity, reproducible byte layout across invocations.

+- All ARM64 Mach-O relocation types, static archives (`.a`), binary dylibs, and TAPI TBD v4 text stubs (libSystem ships as `.tbd` on modern SDKs).

+- Both classic `LC_DYLD_INFO` opcodes **and** modern `LC_DYLD_CHAINED_FIXUPS`.

+- Dylib output (`-dylib`) as a first-class feature, not an afterthought.

+- Ad-hoc code signing — macOS 11+ will not execute an unsigned arm64 binary, even if every other byte is perfect.

+

+## Non-goals (current)

+

+- ELF, COFF, PE, or any non-Mach-O format.

+- x86_64, arm64_32, armv7, or any architecture other than arm64.

+- Bitcode/LTO. armfortas emits assembly, not bitcode; lto is not part of the armfortas pipeline.

+- ObjC / Swift metadata merging. No armfortas code emits it. Hooks exist for later.

+- Cross-compilation. We target the host Mac; no `-sdk_version` time-travel.

+

+These are non-goals **now**; afs-ld is built to grow into them without architectural retrofit.

+

+## What afs-as hands us

+

+afs-as emits `MH_OBJECT` only (hand-rolled, no external Mach-O crate). Its output defines the contract afs-ld reads:

+

+- Load commands: `LC_SEGMENT_64`, `LC_BUILD_VERSION` (PLATFORM_MACOS), optional `LC_LINKER_OPTIMIZATION_HINT`, `LC_SYMTAB`, `LC_DYSYMTAB`.

+- Section kinds: `__TEXT,__text`, `__TEXT,__cstring`, `__TEXT,__literal16`, `__TEXT,__const`, `__TEXT,__compact_unwind`, `__TEXT,__eh_frame`, `__DATA,__data`, `__DATA,__bss`, `__DATA,__thread_data`, `__DATA,__thread_bss`, `__DATA,__thread_vars`.

+- Symbol flags: `N_UNDF`/`N_SECT`/`N_ABS` with `N_EXT`, `N_PEXT`, `N_WEAK_REF`, `N_WEAK_DEF`, `N_NO_DEAD_STRIP`. Common symbols live in `N_UNDF` with `n_desc`-encoded alignment.

+- Relocation types: `ARM64_RELOC_UNSIGNED`, `SUBTRACTOR`, `BRANCH26`, `PAGE21`, `PAGEOFF12`, `GOT_LOAD_PAGE21`, `GOT_LOAD_PAGEOFF12`, `POINTER_TO_GOT`, `TLVP_LOAD_PAGE21`, `TLVP_LOAD_PAGEOFF12`, `ADDEND` (paired prefix).

+- Flags: `MH_SUBSECTIONS_VIA_SYMBOLS` always set — atomization model is in play.

+- LOH hints: `AdrpAdd`, `AdrpLdr`, `AdrpLdrGot`, `AdrpLdrGotLdr` — afs-ld preserves them from Sprint 0 and relaxes them in Sprint 25.

+

+afs-as exposes no Mach-O reader. afs-ld ships its own.

+

+## Current driver contract

+

+`armfortas/src/driver/mod.rs:497-565` shells out to `ld`:

+

+```

+ld <obj1> <obj2> ... <libarmfortas_rt.a> \

+   -lSystem -no_uuid -syslibroot <SDK> -e _main -o <output>

+```

+

+Inputs are `.o` from afs-as plus `libarmfortas_rt.a` from the `runtime/` crate. Output is an arm64 PIE executable with entry `_main` (a synthetic wrapper at `src/driver/mod.rs:371-392` calling `_afs_program_init` → user PROGRAM → `_afs_program_finalize`). afs-ld drops into this contract unchanged; the driver swap (Sprint 20) is initially gated behind `AFS_LD=1`.

+

+## Reference material

+

+Already in parent `.refs/`:

+

+- `.refs/llvm/lld/MachO/` (~21 KLoC C++) — primary architectural reference. Most relevant files: `Driver.cpp` (pipeline), `InputFiles.cpp` (object/archive/dylib parsing), `SymbolTable.cpp` (resolution), `SyntheticSections.cpp` (GOT/stubs/binding), `Arch/ARM64.cpp` (reloc math), `Writer.cpp` (layout).

+- `.refs/llvm/lld/docs/MachO/index.rst` — design notes comparing lld and ld64.

+

+Cloned in Sprint 0:

+

+- `.refs/ld64/` — Apple's open-source `ld64` (GitHub mirror of last publicly released tarball). Authoritative for byte-level parity edge cases when our diff harness disagrees with Apple's `ld`.

+- `.refs/mold/` — Rui Ueyama's `mold` including its Darwin port. Leaner second opinion and a source of performance ideas.

+

+Spec-level:

+

+- Apple `<mach-o/loader.h>`, `<mach-o/nlist.h>`, `<mach-o/reloc.h>`, `<mach-o/arm64/reloc.h>` — mirrored numerically in our `macho/constants.rs`.

+- `dyld` open source — bind/rebase/lazy-bind opcode semantics and chained-fixups format.

+- ARM Architecture Reference Manual (ARMv8-A) — encoding of relocated instructions (ADRP, ADD, LDR, B/BL).

+

+## Repo layout

+

+afs-ld is a Cargo workspace member of `armfortas` and a Git submodule at `armfortas/afs-ld` pointing at `git@github.com:FortranGoingOnForty/afs-ld.git`, mirroring how `afs-as` is organized.

+

+```

+afs-ld/

+├── Cargo.toml                 # no deps outside std

+├── CLAUDE.md                  # mirrors afs-as/CLAUDE.md, tailored to linker

+├── README.md

+├── .docs/

+│   ├── overview.md            # this file

+│   └── sprints/               # 32 sprint files

+├── src/

+│   ├── lib.rs                 # re-export Linker, LinkOptions, OutputKind

+│   ├── main.rs                # afs-ld binary

+│   ├── args.rs                # CLI parsing (hand-rolled, no clap)

+│   ├── macho/

+│   │   ├── mod.rs

+│   │   ├── constants.rs       # LC_*, MH_*, S_*, N_*, ARM64_RELOC_*

+│   │   ├── reader.rs          # parse MH_OBJECT

+│   │   ├── writer.rs          # emit MH_EXECUTE or MH_DYLIB

+│   │   ├── dylib.rs           # parse MH_DYLIB

+│   │   └── tbd.rs             # parse TAPI TBD v4

+│   ├── archive.rs             # ar/ranlib archive reader

+│   ├── input.rs               # InputFile enum, lazy member fetch

+│   ├── symbol.rs              # Symbol kinds, SymbolTable

+│   ├── resolve.rs             # name resolution pass

+│   ├── atom.rs                # subsections-via-symbols atom model

+│   ├── section.rs             # InputSection, OutputSection, OutputSegment

+│   ├── layout.rs              # VM addr + file offset assignment

+│   ├── reloc/

+│   │   ├── mod.rs

+│   │   ├── arm64.rs           # ARM64_RELOC_* application

+│   │   └── loh.rs             # LOH preservation / relaxation

+│   ├── synth/                 # synthetic sections

+│   │   ├── mod.rs

+│   │   ├── got.rs

+│   │   ├── stubs.rs

+│   │   ├── tlv.rs

+│   │   ├── symtab.rs

+│   │   ├── dyld_info.rs       # classic rebase/bind/lazy/weak + export trie

+│   │   ├── chained.rs         # LC_DYLD_CHAINED_FIXUPS

+│   │   ├── unwind.rs

+│   │   ├── eh_frame.rs

+│   │   ├── func_starts.rs

+│   │   ├── data_in_code.rs

+│   │   └── code_sig.rs        # ad-hoc SHA-256 code signature

+│   ├── map.rs                 # -map text link map

+│   ├── why_live.rs            # -why_live dead-strip reasons

+│   ├── gc.rs                  # -dead_strip

+│   ├── icf.rs                 # -icf=safe

+│   ├── driver.rs              # orchestrator

+│   └── diag.rs                # diagnostics, path/line/col parity with afs-as

+└── tests/

+    ├── common/harness.rs      # spawn afs-ld, diff output vs system ld

+    ├── reader_*.rs            # round-trip object reads

+    ├── reloc_*.rs             # golden-file reloc application

+    ├── resolve_*.rs           # symbol resolution matrices

+    ├── hello_world.rs         # first end-to-end executable link

+    ├── hello_library.rs       # first end-to-end dylib link

+    ├── armfortas_integration.rs

+    └── corpus/                # hand-curated .o / .a / .dylib / .tbd fixtures

+```

+

+## Architecture pipeline

+

+```

+args → inputs → resolve → atomize → layout → apply relocs → synth sections → write → sign

+```

+

+1. **args**: hand-rolled parser for the `ld`-compatible CLI surface. No clap.

+2. **inputs**: demultiplex `.o`, `.a`, `.dylib`, `.tbd`; lazy archive-member fetching.

+3. **resolve**: symbol-table fixed-point loop; weak/common/alias coalescing; archive-driven pulls.

+4. **atomize**: split input sections at symbol boundaries per `MH_SUBSECTIONS_VIA_SYMBOLS`.

+5. **layout**: assign VM addrs (`__PAGEZERO`/`__TEXT`/`__DATA_CONST`/`__DATA`/`__LINKEDIT` for executables; no `__PAGEZERO` for dylibs) and file offsets.

+6. **apply relocs**: ARM64_RELOC_* patching; GOT/stubs/lazy-pointer emission; LOH honoring.

+7. **synth sections**: `__LINKEDIT` payload — symbol table, string table, `LC_DYLD_INFO` and/or chained fixups, function starts, data-in-code, compact unwind, eh_frame passthrough.

+8. **write**: Mach-O header + load commands + segment data; `-no_uuid` deterministic.

+9. **sign**: ad-hoc SHA-256 page hashes in `LC_CODE_SIGNATURE` so the binary runs on bare arm64.

+

+## Coding conventions

+

+- **Rust std only.** No `clap`, no `serde`, no `byteorder`, no `object`, no `goblin`. Hand-roll parsers, serializers, and the tiny YAML subset we need for TBD.

+- **`unsafe` only where genuinely required.** Keep blocks small and commented.

+- **Exhaustive pattern matching** on `Section`, `Symbol`, `Relocation`, `InputFile`, `Fixup` — no catch-all `_` arms outside tests.

+- **Diagnostics**: path, offset, caret under source — mirror `afs-as/src/diag*.rs`.

+- **Determinism**: no timestamps in output, sorted iteration, stable hashing.

+- **Commit discipline**: terse imperative, no co-authors, per-file/per-chunk commits, never monoliths. Matches armfortas and afs-as house rules.

+- **No borrowed constants across crates.** afs-ld duplicates `MH_*`, `LC_*`, `S_*`, `N_*`, `ARM64_RELOC_*` in `macho/constants.rs` rather than depending on afs-as at a type level. Each submodule stays independent.

+

+## Testing strategy

+

+- **Unit**: every parser and encoder has a round-trip test — parse a fixture, re-emit, compare bytes.

+- **Corpus**: `tests/corpus/` collects `.o`, `.a`, `.dylib`, `.tbd` fixtures. Every new relocation type or section kind lands a corpus entry in the same sprint that implements it.

+- **Differential** (from Sprint 1): `tests/common/harness.rs` links the same inputs through `ld` and `afs-ld`, diffs load commands, symbol tables, bind/rebase or chained-fixup streams, and disassembly. Tolerated-diff allowlist covers UUID, timestamp, hash-backed temp names. CI gate from sprint one.

+- **End-to-end** (from Sprint 18): hello-world executable must run; (Sprint 18.5) hello-library dylib must `dlopen`. (Sprint 21) the full armfortas integration suite must pass.

+- **fortsh link** (Sprint 29): explicit milestone. A fortsh binary linked by afs-ld must behave identically to one linked by system `ld`.

+- **Audits**: post-Sprint 18 (hello), 18.5 (dylib), 22 (first signed & running on bare arm64), 27 (parity gate), 29 (fortsh), 31 (final). Brutal honesty rules from armfortas/CLAUDE.md apply.

+

+## Sprint roadmap (summary)

+

+See `.docs/sprints/index.md` for the full list. Ten phases, 32 sprints:

+

+- **Phase 0 — Scaffolding**: Sprint 0.

+- **Phase 1 — Mach-O reading**: Sprints 1–3 (header/load commands, sections/symbols, relocations).

+- **Phase 2 — Archives & dylibs**: Sprints 4–6 (`ar`, binary dylib, TBD).

+- **Phase 3 — Symbol resolution**: Sprints 7–9 (model, resolution pass, atomization).

+- **Phase 4 — Output construction**: Sprints 10–14 (layout, reloc application, GOT/stubs, TLV, symtab/strtab). MH_EXECUTE and MH_DYLIB both first-class.

+- **Phase 5 — Dyld metadata**: Sprints 15 (classic `LC_DYLD_INFO`), 15.5 (chained fixups), 16 (function starts/data-in-code), 17 (unwind info).

+- **Phase 6 — End-to-end**: Sprint 18 (hello-world executable), 18.5 (hello-library dylib).

+- **Phase 7 — CLI & driver**: Sprints 19 (CLI + `-map`/`-why_live` diagnostics), 20 (driver swap).

+- **Phase 8 — Runtime compatibility**: Sprints 21 (runtime archive + integration tests), 22 (ad-hoc code signature).

+- **Phase 9 — Advanced**: Sprints 23 (`-dead_strip`), 24 (`-icf=safe`), 25 (LOH relaxation), 26 (thunks).

+- **Phase 10 — Hardening**: Sprints 27 (differential gate), 28 (performance), 29 (fortsh link audit), 30 (polish), 31 (final audit).

+

+## Scope decisions (confirmed)

+

+- Dylib output is in scope from Phase 4; the writer is dylib-aware from Sprint 10. Dylib milestone at Sprint 18.5.

+- Both classic `LC_DYLD_INFO` (Sprint 15) and chained fixups (Sprint 15.5) are in scope. Chained becomes default on macOS 12+ after Sprint 27 parity gate.

+- `.refs/` gains ld64 and mold alongside lld. lld is the architectural reference, ld64 is authoritative for Apple-parity edge cases, mold informs performance.

+- `-map` and `-why_live` land in Sprint 19 with the core CLI. They are the debugging surface during driver adoption, not a polish item.

+# afs-ld Sprint Index

+

+32 sprints across 10 phases. Small bites, clear milestones, testable deliverables at every stage. Each sprint is independently reviewable and mergeable; every sprint that lands new surface area also lands corpus fixtures and differential coverage.

+

+## Phase 0 — Scaffolding

+- [Sprint 0](sprint00.md) — Scaffolding, References, Harness

+

+## Phase 1 — Mach-O Reading

+- [Sprint 1](sprint01.md) — MH_OBJECT Header & Load Commands

+- [Sprint 2](sprint02.md) — Sections, Symbols, String Tables

+- [Sprint 3](sprint03.md) — Relocations (Read-Side)

+

+## Phase 2 — Archives & Dylibs

+- [Sprint 4](sprint04.md) — Static Archives (ar)

+- [Sprint 5](sprint05.md) — Dylibs (MH_DYLIB binary)

+- [Sprint 6](sprint06.md) — TAPI TBD Text Stubs

+

+## Phase 3 — Symbol Resolution

+- [Sprint 7](sprint07.md) — Symbol Model & Table

+- [Sprint 8](sprint08.md) — Name Resolution Pass

+- [Sprint 9](sprint09.md) — Subsections-via-Symbols Atomization

+

+## Phase 4 — Output Construction (MH_EXECUTE and MH_DYLIB both first-class)

+- [Sprint 10](sprint10.md) — Output Segment & Section Layout (dylib-aware)

+- [Sprint 11](sprint11.md) — Core Relocation Application (ARM64)

+- [Sprint 12](sprint12.md) — GOT, Stubs, Lazy Pointers

+- [Sprint 13](sprint13.md) — TLV Relocations

+- [Sprint 14](sprint14.md) — LC_SYMTAB / LC_DYSYMTAB / String Table

+

+## Phase 5 — Dynamic Linker Metadata

+- [Sprint 15](sprint15.md) — Classic LC_DYLD_INFO Opcodes

+- [Sprint 15.5](sprint15_5.md) — Chained Fixups (LC_DYLD_CHAINED_FIXUPS)

+- [Sprint 16](sprint16.md) — LC_FUNCTION_STARTS & LC_DATA_IN_CODE

+- [Sprint 17](sprint17.md) — Unwind Info

+

+## Phase 6 — First End-to-End

+- [Sprint 18](sprint18.md) — HELLO WORLD MILESTONE (Executable)

+- [Sprint 18.5](sprint18_5.md) — HELLO LIBRARY MILESTONE (Dylib)

+

+## Phase 7 — CLI & Driver Integration

+- [Sprint 19](sprint19.md) — CLI Surface + Diagnostics (-map, -why_live)

+- [Sprint 20](sprint20.md) — Driver Swap

+

+## Phase 8 — Runtime Compatibility

+- [Sprint 21](sprint21.md) — Runtime Archive Linking

+- [Sprint 22](sprint22.md) — Code Signature (Ad-Hoc)

+

+## Phase 9 — Advanced Features

+- [Sprint 23](sprint23.md) — Dead Strip (`-dead_strip`)

+- [Sprint 24](sprint24.md) — ICF (`-icf=safe`)

+- [Sprint 25](sprint25.md) — LOH Relaxation

+- [Sprint 26](sprint26.md) — Thunks for Out-of-Range Branches

+

+## Phase 10 — Production Hardening

+- [Sprint 27](sprint27.md) — Differential Harness vs Apple ld

+- [Sprint 28](sprint28.md) — Performance & Parallelism

+- [Sprint 29](sprint29.md) — fortsh Link Audit

+- [Sprint 30](sprint30.md) — Diagnostics & Polish

+- [Sprint 31](sprint31.md) — Final Audit

+# Sprint 0: Scaffolding, References, Harness

+

+## Prerequisites

+None — this is where afs-ld begins. Assumes armfortas and afs-as already exist and compile.

+

+## Current state to remediate

+

+The `afs-ld/` directory currently sits inside armfortas's working tree as a plain subdirectory. `afs-ld/.gitignore` was accidentally committed to armfortas history (commit `85d5ba8 "init"`), tracking a file that will shortly belong to a separate repo. Before anything else in this sprint, afs-ld must be extracted into its own repo and wired back in as a Git submodule. The tracked `.gitignore` must be removed from armfortas's index (history can stay; removing a single file at HEAD is clean) so that afs-ld's contents live in the submodule and nowhere else.

+

+## Goals

+Extract afs-ld into its own repo, wire it back as a submodule, stand up the crate (CLAUDE.md, README, Cargo.toml, skeleton source), clone reference linkers, build the differential harness. End state: `cargo test -p afs-ld` runs from the parent workspace, at least one test passes meaningfully, and `git submodule status` lists afs-ld alongside afs-as.

+

+## Deliverables

+

+### 1. Submodule remediation (do first)

+

+Goal: move from "afs-ld is a tracked subdirectory of armfortas" to "afs-ld is a submodule pointing at `git@github.com:FortranGoingOnForty/afs-ld.git`". Exact sequence:

+

+1. **Preserve the current afs-ld contents**: copy `armfortas/afs-ld/` to a temp location (the `.docs/overview.md` and sprint files produced in planning are the primary content to preserve; `.fackr/` is scratch and can be dropped).

+2. **Untrack from armfortas**: `git rm --cached afs-ld/.gitignore && git commit -m "remove accidentally-tracked afs-ld/.gitignore"`. Confirm `git ls-files afs-ld` returns empty.

+3. **Delete the directory from armfortas's working tree** (submodule-add will recreate it): `rm -rf afs-ld/`.

+4. **Create the external repo** `FortranGoingOnForty/afs-ld` on GitHub (empty, no README — submodule-add will seed it).

+5. **Initialize locally and push**: in a scratch directory,

+   ```

+   git init afs-ld

+   cd afs-ld

+   <copy preserved contents back>

+   git add -A

+   git commit -m "init"

+   git remote add origin git@github.com:FortranGoingOnForty/afs-ld.git

+   git push -u origin trunk

+   ```

+6. **Add as submodule in armfortas**:

+   ```

+   cd <armfortas root>

+   git submodule add git@github.com:FortranGoingOnForty/afs-ld.git afs-ld

+   git commit -m "add afs-ld submodule"

+   ```

+   Confirm `.gitmodules` gained the stanza:

+   ```

+   [submodule "afs-ld"]

+       path = afs-ld

+       url = git@github.com:FortranGoingOnForty/afs-ld.git

+   ```

+7. **Verify** with `git submodule status` — afs-as and afs-ld both listed, each pinned to a commit hash.

+

+Note: the old `git rm --cached` commit stays in armfortas history. Rewriting history to erase it is more destructive than it's worth for a single `.gitignore` file. The file at HEAD is gone; that is sufficient.

+

+### 2. Crate wiring

+

+- Root `Cargo.toml` adds `"afs-ld"` to `[workspace] members` alongside `afs-as`.

+- `afs-ld/Cargo.toml`: binary + library, zero external dependencies, `edition = "2021"`. Mirror `afs-as/Cargo.toml` — same `keywords`, `categories`, `license = "GPL-3.0-only"`, adjusted `description` and `repository`.

+- `afs-ld/src/lib.rs`: public re-exports of `Linker`, `LinkOptions`, `OutputKind` (types are stubs this sprint).

+- `afs-ld/src/main.rs`: CLI that prints usage and exits 0 when run with no args; forwards real args to `Linker::run` (which errors with "not yet implemented" this sprint).

+

+### 3. CLAUDE.md and README.md

+

+- `afs-ld/CLAUDE.md`: mirror `afs-as/CLAUDE.md`, replacing assembler-isms with linker-isms. Non-negotiable rules: Rust std only, exhaustive matching, caret diagnostics, per-chunk commits, no co-authors, no sprint-number references in commits.

+- `afs-ld/README.md`: one-page intro, supported CLI subset at current state (nothing yet — say so), build/test commands.

+- `afs-ld/.gitignore`: `target/`, `.fackr/`, no `.docs/` since those files live in the repo. This one is intentionally tracked because it lives inside afs-ld's own repo now, not armfortas's.

+

+### 4. Reference clones

+

+Add to parent `.refs/` (gitignored):

+

+- `.refs/ld64/` — `git clone --depth 1 https://github.com/apple-oss-distributions/ld64.git`. Apple's last publicly released ld64. Authoritative for Apple-parity edge cases.

+- `.refs/mold/` — `git clone --depth 1 https://github.com/rui314/mold.git`. Performance reference and a second Rust-adjacent angle on Mach-O.

+

+`.refs/llvm/lld/MachO/` already exists from armfortas Sprint 0 — primary architectural reference.

+

+### 5. Differential harness

+

+`afs-ld/tests/common/harness.rs`:

+

+```rust

+pub struct LinkCase {

+    pub name: &'static str,

+    pub inputs: Vec<PathBuf>,       // .o / .a / .tbd

+    pub args: Vec<String>,          // -o, -e, -syslibroot, -l, ...

+}

+

+pub struct LinkOutputs {

+    pub ours: Vec<u8>,              // afs-ld output

+    pub theirs: Vec<u8>,            // system ld output

+}

+

+pub fn link_both(case: &LinkCase) -> LinkOutputs;

+pub fn diff_macho(ours: &[u8], theirs: &[u8]) -> DiffReport;

+```

+

+`DiffReport` categorizes byte differences as `Tolerated` (UUID, timestamp, temp-path hashes) or `Critical` (anything else). Critical diffs fail the test. `link_both` shells out to `ld` via `xcrun -f ld` so it picks up the active toolchain.

+

+### 6. Skeleton CLI and first failing test

+

+- `afs-ld/src/args.rs`: hand-rolled argv parser stub that recognizes `-o`, `-e`, `-arch`, and positional inputs. Unknown flags error loudly with a hint.

+- `afs-ld/tests/reader_empty.rs`: attempts to link `0 inputs → empty output`, expects the diagnostic `"afs-ld: error: no input files"`. Passes today by producing that exact string.

+- `afs-ld/tests/diff_harness_sanity.rs`: runs the harness against a known-identical pair (two copies of the same pre-linked binary produced by `xcrun ld`) and expects zero diffs. Passes.

+- `afs-ld/tests/diff_harness_finds_critical.rs`: feeds the harness two binaries that differ in a non-tolerated byte range (e.g. different text bytes) and asserts the harness reports `Critical`. Passes.

+

+## Testing Strategy

+

+- `cargo build -p afs-ld` compiles from a fresh clone of the parent with `git submodule update --init --recursive`.

+- `cargo test -p afs-ld` runs harness-sanity, critical-detection, and empty-input tests.

+- `cargo clippy -p afs-ld -- -D warnings` clean.

+- Manual verification of submodule state:

+  - `git ls-files | grep afs-ld` in armfortas prints only the `.gitmodules` entry (and nothing under `afs-ld/`).

+  - `git submodule status` shows both afs-as and afs-ld with valid commit hashes.

+  - `git submodule update --init --recursive` on a fresh armfortas clone populates afs-ld correctly.

+

+## Definition of Done

+

+- The accidentally-tracked `afs-ld/.gitignore` is removed from armfortas's index at HEAD.

+- afs-ld exists as a standalone GitHub repo under `FortranGoingOnForty`.

+- afs-ld is wired into armfortas as a Git submodule, visible in `.gitmodules` and `git submodule status`.

+- `armfortas/Cargo.toml` lists `afs-ld` in `[workspace] members`.

+- `afs-ld/CLAUDE.md`, `README.md`, `Cargo.toml`, `src/lib.rs`, `src/main.rs`, `src/args.rs` all committed in the new repo.

+- `.refs/ld64/` and `.refs/mold/` cloned.

+- Differential harness runs, correctly reports zero diffs on identical binaries, correctly reports critical diffs on intentionally-different binaries.

+- `cargo test --workspace` green.

+# Sprint 1: MH_OBJECT Header & Load Commands

+

+## Prerequisites

+Sprint 0 — crate, harness, references in place.

+

+## Goals

+Read a Mach-O relocatable object file: parse the header and every load command afs-as emits. End state: given any `.o` in `afs-as/tests/corpus/`, afs-ld can pretty-print its structure and round-trip-compare it to a golden.

+

+## Deliverables

+

+### 1. Mach-O constants

+`afs-ld/src/macho/constants.rs`: duplicate the constants afs-as uses. Numeric literals only, no imports from afs-as.

+

+```rust

+pub const MH_MAGIC_64: u32 = 0xFEEDFACF;

+pub const CPU_TYPE_ARM64: u32 = 0x0100000C;

+pub const MH_OBJECT: u32 = 1;

+pub const MH_EXECUTE: u32 = 2;

+pub const MH_DYLIB: u32 = 6;

+pub const MH_SUBSECTIONS_VIA_SYMBOLS: u32 = 0x2000;

+

+pub const LC_SEGMENT_64: u32 = 0x19;

+pub const LC_SYMTAB: u32 = 0x02;

+pub const LC_DYSYMTAB: u32 = 0x0B;

+pub const LC_BUILD_VERSION: u32 = 0x32;

+pub const LC_LINKER_OPTIMIZATION_HINT: u32 = 0x2E;

+// ... plus LC_MAIN, LC_DYLD_INFO_ONLY, LC_DYLD_CHAINED_FIXUPS,

+//         LC_FUNCTION_STARTS, LC_DATA_IN_CODE, LC_CODE_SIGNATURE,

+//         LC_ID_DYLIB, LC_LOAD_DYLIB, LC_LOAD_WEAK_DYLIB,

+//         LC_REEXPORT_DYLIB, LC_RPATH, LC_UUID, LC_SOURCE_VERSION.

+```

+

+### 2. Header parser

+`afs-ld/src/macho/reader.rs`:

+

+```rust

+pub struct MachHeader64 {

+    pub magic: u32, pub cputype: u32, pub cpusubtype: u32,

+    pub filetype: u32, pub ncmds: u32, pub sizeofcmds: u32,

+    pub flags: u32, pub reserved: u32,

+}

+

+pub fn parse_header(bytes: &[u8]) -> Result<MachHeader64, ReadError>;

+```

+

+Validate: magic matches MH_MAGIC_64, cputype matches CPU_TYPE_ARM64, `ncmds * 8 <= sizeofcmds`, `32 + sizeofcmds <= bytes.len()`. Clear, sourced diagnostics via `src/diag.rs`.

+

+### 3. Load-command dispatcher

+`LoadCommand` enum with variants for each command afs-as emits:

+

+```rust

+pub enum LoadCommand {

+    Segment64(Segment64),

+    Symtab(SymtabCmd),

+    Dysymtab(DysymtabCmd),

+    BuildVersion(BuildVersionCmd),

+    LinkerOptimizationHint(LohCmd),

+    // placeholders for later sprints:

+    DyldInfoOnly, DyldChainedFixups, Main, FunctionStarts,

+    DataInCode, CodeSignature, IdDylib, LoadDylib, LoadWeakDylib,

+    ReexportDylib, Rpath, Uuid, SourceVersion,

+    Unknown { cmd: u32, cmdsize: u32, data: Vec<u8> },

+}

+

+pub fn parse_commands(header: &MachHeader64, bytes: &[u8]) -> Result<Vec<LoadCommand>, ReadError>;

+```

+

+Exhaustive matching. Unknown commands preserved (not erased) so round-trips survive.

+

+### 4. Segment + section header parsing (metadata only — contents in Sprint 2)

+Decode `segment_command_64` (72 bytes) + N `section_64` structs (80 bytes each). Store:

+- segname (fixed 16 bytes, null-padded)

+- sectname (fixed 16 bytes, null-padded)

+- addr, size, offset, align (as log2), reloff, nreloc, flags, reserved1, reserved2, reserved3

+

+### 5. LC_BUILD_VERSION + LC_LINKER_OPTIMIZATION_HINT

+Decode platform (PLATFORM_MACOS = 1), minos, sdk, ntools, tool records. Decode the LOH blob as raw bytes (interpretation in Sprint 25).

+

+### 6. Pretty-printer

+`afs-ld/src/bin/dump.rs` (optional subcommand `afs-ld --dump <path>`): otool-like output. Used by the round-trip harness.

+

+## Testing Strategy

+- Round-trip test: for every `.o` in `afs-as/tests/corpus/`, parse, serialize back into the same byte layout (no reshuffling in this sprint — just read+echo), compare.

+- Malformed-input tests: truncated header, wrong magic, wrong cputype, `ncmds` lying about `sizeofcmds`, unaligned commands. Each must produce a specific diagnostic, never a panic.

+- Differential: `otool -lV` against our dumper for the full corpus. Diff must be zero after whitespace normalization.

+

+## Definition of Done

+- All afs-as corpus `.o` files parse cleanly.

+- Every load command afs-as emits is represented in `LoadCommand`.

+- Malformed-input fuzz finds no panics.

+- Round-trip byte-level equality on the full corpus.

+- `otool -lV` and our dumper agree after whitespace normalization.

+# Sprint 2: Sections, Symbols, String Tables

+

+## Prerequisites

+Sprint 1 — header + load commands parsed.

+

+## Goals

+Decode section payloads, the symbol table (nlist_64), and the string table. Expose the full section/symbol/string model that later sprints build on.

+

+## Deliverables

+

+### 1. Section attributes and kinds

+`afs-ld/src/section.rs` — `SectionKind` mirrors afs-as's but richer on the reader side (we receive inputs with flags already set):

+

+```rust

+pub enum SectionKind {

+    Text, CStringLiterals, Literal4, Literal8, Literal16,

+    ConstData, Data, ZeroFill, GbZeroFill,

+    ThreadLocalRegular, ThreadLocalZerofill,

+    ThreadLocalVariables, ThreadLocalInitPointers,

+    CompactUnwind, EhFrame, Coalesced,

+    Regular, Unknown,

+}

+

+pub fn kind_from_flags(flags: u32) -> SectionKind; // S_* attribute bits

+```

+

+Respect all `S_ATTR_*` flags and section-type nibble (`flags & 0xff`).

+

+### 2. Section content slicing

+`InputSection` struct: segment, name, kind, addr, size, align (log2), flags, raw `data: &[u8]` borrowed from the mmap'd input, plus the raw relocation entries as `&[u8]` (decoded in Sprint 3). For `S_ZEROFILL` / `S_THREAD_LOCAL_ZEROFILL`, `data` is empty; size is virtual.

+

+### 3. nlist_64 and symbol flags

+`afs-ld/src/symbol.rs`:

+

+```rust

+pub const N_STAB: u8 = 0xe0;

+pub const N_PEXT: u8 = 0x10;

+pub const N_TYPE: u8 = 0x0e; // mask

+pub const N_EXT:  u8 = 0x01;

+

+pub const N_UNDF: u8 = 0x0;

+pub const N_ABS:  u8 = 0x2;

+pub const N_SECT: u8 = 0xe;

+pub const N_INDR: u8 = 0xa;

+

+pub const N_NO_DEAD_STRIP: u16 = 0x0020;

+pub const N_WEAK_REF:      u16 = 0x0040;

+pub const N_WEAK_DEF:      u16 = 0x0080;

+pub const N_ARM_THUMB_DEF: u16 = 0x0008;

+pub const N_SYMBOL_RESOLVER: u16 = 0x0100;

+

+pub struct RawNlist {

+    pub strx: u32,

+    pub n_type: u8, pub n_sect: u8, pub n_desc: u16,

+    pub n_value: u64,

+}

+

+pub struct InputSymbol<'a> {

+    pub name: &'a str,

+    pub kind: SymKind,                // Undef, Abs, SectLocal, SectExt, PExt, Indirect

+    pub weak_ref: bool, pub weak_def: bool,

+    pub no_dead_strip: bool, pub private_extern: bool,

+    pub sect_idx: u8, pub value: u64,

+    pub common_align_pow2: Option<u8>, // from n_desc bits 8..15 when UNDF + value != 0

+}

+```

+

+Common symbols detected the way afs-as emits them: `N_UNDF | N_EXT` with nonzero `n_value` encoding the size and `n_desc >> 8` encoding alignment.

+

+### 4. Indirect (N_INDR) pass-through

+Alias symbols: record the aliased name from the string table via `n_value` used as a strx into the string table. Resolution lives in Sprint 7; this sprint just surfaces the data.

+

+### 5. String table reader

+`StringTable` wraps the raw bytes of `__LINKEDIT` string table, exposes `name_at(strx: u32) -> &str`, validates null termination, gracefully handles the suffix-dedup trick afs-as uses (`"_foo\0"` can overlap with a later `"_bar_foo\0"` by pointing mid-string).

+

+### 6. DYSYMTAB partitioning

+Decode the partition `(ilocalsym, nlocalsym)`, `(iextdefsym, nextdefsym)`, `(iundefsym, nundefsym)`. Record `toc`, `modtab`, `extrefsym`, `indirectsymoff/nindirectsyms`, `extreloff`, `locreloff` offsets for later phases (most are for dylibs).

+

+### 7. Input file model

+`afs-ld/src/input.rs`:

+

+```rust

+pub struct ObjectFile {

+    pub path: PathBuf,

+    pub header: MachHeader64,

+    pub commands: Vec<LoadCommand>,

+    pub sections: Vec<InputSection>,

+    pub symbols: Vec<InputSymbol>,

+    pub strings: StringTable,

+    pub dysymtab: DysymtabView,

+}

+```

+

+## Testing Strategy

+- Round-trip: parse every section/symbol/string from the afs-as corpus; re-emit; match bytes.

+- Diffing against `nm -a` and `otool -r` for symbols and relocation offsets (relocation bodies come in Sprint 3).

+- Edge cases: empty `__bss`, tentative common with 16-byte alignment, weak-def with `N_NO_DEAD_STRIP`, indirect symbol chains.

+- Fuzz: malformed nlist entries (strx out of bounds, n_sect out of range, invalid n_type bits) produce sourced diagnostics, never panics.

+

+## Definition of Done

+- Every symbol attribute afs-as can emit is recognized and round-trips.

+- Common symbols surface with correct size and alignment.

+- String table reader handles suffix-dedup overlaps correctly.

+- Corpus-wide symbol and section parity against `nm -a` / `otool -v`.

+# Sprint 3: Relocations (Read-Side)

+

+## Prerequisites

+Sprints 1–2 — header/load commands and section/symbol parsing in place.

+

+## Goals

+Decode every ARM64 relocation type afs-as emits. Normalize paired relocations (ADDEND + primary, SUBTRACTOR + UNSIGNED) into a linker-friendly form. End state: the linker's reloc model captures every arithmetic and semantic constraint needed by Sprint 11.

+

+## Deliverables

+

+### 1. Relocation constants and raw form

+`afs-ld/src/macho/constants.rs` additions:

+

+```rust

+pub const ARM64_RELOC_UNSIGNED:             u8 = 0;

+pub const ARM64_RELOC_SUBTRACTOR:           u8 = 1;

+pub const ARM64_RELOC_BRANCH26:             u8 = 2;

+pub const ARM64_RELOC_PAGE21:               u8 = 3;

+pub const ARM64_RELOC_PAGEOFF12:            u8 = 4;

+pub const ARM64_RELOC_GOT_LOAD_PAGE21:      u8 = 5;

+pub const ARM64_RELOC_GOT_LOAD_PAGEOFF12:   u8 = 6;

+pub const ARM64_RELOC_POINTER_TO_GOT:       u8 = 7;

+pub const ARM64_RELOC_TLVP_LOAD_PAGE21:     u8 = 8;

+pub const ARM64_RELOC_TLVP_LOAD_PAGEOFF12:  u8 = 9;

+pub const ARM64_RELOC_ADDEND:               u8 = 10;

+```

+

+Raw `relocation_info`: 8 bytes. `r_address: i32`, `r_info: u32` packed as `[r_symbolnum:24][r_pcrel:1][r_length:2][r_extern:1][r_type:4]`.

+

+### 2. Parsed relocation form

+`afs-ld/src/reloc/mod.rs`:

+

+```rust

+pub struct Reloc {

+    pub offset: u32,            // byte offset into input section

+    pub kind: RelocKind,

+    pub length: RelocLength,    // Byte=0, Half=1, Word=2, Quad=3

+    pub pcrel: bool,

+    pub referent: Referent,

+    pub addend: i64,            // folded from ARM64_RELOC_ADDEND prefix or inline

+}

+

+pub enum RelocKind {

+    Unsigned, Branch26,

+    Page21, PageOff12,

+    GotLoadPage21, GotLoadPageOff12, PointerToGot,

+    TlvpLoadPage21, TlvpLoadPageOff12,

+    Subtractor,     // minuend in `referent`; paired with a following Unsigned subtrahend

+}

+

+pub enum Referent {

+    Symbol(SymRef),        // r_extern = 1

+    Section(SectRef),      // r_extern = 0

+}

+```

+

+### 3. Paired reloc fusion

+Two pairings afs-as emits:

+

+1. **ARM64_RELOC_ADDEND**: a prefix reloc whose `r_symbolnum` field is actually a 24-bit signed addend. The next reloc in the list is the primary (UNSIGNED, PAGE21, PAGEOFF12, BRANCH26, or GOT/TLVP variant). Parser fuses: `addend_reloc.symnum → primary.addend`, primary kept.

+

+2. **ARM64_RELOC_SUBTRACTOR + ARM64_RELOC_UNSIGNED**: difference expression. Emitted as a pair where SUBTRACTOR names the subtrahend symbol and UNSIGNED names the minuend. Parser fuses into a single `RelocKind::Subtractor { minuend, subtrahend }` record on the minuend-carrying entry.

+

+After fusion no ADDEND or SUBTRACTOR relocs should leak out of the reader.

+

+### 4. Integrity checks

+- `r_address + (length_bytes)` within section bounds.

+- `r_extern = 1` → `r_symbolnum < nsyms`.

+- `r_extern = 0` → `r_symbolnum` is a 1-based section index in range.

+- `r_pcrel` matches the reloc kind (PC-relative: BRANCH26, PAGE21 variants, PAGEOFF12 that looks at ADRP page, TLVP variants; not PC-relative: UNSIGNED, PAGEOFF12 for immediates, POINTER_TO_GOT is PC-relative).

+- `r_length` matches kind (all ARM64 reloc kinds are length = 2 except UNSIGNED which is length = 2 or 3 and SUBTRACTOR which matches UNSIGNED).

+

+### 5. Round-trip serializer (for golden tests)

+`afs-ld/src/reloc/mod.rs::write_relocs(sect: &InputSection, relocs: &[Reloc]) -> Vec<u8>` reassembles into Mach-O wire form, including the ADDEND prefix when necessary. Used to prove the reader lost nothing.

+

+## Testing Strategy

+- Round-trip every reloc in the afs-as corpus. Byte equality after ADDEND/SUBTRACTOR fusion + re-emission.

+- Synthetic fixtures for each reloc kind (smallest possible `.s` input through afs-as):

+  - `bl _extern` → BRANCH26 external.

+  - `adrp x0, _g@PAGE; add x0, x0, _g@PAGEOFF` → PAGE21 + PAGEOFF12.

+  - `adrp x0, _g@GOTPAGE; ldr x0, [x0, _g@GOTPAGEOFF]` → GOT_LOAD_PAGE21 + GOT_LOAD_PAGEOFF12.

+  - `.quad _g + 0x1000` → ADDEND + UNSIGNED pair.

+  - `.quad _a - _b` → SUBTRACTOR + UNSIGNED pair.

+  - `adrp x0, _tlv@TLVPPAGE; ldr x0, [x0, _tlv@TLVPPAGEOFF]` → TLVP_LOAD_* pair.

+- Malformed-input: reloc pointing past section end, unpaired SUBTRACTOR, unpaired ADDEND. Each produces a specific diagnostic citing input path and offset.

+

+## Definition of Done

+- Every ARM64 reloc afs-as emits is represented in `RelocKind` post-fusion.

+- Paired relocs never leak as separate entries into downstream code.

+- Corpus-wide round-trip byte equality.

+- Integrity checks trigger diagnostics on malformed fixtures.

+# Sprint 4: Static Archives (`ar`)

+

+## Prerequisites

+Sprints 1–3 — Mach-O reading complete.

+

+## Goals

+Read static archives (`.a`) including the BSD, System V, and GNU-thin variants. Support lazy member fetching: a member is only parsed when an undefined symbol names it. This is the mechanism by which `libarmfortas_rt.a` gets pulled in.

+

+## Deliverables

+

+### 1. Archive format recognizer

+`afs-ld/src/archive.rs`:

+

+```rust

+pub struct Archive<'a> {

+    pub path: PathBuf,

+    pub flavor: Flavor,         // Bsd, Sysv, GnuThin

+    pub symdef: SymbolIndex,    // names → member offsets

+    pub members: Vec<Member<'a>>,

+}

+

+pub enum Flavor { Bsd, Sysv, GnuThin }

+```

+

+Detection by magic: `!<arch>\n` for all flavors; thin archives use `!<thin>\n`. BSD vs SysV distinguished by the first entry: `#1/<N>` BSD extended filenames vs `//` SysV long-name string table.

+

+### 2. Header parsing

+Each member preceded by a 60-byte `ar_hdr`:

+```

+char name[16];   // "#1/<N>" on BSD, or "//" string-table index on SysV, or "foo.o/" on SysV short

+char date[12];

+char uid[6];

+char gid[6];

+char mode[8];

+char size[10];

+char fmag[2];    // "`\n"

+```

+

+Parse field-by-field with tight bounds checks. Size is a decimal ASCII integer, not a C literal.

+

+### 3. Name decoding

+- BSD: name field `#1/<N>`, real name is the first N bytes of the member body (body shrinks accordingly).

+- SysV: name field holds a byte offset into the `//` string table.

+- SysV short: `foo.o/ ` — slash-terminated, space-padded.

+- GNU-thin: member body is zero bytes; the name encodes a path relative to the archive. afs-ld `mmap`s the external file.

+

+Names stored canonical (null-stripped, slash-stripped).

+

+### 4. Symbol index

+SysV `/` member or BSD `__.SYMDEF` / `__.SYMDEF SORTED` member. BSD layout:

+```

+uint32 ranlib_count

+ranlib[ranlib_count] { uint32 strx; uint32 offset; }

+uint32 stringsize

+char strings[stringsize]

+```

+

+SysV: big-endian `nsyms: u32`, then `nsyms` big-endian `u32` offsets, then packed null-terminated strings.

+

+`SymbolIndex` exposes `fn members_defining(name: &str) -> impl Iterator<Item = MemberRef>`.

+

+### 5. Lazy fetch API

+```rust

+impl<'a> Archive<'a> {

+    pub fn fetch(&mut self, name: &str) -> Option<ObjectFile>;

+}

+```

+

+Returns `None` if the archive does not define `name`. Fetching an archive member memoizes: a second lookup for the same member returns a cached handle. The resolution pass (Sprint 8) is the only caller.

+

+### 6. `-force_load` / `-all_load` support (semantics, not CLI yet)

+Archive has a `force_all(&mut self)` method that pre-fetches every member. Sprint 19 wires the CLI.

+

+### 7. Archive-of-archives

+Rare but legal: member can be another `.a`. Recurse one level. If a sub-archive defines `name`, the outer `fetch` returns the sub-member's object file and records a provenance chain for diagnostics.

+

+## Testing Strategy

+- Fixtures in `tests/corpus/archives/`:

+  - `libbsd.a` made by Apple `ar` (BSD flavor, extended filenames).

+  - `libsysv.a` made by GNU `ar` on Linux (for cross-check).

+  - `libthin.a` made by `ar --thin` (GNU-thin).

+  - `libmulti.a` containing several members each defining one or more symbols.

+- `cargo test -p afs-ld test_archive_bsd` verifies BSD index → correct member for each name.

+- Symbol-defining-two-members scenario: archive picks the one whose member comes first (ld's traditional rule).

+- Missing-symbol lookup returns `None`, does not error.

+- Thin-archive member file missing on disk produces a path-qualified diagnostic.

+

+## Definition of Done

+- All three archive flavors read.

+- `libarmfortas_rt.a` (built by parent workspace) parses and every runtime symbol is findable by name.

+- Archive-of-archives works one level deep.

+- Differential: `ar -t libarmfortas_rt.a` output matches our `--dump-archive` output.

+# Sprint 5: Dylibs (MH_DYLIB Binary)

+

+## Prerequisites

+Sprints 1–3 — Mach-O reading complete.

+

+## Goals

+Parse binary dylibs (`MH_DYLIB`). Extract exported symbols via the export trie or `LC_DYLD_CHAINED_FIXUPS` exports, resolve re-exports through umbrella frameworks, and expose a linkable `DylibFile` surface.

+

+## Deliverables

+

+### 1. DylibFile model

+`afs-ld/src/macho/dylib.rs`:

+

+```rust

+pub struct DylibFile {

+    pub path: PathBuf,

+    pub install_name: String,

+    pub current_version: u32,         // X.Y.Z packed

+    pub compat_version: u32,

+    pub is_umbrella: bool,

+    pub load_kind: DylibLoadKind,     // Normal, Weak, Reexport, Upward

+    pub ordinal: u16,                 // two-level namespace ordinal

+    pub reexports: Vec<PathBuf>,      // LC_REEXPORT_DYLIB paths

+    pub exports: ExportTrie,          // resolved during loading

+}

+

+pub enum DylibLoadKind { Normal, Weak, Reexport, Upward }

+```

+

+### 2. Load command decoding

+- `LC_ID_DYLIB` (for the dylib itself): install_name, timestamp, current_version, compat_version.

+- `LC_LOAD_DYLIB`: normal dependency.

+- `LC_LOAD_WEAK_DYLIB`: weak dep (imports allowed to be null at runtime).

+- `LC_REEXPORT_DYLIB`: dependency whose exports we rebroadcast (umbrella-framework case).

+- `LC_LOAD_UPWARD_DYLIB`: cyclic dependency escape hatch.

+

+### 3. Export trie decoder

+Export trie lives in `__LINKEDIT` pointed at by either `LC_DYLD_INFO_ONLY.export_off/export_size` (classic) or `LC_DYLD_CHAINED_FIXUPS.exports_trie_offset` (modern). Trie format:

+

+- Each node: ULEB128 terminal-size, optional terminal payload (flags ULEB + address ULEB, plus re-export or resolver data), then child count, then `(edge_string, child_offset_ULEB)` pairs.

+- Terminal flags: `EXPORT_SYMBOL_FLAGS_KIND_REGULAR`/`_THREAD_LOCAL`/`_ABSOLUTE`, `EXPORT_SYMBOL_FLAGS_WEAK_DEFINITION`, `EXPORT_SYMBOL_FLAGS_REEXPORT`, `EXPORT_SYMBOL_FLAGS_STUB_AND_RESOLVER`.

+

+```rust

+pub struct ExportTrie { /* walk-only view */ }

+impl ExportTrie {

+    pub fn lookup(&self, name: &str) -> Option<ExportEntry>;

+    pub fn iter(&self) -> impl Iterator<Item = (String, ExportEntry)>;

+}

+

+pub struct ExportEntry {

+    pub flags: u32,

+    pub address: u64,

+    pub reexport: Option<(u16 /*ordinal*/, String /*imported_name*/)>,

+    pub resolver: Option<u64>,

+}

+```

+

+Walking is recursive; we guard against malformed trees with a depth cap and visited-offset set.

+

+### 4. Two-level namespace ordinals

+Each dylib loaded by path gets an ordinal (1..=N) assigned in load-command order; `BIND_SPECIAL_DYLIB_SELF=0`, `BIND_SPECIAL_DYLIB_MAIN_EXECUTABLE=-1`, `BIND_SPECIAL_DYLIB_FLAT_LOOKUP=-2`, `BIND_SPECIAL_DYLIB_WEAK_LOOKUP=-3`. When an imported symbol is bound in Sprint 15, we use this ordinal.

+

+### 5. Re-export resolution

+Loading a dylib recursively loads its `LC_REEXPORT_DYLIB` chain. Names looked up in the umbrella are delegated down the chain. For CoreFoundation / Foundation style umbrella frameworks (not strictly required for armfortas today but landed now to avoid retrofit).

+

+### 6. SDK path resolution

+`-syslibroot <SDK>` + `-l<name>` needs to locate `${SDK}/usr/lib/lib<name>.{dylib,tbd}`. This sprint establishes the search order; the rest lands in Sprint 19's CLI work.

+

+## Testing Strategy

+- Fixtures: tiny hand-built `.dylib` via the system toolchain (one exported symbol, one re-export). Parsed and exports match `nm -g`.

+- Differential: load `CoreFoundation.tbd` in Sprint 6, not here; this sprint uses real binary `.dylib`s from `/usr/lib/` (where present on older macOS) or synthetic ones.

+- Malformed trie: cycle, out-of-bounds child offset, ULEB128 overrun — diagnostics, no panics.

+

+## Definition of Done

+- Export trie walker handles real `.dylib` files correctly.

+- `DylibFile` constructed with correct install_name, versions, ordinal.

+- Re-exports chained through umbrella fixtures.

+- `dyld_info -export <dylib>` output matches our export dumper.

+# Sprint 6: TAPI TBD Text Stubs

+

+## Prerequisites

+Sprint 5 — binary dylib reader works.

+

+## Goals

+Read `.tbd` files (TAPI text dylib stubs). On modern SDKs `libSystem`, `libc++`, and `CoreFoundation` ship only as `.tbd` — linking without this sprint means no system libraries, full stop.

+

+## Deliverables

+

+### 1. Minimal YAML subset

+TBD is YAML with a well-defined schema. We implement only the subset TAPI emits, not a general YAML parser:

+

+- Flow scalars (plain, single-quoted, double-quoted).

+- Flow sequences: `[ a, b, c ]`.

+- Block sequences: `- item`.

+- Block mappings: `key: value`.

+- Multi-document files with `---` / `...`.

+- Tags: `!tapi-tbd`.

+- Version directives: `%YAML 1.2`.

+

+No anchors, no aliases, no complex types, no folded scalars. If a real `.tbd` in the wild uses features outside the subset, the parser fails loudly with line/column.

+

+### 2. TBD schema

+`afs-ld/src/macho/tbd.rs`:

+

+```rust

+pub struct Tbd {

+    pub tbd_version: u32,      // 3 or 4

+    pub targets: Vec<Target>,  // arch + platform

+    pub install_name: String,

+    pub current_version: Option<String>,

+    pub compatibility_version: Option<String>,

+    pub parent_umbrella: Vec<Scoped<String>>,

+    pub allowable_clients: Vec<Scoped<String>>,

+    pub reexported_libraries: Vec<Scoped<String>>,

+    pub exports: Vec<Scoped<Exports>>,

+    pub reexports: Vec<Scoped<Exports>>,

+}

+

+pub struct Target { pub arch: Arch, pub platform: Platform }

+pub struct Scoped<T> { pub targets: Vec<Target>, pub value: T }

+pub struct Exports {

+    pub symbols: Vec<String>,

+    pub weak_symbols: Vec<String>,

+    pub thread_local_symbols: Vec<String>,

+    pub objc_classes: Vec<String>,

+    pub objc_eh_types: Vec<String>,

+    pub objc_ivars: Vec<String>,

+}

+```

+

+v3 and v4 both supported; v4 is what modern Xcode ships.

+

+### 3. Materialize into DylibFile

+`Tbd::into_dylib_file(tbd: Tbd, for_target: Target) -> DylibFile`. Filters scoped entries to only those matching `arm64 / macos`. Produces the same `DylibFile` surface Sprint 5 produces, so downstream code doesn't care about source format.

+

+### 4. SDK search implementation

+Integrate with `-syslibroot`. Search order for `-l<name>`:

+1. `${SDK}/usr/lib/lib<name>.tbd`

+2. `${SDK}/usr/lib/lib<name>.dylib`

+3. `${SDK}/usr/local/lib/lib<name>.tbd`

+4. `${SDK}/usr/local/lib/lib<name>.dylib`

+5. `-L<dir>` entries in order, same four suffixes.

+

+For frameworks (`-framework Foo`): `${SDK}/System/Library/Frameworks/Foo.framework/Foo.{tbd,dylib}`.

+

+### 5. Platform/arch filtering

+`Target { arch: Arm64, platform: MacOS }` is what armfortas cares about. If the TBD has no matching target, produce a clear diagnostic: "`<path>` does not export for arm64-macos".

+

+## Testing Strategy

+- Fixtures: copies of `${SDK}/usr/lib/libSystem.tbd`, `libc++.tbd`, `libobjc.tbd` checked into `tests/corpus/tbd/` (small, just headers of exported symbols — confirm they're not under a license that forbids redistribution; if so, generate equivalent fixtures).

+- Parse `libSystem.tbd`, assert that `_dyld_stub_binder`, `_malloc`, `_free`, `_printf` are all in exports.

+- Verify `DylibFile` produced is byte-level equivalent (in the fields we populate) to one produced by loading an actual `libSystem.dylib` from an older SDK.

+- Malformed YAML: missing `install_name`, tabs in indentation, unterminated quoted scalar — each with a precise diagnostic.

+

+## Definition of Done

+- Can read a modern Xcode `libSystem.tbd` and enumerate its exports.

+- SDK + `-l` + `-framework` resolution picks the right file on a real toolchain.

+- Differential test: hello-world link with `libSystem.tbd` produces the same bind entries as with a binary dylib (on older SDKs where both exist).

+# Sprint 7: Symbol Model & Table

+

+## Prerequisites

+Sprints 2, 4, 5, 6 — object, archive, dylib, TBD readers in place.

+

+## Goals

+A uniform symbol table that fuses definitions from every input kind. Establishes the invariants Sprint 8's resolution pass will preserve.

+

+## Deliverables

+

+### 1. `Symbol` sum type

+`afs-ld/src/symbol.rs`:

+

+```rust

+pub enum Symbol {

+    Undefined   { name: Istr, origin: InputId,        weak_ref: bool },

+    Defined     { name: Istr, origin: InputId, atom:  AtomId, value: u64,

+                  weak: bool, private_extern: bool, no_dead_strip: bool },

+    Common      { name: Istr, origin: InputId, size: u64, align_pow2: u8 },

+    DylibImport { name: Istr, dylib: DylibId, ordinal: u16, weak_import: bool },

+    LazyArchive { name: Istr, archive: ArchiveId, member: MemberId },

+    LazyObject  { name: Istr, origin: InputId },        // --start-lib / --end-lib

+    Alias       { name: Istr, aliased: Istr },          // N_INDR

+}

+```

+

+`Istr` = interned string handle. Interning happens once when a name first enters the table; all comparisons are handle-equality.

+

+### 2. `SymbolTable`

+```rust

+pub struct SymbolTable {

+    names: StringInterner,

+    by_name: HashMap<Istr, SymbolId>,

+    symbols: Vec<Symbol>,

+    // replacement log for diagnostics + -why_live

+    transitions: Vec<Transition>,

+}

+

+pub struct Transition { pub at: SymbolId, pub from: SymbolKindTag, pub to: SymbolKindTag, pub cause: Cause }

+```

+

+`HashMap` is fine for Sprint 7; Sprint 28 may swap in a custom open-addressing table.

+

+### 3. Insertion semantics

+`SymbolTable::insert(sym: Symbol)` runs the resolution rules inline:

+

+| Existing \ New       | Undefined | Defined | Common | DylibImport | LazyArchive | LazyObject |

+|----------------------|-----------|---------|--------|-------------|-------------|------------|

+| *vacant*             | insert    | insert  | insert | insert      | insert      | insert     |

+| Undefined            | keep      | replace | replace| replace     | replace     | replace    |

+| Defined (strong)     | keep      | **error if both strong and same kind** | keep | keep | keep | keep |

+| Defined (weak)       | keep      | replace if new strong | keep | keep | keep | keep |

+| Common               | keep      | replace (common → Defined) | pick larger size / stricter align | keep | keep | keep |

+| DylibImport          | keep      | replace (definition shadows import) | keep | keep | keep | keep |

+| LazyArchive          | **fetch** | replace | replace | replace | keep first | replace |

+| LazyObject           | **fetch** | replace | replace | replace | replace | keep |

+

+"Fetch" means: load the member/object, enqueue its symbols, mark this entry's transition.

+

+### 4. Weak coalescing rules

+- `weak_def` + `weak_def` → first wins.

+- `weak_def` + strong → strong wins.

+- Strong + strong → hard error, diagnostic cites both input paths.

+- `weak_ref` without a definition is not an error; the reference resolves to address 0 (handled in relocation pass).

+

+### 5. Aliases (N_INDR)

+Flattened on insertion: an `Alias(name → aliased)` is resolved by looking up `aliased`. If `aliased` is itself an alias, walk until a non-alias is found; cycle detection with a depth cap.

+

+### 6. Transition log

+Every `insert` records the old/new kind + input path + (for lazy fetches) the reason the fetch happened. The `-why_live` diagnostic introduced in Sprint 19 reads this log.

+

+### 7. Tombstoned symbols

+Common → Defined promotion preserves the common size and alignment (so the BSS slot is large enough). Dead-stripping (Sprint 23) can tombstone a Defined without removing it from the table.

+

+## Testing Strategy

+- Unit tests for every cell in the resolution matrix. Each combination has a named test.

+- Synthetic inputs: two `.o`s both defining `_foo` strong → error; one strong + one weak → strong wins; two weak → first wins; common + strong → common replaced.

+- Alias-chain cycles detected with a diagnostic, not a stack overflow.

+- Interner stress test: 100K unique names, membership queries are O(1) average.

+

+## Definition of Done

+- Every matrix cell has a passing test.

+- Weak coalescing matches `ld` on a corpus of 20+ scenarios (differential test: both linkers produce the same `nm` output).

+- Alias flattening correct and cycle-safe.

+- Transition log surfaces replacement causes for `-why_live`.

+# Sprint 8: Name Resolution Pass

+

+## Prerequisites

+Sprint 7 — `SymbolTable` with insertion semantics.

+

+## Goals

+Drive the symbol table to a fixed point: every undefined reference either resolves to a Defined (from an object), Common (promoted in BSS), DylibImport (from a dylib/TBD), or raises a clear, actionable diagnostic. `-force_load` / `-all_load` / `-undefined <treatment>` all handled.

+

+## Deliverables

+

+### 1. Resolution algorithm

+`afs-ld/src/resolve.rs`:

+

+```rust

+pub fn resolve(inputs: &mut Inputs, table: &mut SymbolTable, opts: &LinkOptions)

+    -> Result<(), Vec<ResolveError>>

+{

+    seed_table_with_objects_and_dylib_imports(inputs, table, opts);

+    if opts.all_load    { force_load_everything(inputs, table); }

+    for forced in &opts.force_load { force_load_one(inputs, table, forced); }

+    fixed_point_pull_from_archives(inputs, table);

+    classify_unresolved(table, opts);

+}

+```

+

+### 2. Seed phase

+Walk every explicit `.o` first, then every `.dylib` / `.tbd`: add Defined / Common from objects, DylibImport from dylibs. Archives are added as LazyArchive entries only — their members are not parsed until pulled.

+

+### 3. Fixed-point pull

+```

+while let Some(name) = table.undefined_pending.pop() {

+    for archive in &inputs.archives_in_command_line_order {

+        if let Some(member) = archive.fetch(name) {

+            ingest_member(member, table);

+            break;

+        }

+    }

+}

+```

+

+Order matters: armfortas's driver currently passes `<objs> <runtime.a> -lSystem`, and resolution must match `ld`'s left-to-right behavior. Ingesting a member can create new undefined pending names; loop terminates when no member was fetched this round.

+

+### 4. `-force_load` and `-all_load`

+- `-force_load <archive>`: pull every member of that archive before fixed-point.

+- `-all_load`: pull every member of every archive.

+- Both happen before the fixed-point loop so their transitively-pulled symbols feed into the same fixed point.

+

+### 5. `-undefined <treatment>`

+After the fixed point, any still-Undefined entry is classified by the `-undefined` setting:

+- `error` (default): hard error, cite every input that references the name (collected via the transition log).

+- `warning`: warn but emit, writing the symbol as address 0 (bind to nothing).

+- `suppress`: silent, address 0.

+- `dynamic_lookup`: flat-namespace DylibImport with ordinal `BIND_SPECIAL_DYLIB_FLAT_LOOKUP=-2`.

+

+### 6. Weak references

+`weak_ref` to a missing symbol is always valid regardless of `-undefined`; it resolves to address 0 at bind time and the runtime tests for null.

+

+### 7. Diagnostics

+Undefined errors must cite every referrer input, not just one. Output format:

+

+```

+afs-ld: error: undefined symbol: _afs_print

+      referenced by program.o(text section + 0x34)

+      referenced by runtime.o(text section + 0x120)

+      (also via 2 relocations in libarmfortas_rt.a(io.o))

+Hint: did you mean _afs_print_real? (Levenshtein distance 5)

+```

+

+Did-you-mean uses a basic Levenshtein-3 search over defined symbols.

+

+### 8. Diagnostics for duplicate strong

+```

+afs-ld: error: duplicate symbol _foo

+  defined in: a.o (text + 0x0)

+  also in:    b.o (text + 0x0)

+```

+

+No suggestion — two strong defs is a real ambiguity.

+

+## Testing Strategy

+- Resolution matrix revisited from Sprint 7, but with real archives and dylibs.

+- Order sensitivity: `a.o b.a` vs `b.a a.o` — first resolves when `a.o` references a symbol in `b.a`; second does not (matches `ld`'s classic behavior).

+- `-force_load` pulls in a member whose symbols would otherwise go unreferenced.

+- `-all_load` across a multi-member archive.

+- Weak-import from a dylib that at runtime will be missing.

+- Did-you-mean fires on a close misspell, stays silent when the closest match is > 3 edits away.

+

+## Definition of Done

+- Fixed-point loop terminates on all corpus inputs.

+- Diagnostics match the format above, include every referrer, include did-you-mean suggestions.

+- Differential test against `ld` for order-dependent resolution on 10+ scenarios.

+- `-force_load` / `-all_load` / `-undefined=*` all pass dedicated tests.

+# Sprint 9: Subsections-via-Symbols Atomization

+

+## Prerequisites

+Sprints 2, 7, 8 — sections, symbols, resolved table.

+

+## Goals

+Split each input section into **atoms** at symbol boundaries when `MH_SUBSECTIONS_VIA_SYMBOLS` is set (afs-as always sets this). Atoms are the unit of dead-stripping (Sprint 23), ICF (Sprint 24), and output layout (Sprint 10). Every Defined symbol owns exactly one atom.

+

+## Deliverables

+

+### 1. Atom model

+`afs-ld/src/atom.rs`:

+

+```rust

+pub struct Atom {

+    pub id: AtomId,

+    pub owner: SymbolId,           // the primary symbol defining this atom

+    pub alt_entries: Vec<SymbolId>, // .alt_entry chains

+    pub section: OutputSectionKey,  // which output section it will land in

+    pub input_origin: InputId,

+    pub input_section: SectIdx,

+    pub offset: u32,                // offset within input section

+    pub size: u32,

+    pub align_pow2: u8,

+    pub data: DataRef,              // borrowed from input mmap, or ZeroFill

+    pub relocs: Vec<RelocIdx>,      // relocs originating inside this atom

+    pub flags: AtomFlags,           // NoDeadStrip, WeakDef, ThreadLocal, ...

+}

+```

+

+### 2. Atomization algorithm

+For each input section:

+1. Collect every Defined symbol whose section is this section, sorted by value.

+2. If `MH_SUBSECTIONS_VIA_SYMBOLS` is set: split the section at each symbol's offset. Each slice becomes an atom owned by the symbol at its head.

+3. If a symbol is `.alt_entry`, fold it into the previous atom's `alt_entries`, don't split.

+4. If the flag is not set: one atom per section (Apple-style consolidated section).

+

+Atoms for text preserve instruction alignment; atoms for zerofill carry size only.

+

+### 3. Literal atoms (C strings, 16-byte literals)

+`__TEXT,__cstring` and `__TEXT,__literal16` are special. Every null-terminated string / every 16-byte block is an atom candidate for de-duplication (Sprint 24 ICF). For now, store each literal as its own atom with a content-hash annotation.

+

+### 4. Unwind + compact-unwind atoms

+`__TEXT,__compact_unwind` contains 32-byte records, each referring (via a reloc) to a function atom. One unwind atom per function; tracked as `parent_of: AtomId` so unwind atoms get stripped alongside dead functions.

+

+### 5. Reloc → atom remapping

+Every reloc has an input offset into its source section. After atomization, recompute as `(atom, offset_within_atom)`. When a reloc crosses atom boundaries it can only point at a whole symbol (subsections-via-symbols invariant); confirm this and diagnose if not.

+

+### 6. Reloc references to atoms

+`Reloc::referent` gains:

+```rust

+pub enum Referent {

+    SymbolExternal(SymbolId),       // undefined or dylib import

+    SymbolLocal(AtomId, i64),       // same-tu reference, addend in bytes

+    AbsoluteSection(AtomId, i64),   // rare, section-relative

+}

+```

+

+The "local" case is what the atomization unlocks: a reloc from function `_a` to function `_b` in the same `.o` becomes a reference to `_b`'s atom, not to an offset within a monolithic text section.

+

+### 7. `.no_dead_strip` propagation

+Symbol flag propagates to its atom. Unwind atoms inherit `NoDeadStrip` from their parent function. Entry point symbol is marked `NoDeadStrip`.

+

+## Testing Strategy

+- Fixture: a `.s` with several functions where one branches to another. After atomization, reloc's referent must be the callee atom, not a byte-offset.

+- `.alt_entry` folding: `_foo` and `.alt_entry _bar` in the same input produce one atom whose `alt_entries = [_bar]`.

+- Boundary-crossing reloc (synthesized maliciously): parser diagnoses.

+- Differential: `ld -dead_strip` behavior on a corpus of ~20 atomization fixtures compared to what Sprint 23 will produce.

+

+## Definition of Done

+- Every `.o` in the afs-as corpus atomizes without diagnostics.

+- `.alt_entry` correctly folded.

+- Relocs re-targeted to atoms; no raw section-relative references leak into Sprint 10.

+- Unwind atoms track their parent function atom.

+# Sprint 10: Output Segment & Section Layout (dylib-aware)

+

+## Prerequisites

+Sprints 7–9 — resolved table and atomized inputs.

+

+## Goals

+One layout engine, two modes: `MH_EXECUTE` and `MH_DYLIB`. Assign VM addresses, file offsets, and segment membership to every atom. End state: the writer can emit a valid-but-empty Mach-O for both modes that `otool -lV` accepts.

+

+## Deliverables

+

+### 1. Output segment & section model

+`afs-ld/src/section.rs`:

+

+```rust

+pub struct OutputSegment {

+    pub name: String,           // "__TEXT", "__DATA_CONST", "__DATA", "__LINKEDIT", "__PAGEZERO"

+    pub sections: Vec<OutputSectionId>,

+    pub vm_addr: u64, pub vm_size: u64,

+    pub file_off: u64, pub file_size: u64,

+    pub init_prot: Prot, pub max_prot: Prot,

+}

+

+pub struct OutputSection {

+    pub segment: String, pub name: String,    // e.g. ("__TEXT", "__text")

+    pub kind: SectionKind,

+    pub align_pow2: u8, pub flags: u32,

+    pub atoms: Vec<AtomId>,

+    pub addr: u64, pub size: u64, pub file_off: u64,

+}

+```

+

+### 2. Segment plan

+Two plans, keyed by `OutputKind::Executable | Dylib`:

+

+**Executable**:

+- `__PAGEZERO`: VM `[0, 0x1_0000_0000)`, prot `---`. No file backing.

+- `__TEXT`: prot `r-x`. Contains `__text`, `__stubs`, `__stub_helper`, `__cstring`, `__const`, `__literal16`, `__unwind_info`, `__eh_frame`.

+- `__DATA_CONST`: prot `r--` (rebased to `r--` by dyld after fixups). Contains `__got`, `__const` data.

+- `__DATA`: prot `rw-`. Contains `__data`, `__bss`, `__la_symbol_ptr`, `__thread_ptrs`, `__thread_vars`, `__thread_data`, `__thread_bss`.

+- `__LINKEDIT`: prot `r--`. Symbol table, string table, dyld-info opcodes (or chained fixups), function starts, data-in-code, code signature.

+

+**Dylib**:

+- No `__PAGEZERO`. `__TEXT` starts at VM `0`.

+- Everything else the same.

+

+### 3. Section placement order within segments

+Matches ld's defaults so differential testing converges:

+- `__TEXT`: `__text`, `__stubs`, `__stub_helper`, `__cstring`, `__const`, `__literal16`, `__unwind_info`, `__eh_frame`.

+- `__DATA_CONST`: `__got`, `__const`.

+- `__DATA`: `__la_symbol_ptr`, `__data`, `__thread_vars`, `__thread_ptrs`, `__thread_data`, `__thread_bss`, `__bss`.

+- `__LINKEDIT`: fixup stream, function starts, data-in-code, symbol table, string table, code signature (in that order — matches ld's observed layout).

+

+Missing sections are simply absent; empty sections are dropped entirely.

+

+### 4. Atom placement

+Each atom maps to one output section by its `OutputSectionKey`. Within a section, atoms ordered by:

+1. Input-file command-line order.

+2. Within an input, atom original offset.

+3. Tiebreaker: symbol name (for determinism).

+

+ICF (Sprint 24) and `-order_file` (later polish) will override this later; for now, deterministic default.

+

+### 5. Address assignment

+Pass 1: accumulate sizes per section, respecting atom alignment. Pass 2: assign section `addr` by accumulating `vm_addr + padding-to-section-alignment`. Pass 3: file offsets — `__TEXT` starts at file 0 (header lives there); other segments at next 4 KiB boundary. Zerofill sections have `size > 0` but contribute 0 to file size.

+

+Page alignment is 16 KiB on arm64 (Apple Silicon always). Section alignment comes from atoms.

+

+### 6. MH_EXECUTE vs MH_DYLIB writer dispatch

+`afs-ld/src/macho/writer.rs`:

+

+```rust

+pub enum OutputKind { Executable, Dylib }

+

+pub fn write(layout: &Layout, kind: OutputKind, opts: &LinkOptions, out: &mut Vec<u8>)

+    -> Result<(), WriteError>;

+```

+

+Dispatches to the right load-command set:

+- Executable: `LC_MAIN` with entry offset, optional `LC_UUID`, `LC_SOURCE_VERSION`.

+- Dylib: `LC_ID_DYLIB` with install-name, current-version, compat-version; no `LC_MAIN`.

+- Both: `LC_SEGMENT_64` per segment, `LC_BUILD_VERSION`, `LC_SYMTAB`, `LC_DYSYMTAB`, `LC_DYLD_INFO_ONLY` or `LC_DYLD_CHAINED_FIXUPS`, `LC_FUNCTION_STARTS`, `LC_DATA_IN_CODE`, one `LC_LOAD_DYLIB` per dylib dependency, `LC_RPATH` entries, `LC_CODE_SIGNATURE`.

+

+### 7. Minimum-viable empty output

+End-of-sprint gate: both `OutputKind::Executable` (empty `_main`) and `OutputKind::Dylib` (no exports) emit a file that:

+- `otool -lV` accepts without complaint.

+- `file` identifies as `Mach-O 64-bit executable arm64` / `Mach-O 64-bit dynamically linked shared library arm64`.

+- Does not yet need to run or load — just parse.

+

+## Testing Strategy

+- Snapshot tests: produce the minimal empty executable and dylib; compare load-command layout against a golden captured from `ld`.

+- Differential: for empty inputs, our load-command order and segment protections must match `ld`'s.

+- Golden section-ordering tests for the standard ld section order.

+

+## Definition of Done

+- Empty executable output passes `otool -lV`.

+- Empty dylib output passes `otool -lV`.

+- Section placement order matches `ld` on a corpus of staged fixtures.

+- Address assignment deterministic across 100 invocations of the same input.

+# Sprint 11: Core Relocation Application (ARM64)

+

+## Prerequisites

+Sprints 3, 9, 10 — relocs parsed, atoms sized, addresses assigned.

+

+## Goals

+Patch atom bytes according to every basic ARM64 reloc kind. This sprint covers `BRANCH26`, `PAGE21`, `PAGEOFF12`, `UNSIGNED`, `SUBTRACTOR`, and the folded `ADDEND`. GOT/stubs land in Sprint 12, TLV in Sprint 13.

+

+## Deliverables

+

+### 1. Reloc application pass

+`afs-ld/src/reloc/arm64.rs`:

+

+```rust

+pub fn apply(layout: &Layout, atom: &Atom, bytes: &mut [u8]) -> Result<(), RelocError>;

+```

+

+For each reloc in the atom:

+1. Resolve `Referent` to a final address (atom.addr + referent.atom.offset + addend, or dylib import → 0 for now, handled fully in Sprint 12).

+2. Compute the reloc value per kind.

+3. Patch `bytes` at `reloc.offset`.

+

+### 2. Reloc math (reference)

+

+| Kind | Formula | Encoding |

+|---|---|---|

+| `Unsigned` (length=2) | `S + A` | little-endian u32 write |

+| `Unsigned` (length=3) | `S + A` | little-endian u64 write |

+| `Subtractor` | `S_min - S_sub + A` | u32 or u64 depending on length |

+| `Branch26` | `(S + A - P) >> 2` | 26-bit sign-check, OR into bottom 26 bits of the instruction |

+| `Page21` | `(page(S+A) - page(P)) >> 12` | ADRP immhi:immlo encoding, 21-bit sign-check |

+| `PageOff12` | `(S + A) & 0xFFF` | ADD imm12 or LDR imm12 (scaled per LDR size!) |

+

+Where `S` = symbol/section address, `A` = addend, `P` = address of the relocated instruction, `page(x) = x & ~0xFFF`.

+

+### 3. PAGEOFF12 scaling detail

+For `LDR` immediate-offset forms the 12-bit immediate is scaled by the load size (1 for `LDRB`, 2 for `LDRH`, 4 for `LDR W`, 8 for `LDR X`). afs-as sets the instruction bits correctly; our job is to right-shift the 12-bit offset by the load size's log2 before OR'ing into the instruction. The `size` nibble of the LDR encoding tells us the shift.

+

+For `ADD` immediate-offset the 12-bit immediate is unscaled — write as-is.

+

+Disambiguate by disassembling the instruction: opcode bits `[31:24]` distinguish ADD vs LDR (B/H/W/X).

+

+### 4. Range checks

+- `Branch26`: `(S + A - P)` must fit in signed 28 bits (26 bits × 4-byte scale). If not, emit a hard error citing the caller atom and the out-of-range target. Thunks land in Sprint 26.

+- `Page21`: `(page(S+A) - page(P))` must fit in signed 33 bits (21 bits × 4 KiB scale). In practice, always satisfiable on macOS.

+- `PageOff12`: always fits by construction.

+- `Unsigned`: wraps silently.

+

+### 5. Subtractor + Unsigned pair

+A `RelocKind::Subtractor` entry carries both the minuend and subtrahend. Formula: `target = minuend.addr + minuend_addend - (subtrahend.addr + subtrahend_addend)`. Write as u32 or u64 depending on length. afs-as uses this for `.quad _a - _b` and for CIE offset diff in `__eh_frame`.

+

+### 6. PC vs atom address

+`P` is the address of the relocated 4-byte instruction, `atom.addr + reloc.offset`. `P` for an `Unsigned` reloc still evaluates even when `pcrel=false`; the formula just doesn't use it. A wrong `P` is the most common reloc bug — unit test every kind against a hand-computed value.

+

+### 7. Error reporting

+Every failed reloc cites the originating input + atom + offset + kind + referent. No panics.

+

+### 8. Defer: GOT and TLVP

+`GOT_LOAD_PAGE21`, `GOT_LOAD_PAGEOFF12`, `POINTER_TO_GOT`, `TLVP_LOAD_*` — Sprint 12 and Sprint 13 allocate the synthetic sections and wire them. This sprint emits a clear "not yet implemented" error if encountered.

+

+## Testing Strategy

+- Unit test each kind with hand-computed encodings cross-checked against ARM ARM and `otool -tv` disassembly.

+- Differential: identical inputs through `ld` and afs-ld produce the same patched bytes (within allowed-diff categories from Sprint 0's harness).

+- Corner cases: max-negative branch, wrap-around UNSIGNED addend, SUBTRACTOR across sections, SUBTRACTOR within same section.

+- Regression fixture: a tiny `.o` that exercises every kind covered in this sprint.

+

+## Definition of Done

+- All covered reloc kinds apply correctly against a corpus of fixtures.

+- Out-of-range BRANCH26 emits an actionable error.

+- Differential pass: 10+ fixtures link to byte-identical `__text` under afs-ld and `ld`.

+- GOT/TLVP kinds emit "not yet implemented" errors with a pointer to Sprints 12/13.

+# Sprint 12: GOT, Stubs, Lazy Pointers

+

+## Prerequisites

+Sprints 5, 10, 11 — dylibs loaded, layout pass, core reloc application.

+

+## Goals

+Synthesize `__got`, `__stubs`, `__stub_helper`, `__la_symbol_ptr`. Wire `GOT_LOAD_*` / `POINTER_TO_GOT` relocations to GOT slots. Rewire `BRANCH26` to a dylib import through a stub. Classic lazy-binding model; chained fixups land in Sprint 15.5.

+

+## Deliverables

+

+### 1. GOT synthetic section

+`afs-ld/src/synth/got.rs`:

+

+```rust

+pub struct GotSection {

+    entries: Vec<GotEntry>,

+    index: HashMap<SymbolId, usize>,

+}

+

+pub struct GotEntry { pub symbol: SymbolId, pub weak_import: bool }

+```

+

+- Lives in `__DATA_CONST,__got`, section flags `S_NON_LAZY_SYMBOL_POINTERS` (type = 6). `reserved1` in the section header = the starting indirect-symbol-table index.

+- 8 bytes per entry, aligned 8.

+- GOT entry for a Defined symbol holds that symbol's address directly (no dyld bind).

+- GOT entry for a DylibImport is zeroed in the file; dyld binds it at load time via the non-lazy bind stream (Sprint 15).

+

+### 2. Stubs synthetic section

+`afs-ld/src/synth/stubs.rs`:

+

+ARM64 stub is 12 bytes:

+```

+ADRP x16, la_symbol_ptr@PAGE

+LDR  x16, [x16, la_symbol_ptr@PAGEOFF]

+BR   x16

+```

+

+- Lives in `__TEXT,__stubs`, section flags `S_SYMBOL_STUBS | S_ATTR_PURE_INSTRUCTIONS | S_ATTR_SOME_INSTRUCTIONS` (type = 8). `reserved1` = starting indirect-sym index, `reserved2` = 12 (stub size).

+- One stub per dylib-imported function whose address is branched to (`BRANCH26` target).

+

+### 3. Lazy symbol pointers

+`__DATA,__la_symbol_ptr`, section flags `S_LAZY_SYMBOL_POINTERS` (type = 7). Each 8-byte entry is initialized to point at the corresponding `__stub_helper` entry; at first call, the stub-helper resolves the symbol and patches the lazy pointer.

+

+### 4. Stub helper

+`__TEXT,__stub_helper`:

+

+Header (24 bytes on arm64):

+```

+ADRP x17, __dyld_private@PAGE

+ADD  x17, x17, __dyld_private@PAGEOFF

+STP  x16, x17, [sp, #-16]!

+ADRP x16, dyld_stub_binder@GOTPAGE

+LDR  x16, [x16, dyld_stub_binder@GOTPAGEOFF]

+BR   x16

+```

+

+Per-symbol entry (12 bytes):

+```

+LDR  w16, =<lazy_bind_offset>

+B    <header_addr>

+```

+

+Where `<lazy_bind_offset>` is the offset of this symbol's opcode sequence within the `__LINKEDIT` lazy-bind stream (Sprint 15 wires this).

+

+Needs `___dyld_private` (local anchor) and `_dyld_stub_binder` (dylib import from `libSystem`).

+

+### 5. Binding strategy

+- `_dyld_stub_binder` is imported from `libSystem`. Gets a GOT entry; no stub (we take its address directly).

+- `___dyld_private` is a 0-filled 8-byte slot in `__DATA,__data`. Not exported. Dyld uses it as scratch during binding.

+

+### 6. Reloc rewiring

+Relocation application pass (Sprint 11 + this):

+

+- `GOT_LOAD_PAGE21` / `GOT_LOAD_PAGEOFF12` → target = GOT slot address.

+- `POINTER_TO_GOT` → target = GOT slot address (used for 32-bit pointer-to-GOT references).

+- `BRANCH26` to a dylib import → target = stub address.

+- `BRANCH26` to a Defined → target unchanged (direct call).

+- `BRANCH26` to an Undefined resolved via `-undefined dynamic_lookup` → target = stub address.

+

+### 7. Indirect symbol table

+`__LINKEDIT` indirect-symbol table = list of u32 symbol-table indices, used by dyld to map each stub / lazy pointer / GOT slot entry back to its symbol. Populated here, pointed at by `LC_DYSYMTAB.indirectsymoff`.

+

+### 8. Weak-import dylib functions

+`weak_import` symbols get stubs whose lazy binding opcode sequence includes the `BIND_SYMBOL_FLAGS_WEAK_IMPORT` flag. At runtime, if the symbol is missing, dyld patches the lazy pointer to 0 instead of erroring. The call site must test for null before branching — that's user code's responsibility.

+

+## Testing Strategy

+- Hello-world staging fixture: a `.o` that calls `_printf` + references `_errno`. Produces `__stubs`, `__la_symbol_ptr`, `__stub_helper`, `__got` in the expected order and sizes.

+- Differential: stub/lazy-pointer/GOT layout byte-identical to `ld` on the staging fixture.

+- Reloc-rewire test: `BRANCH26` to a dylib-imported function lands in the stub, not in the dylib directly.

+- Disassembly test: `otool -v -t` on `__stubs` matches the expected three-instruction sequence for every entry.

+

+## Definition of Done

+- GOT, stubs, lazy pointers, stub helper all emitted with correct flags and `reserved*` fields.

+- Indirect symbol table populated correctly (Sprint 14 consumes it).

+- BRANCH26-to-dylib correctly rewired to stubs.

+- Differential pass on the staging hello-world fixture.

+# Sprint 13: TLV Relocations

+

+## Prerequisites

+Sprint 12 — GOT-like synthesis patterns established.

+

+## Goals

+Support thread-local variables: the full chain from afs-as's `__thread_vars` / `__thread_data` / `__thread_bss` through `__DATA,__thread_ptrs` into the ARM64 TLV runtime call. `TLVP_LOAD_PAGE21` and `TLVP_LOAD_PAGEOFF12` relocations applied correctly.

+

+## Deliverables

+

+### 1. TLV descriptor layout

+Apple's TLV model: each TLV gets a 3-word descriptor in `__DATA,__thread_vars` (section type `S_THREAD_LOCAL_VARIABLES`, 0x13):

+

+```

+u64 thunk_addr;   // pointer to tlv_get_addr (libSystem) — rebased/bound at load

+u64 key;          // pthread_key_t, set to 0 initially

+u64 offset;       // offset of the variable's initial data within __thread_data

+```

+

+afs-as emits the descriptor template (thunk_addr = 0, key = 0, offset = section-relative to `__thread_data` or `__thread_bss`). afs-ld:

+

+- Patches `thunk_addr` to reference `_tlv_bootstrap` (from libSystem) via `__DATA,__thread_ptrs`.

+- Leaves `key = 0` (runtime initializes on first access).

+- Adjusts `offset` to be the final VM offset into the laid-out `__thread_data` / `__thread_bss` section.

+

+### 2. `__DATA,__thread_ptrs` synth

+Section type `S_THREAD_LOCAL_VARIABLE_POINTERS` (0x16). Contains non-lazy pointers to the TLV thunk function (`_tlv_bootstrap` from libSystem). One 8-byte entry per imported TLV thunk. Equivalent to the GOT for TLVs.

+

+### 3. TLVP reloc application

+`TLVP_LOAD_PAGE21` and `TLVP_LOAD_PAGEOFF12` resolve to a `__thread_ptrs` entry (not a `__thread_vars` descriptor directly). The thread-local access sequence afs-as emits:

+

+```

+ADRP  x0, _tlv@TLVPPAGE

+LDR   x0, [x0, _tlv@TLVPPAGEOFF]   ; x0 = &thread_ptrs[_tlv]

+LDR   x1, [x0]                       ; x1 = &tlv_descriptor (actually thunk ptr!)

+BLR   x1                              ; returns address of TLV body in x0

+```

+

+Wait — re-check Apple's TLV ABI. The correct sequence: `__thread_ptrs` entry is a pointer to the TLV descriptor (the 3-word thing in `__thread_vars`). The sequence loads `[desc+0]` = thunk, `[desc+8]` = key, and calls the thunk with the descriptor address in `x0`. The thunk reads the key, calls `pthread_getspecific` if needed, and returns the body address. Verify against reference in `.refs/ld64/` before coding.

+

+### 4. Coordinate with afs-as section layout

+afs-as emits:

+- `__DATA,__thread_data` (S_THREAD_LOCAL_REGULAR, 0x11): TLV initializers.

+- `__DATA,__thread_bss` (S_THREAD_LOCAL_ZEROFILL, 0x12): zero-initialized TLVs.

+- `__DATA,__thread_vars` (S_THREAD_LOCAL_VARIABLES, 0x13): descriptors.

+

+afs-ld preserves these three sections and adds `__DATA,__thread_ptrs` (S_THREAD_LOCAL_VARIABLE_POINTERS, 0x16).

+

+### 5. `_tlv_bootstrap` import

+Auto-injected as an undefined symbol (if any TLV descriptor needs it), resolves from `libSystem`. Its GOT-equivalent entry lives in `__DATA,__thread_ptrs`, not `__DATA_CONST,__got` (TLV has its own indirection).

+

+### 6. Zero TLVs early-out

+If no input section has `S_THREAD_LOCAL_*` contents and no reloc has a TLVP kind, emit no TLV sections at all.

+

+## Testing Strategy

+- Fixture: a `.f90` with `THREADPRIVATE` → `.o` with `__thread_vars`, `__thread_data`, `__thread_bss` and TLVP relocs. Link with afs-ld and with `ld`. Diff the resulting TLV descriptors, `__thread_ptrs`, and reloc-patched bytes.

+- Runtime test: link a tiny C program that reads a TLV via the Apple TLV ABI sequence, run it, check output.

+- Zero-TLV fixture: no TLV sections leak into the output.

+

+## Definition of Done

+- `TLVP_LOAD_*` relocs apply correctly.

+- `__thread_ptrs` emitted with correct type flag and entries.

+- `_tlv_bootstrap` imported only when needed.

+- Runtime test loads and reads a TLV correctly under afs-ld.

+# Sprint 14: LC_SYMTAB / LC_DYSYMTAB / String Table

+

+## Prerequisites

+Sprints 10–13 — layout, relocs, GOT/stubs/TLV all emitted.

+

+## Goals

+Build the final symbol table, string table, and `LC_DYSYMTAB` partitioning expected by dyld. Byte-level matches with `ld`'s layout on simple inputs.

+

+## Deliverables

+

+### 1. Symbol table partitioning

+dyld requires symbols in this order inside `LC_SYMTAB`:

+

+1. **Locals** (ilocalsym..ilocalsym+nlocalsym): private Defined + `N_PEXT` private-external symbols, debug stabs (we have none from afs-as today), `N_STAB` entries.