+# Sprint 0-9 Closeout Checklist

+

+Concrete closeout checklist based on the current codebase audit.

+

+Current conclusion: we are not ready to honestly declare Sprint 10 complete-in-practice yet.

+The main blockers are:

+

+- Sprint 0's tolerated-diff categories are still deferred until afs-ld can emit real linked output for Mach-O-to-Mach-O differential checks.

+

+## Sprint 10 Gate

+

+Do not declare "we are on Sprint 10" until all of these are true:

+

+- [x] Sprint 9 reloc referents are remapped to atom-aware forms.

+- [x] Sprint 8 resolution orchestration exists as a real callable stage, not just loose helper APIs.

+- [x] `cargo test -p afs-ld` is green after the closeout work.

+- [x] `cargo clippy -p afs-ld --all-targets -- -D warnings` is green after the closeout work.

+- [x] `README.md` and sprint docs no longer materially misstate the current state of the crate.

+

+## Recommended Order

+

+- [x] Close Sprint 9 reloc-to-atom remap first.

+- [x] Close Sprint 8 resolution orchestration and option coverage second.

+- [x] Close Sprint 6 TBD/SDK search gaps third.

+- [x] Close Sprint 4 nested archive support fourth.

+- [ ] Finish the deferred Sprint 0 differential-harness tolerance work once afs-ld can emit real output.

+

+## Cross-Sprint Exit Criteria

+

+- [ ] Every closeout chunk lands with tests.

+- [ ] Every bug fix or behavioral gap gets a regression test.

+- [ ] No newly-discovered roadmap/code mismatch is left undocumented.

+- [ ] Any user-facing diagnostic we touch stays deterministic and testable.

+

+## Sprint 0

+

+Status: closed

+

+Validated:

+

+- [x] `afs-ld` exists as its own git submodule in the parent workspace.

+- [x] Parent `Cargo.toml` includes `afs-ld` as a workspace member.

+- [x] `CLAUDE.md`, `README.md`, crate wiring, and test harness scaffolding exist.

+- [x] Reference repos are present under parent `.refs/` (`ld64`, `mold`, `lld`).

+- [x] `tests/reader_empty.rs` enforces the empty-invocation CLI contract.

+- [x] `tests/diff_harness_sanity.rs` and `tests/diff_harness_finds_critical.rs` exist and pass.

+- [x] `cargo clippy -p afs-ld --all-targets -- -D warnings` is currently clean.

+

+Remaining closeout work:

+

+- [x] Explicitly downscope Sprint 0 docs so the current diff harness is described as synthetic until end-to-end linking exists.

+- [ ] Add tolerated-diff categories once real Mach-O-to-Mach-O comparisons exist.

+

+## Sprint 1

+

+Status: closed

+

+Validated:

+

+- [x] Mach-O constants are duplicated locally in `src/macho/constants.rs`.

+- [x] `MachHeader64` parsing exists and rejects malformed headers.

+- [x] Load-command dispatch exists and preserves unknown commands as raw bytes.

+- [x] Segment and section-header metadata parsing exists.

+- [x] `LC_BUILD_VERSION` and `LC_LINKER_OPTIMIZATION_HINT` decoding exists.

+- [x] `--dump` exists through `src/dump.rs` and `src/main.rs`.

+- [x] Corpus round-trip tests pass in `tests/reader_corpus_round_trip.rs`.

+

+Remaining closeout work:

+

+- [x] Add an `otool -lV` parity test for dumper output shape across the corpus.

+- [x] Add a panic-focused malformed-input stress pass beyond the current unit tests so the "no panics on malformed input" claim is defensible.

+

+## Sprint 2

+

+Status: closed

+

+Validated:

+

+- [x] Section classification exists in `src/section.rs`.

+- [x] `InputSection` carries section data and raw relocation bytes.

+- [x] `RawNlist` / `InputSymbol` parsing and classification exist in `src/symbol.rs`.

+- [x] Common symbols, weak flags, private externs, and indirect aliases are surfaced.

+- [x] `StringTable` exists and handles suffix-dedup overlaps.

+- [x] `DysymtabCmd` is parsed and exposed through `ObjectFile`.

+- [x] `ObjectFile` integrates header, commands, sections, symbols, strings, and dysymtab.

+

+Remaining closeout work:

+

+- [x] Add `nm -a` parity tests for symbol view and classification.

+- [x] Add `otool -r` parity checks for relocation-offset surfaces promised by Sprint 2, with section/load-command parity covered by the Sprint 1 `otool -lV` gate.

+- [x] Add stronger malformed-symbol / malformed-string-table stress coverage if we want the "never panics" bar to be explicit.

+

+## Sprint 3

+

+Status: closed enough for current closeout

+

+Validated:

+

+- [x] ARM64 relocation constants exist.

+- [x] Raw relocation parsing and writing exist.

+- [x] Fused `Reloc` form exists.

+- [x] `ADDEND` and `SUBTRACTOR + UNSIGNED` pairing is fused in `parse_relocs`.

+- [x] Validation logic exists in `validate_relocs`.

+- [x] Write-side round-trip support exists.

+- [x] Unit coverage is broad and current corpus relocation round-trips pass.

+

+Remaining closeout work:

+

+- [x] No audit-blocking work found for Sprint 3.

+

+## Sprint 4

+

+Status: closed

+

+Validated:

+

+- [x] BSD, SysV, and GNU-thin archive flavors are recognized.

+- [x] Archive headers and name decoding are implemented.

+- [x] Symbol-index parsing exists for BSD and SysV archives.

+- [x] Lazy member fetch exists via `fetch_object_defining`.

+- [x] `libarmfortas_rt.a` is exercised by `tests/archive_runtime.rs`.

+- [x] Archive dump mode exists via `--dump-archive`.

+

+Remaining closeout work:

+

+- [x] Implement one-level nested archive support (`.a` member inside `.a`) and preserve provenance for diagnostics.

+- [x] Formally treat `resolve::force_load_archive` / `force_load_all` as the Sprint 4 completion surface and document that surface instead of adding a parallel archive-only helper.

+- [x] Add `ar -t` shape/parity coverage for `--dump-archive`.

+

+## Sprint 5

+

+Status: partially closed

+

+Validated:

+

+- [x] `DylibFile` exists and parses binary `MH_DYLIB`.

+- [x] `LC_ID_DYLIB`, dependency dylib commands, ordinals, and rpaths are decoded.

+- [x] Export trie decoding exists with cycle/depth protection.

+- [x] Real clang-built dylib coverage exists in `tests/dylib_integration.rs`.

+- [x] Dylib dump mode exists via `--dump-dylib`.

+

+Remaining closeout work:

+

+- [ ] Prove recursive re-export / umbrella lookup behavior with a focused test, not just dependency collection.

+- [ ] Confirm the public dylib surface matches what Sprint 5 intended for re-exported symbols, not only direct exports.

+

+## Sprint 6

+

+Status: closed

+

+Validated:

+

+- [x] The custom YAML subset parser exists in `src/macho/tbd_yaml.rs`.

+- [x] TBD schema decoding exists in `src/macho/tbd.rs`.

+- [x] `DylibFile::from_tbd` exists and materializes TBDs into the same linker-facing surface.

+- [x] Real `libSystem.tbd` smoke/integration coverage exists in `tests/tbd_smoke.rs` and `tests/tbd_integration.rs`.

+- [x] TBD dump mode exists via `--dump-tbd`.

+

+Remaining closeout work:

+

+- [x] Implement SDK `-syslibroot` library search helpers for `.tbd` / `.dylib`.

+- [x] Implement framework search helpers promised by Sprint 6.

+- [x] Make target filtering fail loudly when the requested target is not exported, instead of only materializing matching targets when the caller already knows one exists.

+- [x] No further audit-blocking work found for Sprint 6 in the current helper/test surface.

+

+## Sprint 7

+

+Status: closed

+

+Validated:

+

+- [x] `Symbol` sum type exists with the planned major variants.

+- [x] `StringInterner`, opaque ids, and `SymbolTable` exist.

+- [x] The insertion matrix is heavily unit-tested.

+- [x] Weak/strong/common coalescing behavior is covered in unit tests.

+- [x] Alias-cycle detection and chain resolution exist.

+- [x] Transition logging exists.

+

+Remaining closeout work:

+

+- [ ] Add the differential weak-coalescing / duplicate-behavior coverage against system `ld` that Sprint 7 originally called for.

+

+## Sprint 8

+

+Status: closed

+

+Validated:

+

+- [x] Archive seeding, object seeding, and dylib seeding exist.

+- [x] Fixed-point archive fetch draining exists.

+- [x] `force_load_archive` and `force_load_all` helpers exist in `src/resolve.rs`.

+- [x] Undefined classification exists for `Error`, `Warning`, `Suppress`, and `DynamicLookup`.

+- [x] Did-you-mean support exists.

+- [x] Duplicate-symbol and undefined-symbol formatting helpers exist.

+- [x] Real integration coverage exists for archive pull plus unresolved-symbol reporting.

+

+Remaining closeout work:

+

+- [x] Add a real orchestration entrypoint for resolution (`seed -> optional force load -> drain -> classify`) that can be called as a coherent stage.

+- [x] Add option/state plumbing for `all_load`, `force_load`, and undefined treatment so resolution is not just a bag of helper APIs.

+- [x] Add an archive order-sensitivity test.

+- [x] Add dedicated tests for `force_load_archive` and `force_load_all`.

+- [x] Add dedicated tests for `UndefinedTreatment::Warning`, `Suppress`, and `DynamicLookup`.

+- [x] Add a dedicated test that unresolved weak refs stay accepted regardless of treatment.

+- [x] Tighten diagnostics toward the Sprint 8 format by carrying section/offset provenance and aggregate repeated relocation sites when available.

+

+## Sprint 9

+

+Status: closed

+

+Validated:

+

+- [x] Atom model and atom table exist.

+- [x] Section splitting at symbol boundaries exists.

+- [x] `.alt_entry` folding exists.

+- [x] CString atom splitting exists and is integration-tested.

+- [x] Compact-unwind atom splitting and `parent_of` wiring exist.

+- [x] Backpatching of `Symbol::Defined { atom }` exists.

+- [x] `N_NO_DEAD_STRIP` and weak-def flags are propagated into atom flags.

+- [x] Embedded payload addends on symbol-based data relocs are folded into local atom offsets or preserved on external refs.

+

+Remaining closeout work:

+

+- [x] Remap relocations from raw section/symbol referents into atom-aware referents.

+- [x] Add atom-local relocation storage or an equivalent per-atom relocation view.

+- [x] Ensure same-object references point at target atoms, not raw section offsets.

+- [x] Add a focused integration test proving a local branch or data reference resolves to the callee/target atom.

+- [x] Add a boundary-crossing reloc diagnostic test.

+- [x] Confirm no raw section-relative relocation state leaks into Sprint 10 inputs.

+- [x] No further audit-blocking work found for Sprint 9 in the current corpus and targeted local-addend probes.

+

+## Documentation Closeout

+

+- [x] Update `README.md` so it no longer says the crate is only Sprint 0 scaffolding.

+- [x] Refresh sprint docs whose deliverables have been implemented under a different surface than originally planned.

+- [x] Keep `CLAUDE.md` as the authority for discipline, but make user-facing docs match the actual code.

+

+## Verification Commands

+

+- [x] `cargo test -p afs-ld`

+- [x] `cargo clippy -p afs-ld --all-targets -- -D warnings`

+- [ ] Focused xcrun-backed checks when touching reader/resolve/atom/TBD/dylib paths:

+  - [x] `cargo test -p afs-ld --test reader_corpus_round_trip -- --nocapture`

+  - [x] `cargo test -p afs-ld --test resolve_integration -- --nocapture`

+  - [x] `cargo test -p afs-ld --test atom_integration -- --nocapture`

+  - [x] `cargo test -p afs-ld --test dylib_integration -- --nocapture`

+  - [x] `cargo test -p afs-ld --test tbd_integration -- --nocapture`

+`DiffReport` categorizes byte differences as `Tolerated` (UUID, timestamp, temp-path hashes) or `Critical` (anything else). Critical diffs fail the test.

+

+Closeout note: the current Sprint 0 surface is intentionally synthetic. `diff_macho` exists and is tested, but `link_both` remains a placeholder until afs-ld can emit real linked output. That means the current harness validates diff categorization logic, not end-to-end linker parity yet.

+- `afs-ld/tests/diff_harness_sanity.rs`: exercises the diff surface against two identical synthetic byte slices and expects zero diffs. Passes.

+- `afs-ld/tests/diff_harness_finds_critical.rs`: feeds the harness two synthetic binaries that differ in a non-tolerated byte range and asserts the harness reports `Critical`. Passes.

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

+Closeout note: alongside the original unit coverage, `tests/reader_malformed_stress.rs`

+now runs deterministic truncated/header-corruption cases over real corpus-built

+objects to defend the "no panics on malformed input" bar, and

+`tests/reader_tool_parity.rs` checks the `--dump` load-command surface against

+`otool -lV` across the afs-as corpus.

+

+Closeout note: `tests/reader_malformed_stress.rs` now also covers malformed

+symbol/string-table variants derived from real corpus objects so the reader's

+symbol and string surfaces are exercised under targeted bad-input cases, not

+just hand-written unit fixtures. `tests/reader_tool_parity.rs` now also checks

+symbol classification against `nm -a` and raw relocation tables against

+`otool -r` across the afs-as corpus.

+

+Closeout note: the force-load surface landed in the resolver as

+`resolve::force_load_archive` / `resolve::force_load_all`, and one-level

+nested archives are expanded through the fetched-member path with provenance

+chains such as `outer.a(inner.a)(foo.o)`. `--dump-archive` now intentionally

+prints the same member listing shape as `ar -t`, and parity is checked

+against both generated archives and `libarmfortas_rt.a` when available.

+

+Implemented via the resolver-level helpers

+`resolve::force_load_archive` / `resolve::force_load_all`, which pre-fetch

+archive members against the live linker input registry. Sprint 19 wires the

+CLI surface.

+Closeout note: the implemented entrypoint is

+`resolve(inputs, table, opts) -> ResolutionReport`. The current library

+surface applies archive force-loading as archives are encountered in

+command-line order so left-to-right archive behavior stays explicit.

+

+    -> Result<ResolutionReport, ResolutionError>

+    seed_and_resolve_in_link_order(inputs, table, opts);

+    classify_unresolved(table, opts.undefined_treatment);

+- In the implemented surface these happen when the named archive is encountered in link order, which preserves left-to-right linker semantics while still feeding the same resolution/classification pipeline.

+      referenced by program.o(__TEXT,__text + 0x34)

+      referenced by runtime.o(__TEXT,__text + 0x120)

+  defined in: a.o (__TEXT,__text + 0x0)

+  also in:    b.o (__TEXT,__text + 0x0)

+

+## Remaining Flag Slices

+- [x] `-exported_symbols_list <file>`

+- [x] `-unexported_symbols_list <file>`

+- [x] `-exported_symbol <sym>`

+- [x] `-unexported_symbol <sym>`

+- [x] `-r` / `-bundle` explicit deferred errors

+- [x] `-S`

+- [x] `-no_uuid`

+- [x] `-dead_strip`

+- [x] `-icf=safe` / `-icf=none`

+- [x] `-fixup_chains` / `-no_fixup_chains`

+- [x] `-Wl,<comma-separated>` normalization

+- [x] `-map <path>`

+- [x] `-t` / `-trace`

+- [x] `-v` / `--version`

+- [x] `-h` / `--help`

+- [x] `-why_live <symbol>`

+Current Sprint 27 allowlist is intentionally small and explicit:

+- UUID load-command bytes.

+- Dylib timestamp fields.

+- Code-signature load-command/blob bytes.

+- Case-specific section-byte ranges declared in `notes.md`.

+- String-table length drift within 5% for suffix-dedup variance.

+Make afs-ld fast enough to feel like a production tool. Sprint 28 establishes

+the profiling surface, parallelizes the obvious hot paths, and enforces

+hello/runtime-link budgets in CI. The fortsh 2× Apple `ld` gate remains the

+production target, but Sprint 29 owns the fortsh fixture and final comparison.

+Mold demonstrates linkers can be very fast; we don't need mold's speed, but we

+need to not be painful.

+Profile representative hello-world and runtime-archive links in Sprint 28.

+Sprint 29 extends the same profile surface to the fortsh link once the fixture

+exists. Categorize wall time:

+Deferred. The current Sprint 28 profile work did not prove allocation churn is

+the next limiting bucket after the parallel parsing/relocation/signature and

+string-table clone fixes. If Sprint 29's fortsh profile shows parser allocation

+pressure, implement `src/arena.rs` as a std-only `Vec<Box<[u8]>>` chunker.

+Deferred. Object/archive loading still uses `fs::read`; this keeps the Sprint 28

+closeout safe and std-only. If fortsh-sized inputs show file-read overhead as a

+real bucket in Sprint 29, add an unsafe `src/mmap.rs` wrapper and keep a

+`fs::read` fallback for archive members whose external path cannot be mapped.

+Deferred. Sprint 28 made the global string table thread-shareable and removed

+the cloned string-table offset map during output writing. Per-input local

+interners remain a candidate if Sprint 29 identifies symbol seeding as a

+fortsh-scale bottleneck.

+Sprint 28 uses CI-enforced integration benchmarks in `tests/perf_baseline.rs`:

+

+- `bench_hello_world_profile_reports_baseline_timings`: small, measures startup overhead.

+- `bench_runtime_link_profile_reports_baseline_timings`: mid, measures symbol-table, archive parsing, and reloc-apply.

+- `bench_fortsh_link`: deferred to Sprint 29 with the real fortsh fixture.

+- fortsh link: ≤ 2× Apple `ld`'s wall time on the same machine, enforced in Sprint 29.

+- Benchmark gate: CI runs `tests/perf_baseline.rs` with hello/runtime budgets on every push and PR.

+- Nightly throughput recording and a relative >10% regression gate are deferred until the fortsh fixture lands in Sprint 29.

+- hello/runtime performance budgets are enforced in CI.

+- fortsh 2× comparison is explicitly handed to Sprint 29 with its fixture.

+name: parity-matrix

+

+on:

+  pull_request:

+  push:

+    branches:

+      - trunk

+

+permissions:

+  contents: read

+

+jobs:

+  parity-matrix:

+    runs-on: macos-14

+    timeout-minutes: 30

+    steps:

+      - name: Checkout

+        uses: actions/checkout@v4

+

+      - name: Install Rust

+        uses: dtolnay/rust-toolchain@stable

+

+      - name: Run parity harness proof tests

+        run: cargo test --test diff_harness_tolerates_known_linkedit --test parity_harness --test parity_canary -- --nocapture

+

+      - name: Run determinism gate

+        run: cargo test --test determinism -- --nocapture

+

+      - name: Run performance budget gate

+        env:

+          AFS_LD_HELLO_BUDGET_MS: "20"

+          AFS_LD_RUNTIME_BUDGET_MS: "150"

+        run: cargo test --test perf_baseline -- --nocapture

+

+      - name: Run parity matrix

+        env:

+          PARITY_MATRIX_ARTIFACT_DIR: ${{ github.workspace }}/parity-matrix-artifacts

+          PARITY_MATRIX_MAX_SECONDS: "120"

+        run: cargo test --test parity_matrix -- --nocapture

+

+      - name: Upload parity artifacts

+        if: always()

+        uses: actions/upload-artifact@v4

+        with:

+          name: parity-matrix-html

+          path: parity-matrix-artifacts

+          if-no-files-found: warn

+# AFS-LD

+

+Local working guide for agents in `afs-ld`. Keep this file untracked.

+`CLAUDE.md` is the tracked, authoritative policy file; this document adds a

+reality-checked snapshot of the current implementation so we do not confuse the

+roadmap with shipped code.

+

+## Repository Context

+

+`afs-ld` is the standalone ARM64 Mach-O linker for the ARMFORTAS toolchain. It

+sits beside `afs-as` as a submodule in the `armfortas` workspace and is meant

+to replace Apple's `ld` for binaries produced by armfortas.

+

+The project boundary is intentionally clean:

+

+- `afs-as` emits `MH_OBJECT`.

+- `afs-ld` reads `.o`, `.a`, `.dylib`, and `.tbd`.

+- armfortas should eventually hand final linking to `afs-ld` rather than to

+  the system linker.

+

+The project is Mach-O only, macOS only, arm64 only, stdlib only.

+

+## Definition Of Done

+

+The real finish line is not "parses some objects" or "links hello world once."

+It is parity with Apple's `ld` for the binaries armfortas and fortsh need:

+

+- arm64 Mach-O executables and dylibs

+- static archive linking

+- dylib and TBD ingestion

+- dyld metadata that works on real macOS systems

+- ad-hoc signing so output executes on Apple Silicon

+- deterministic output

+- enough correctness to link fortsh without ARM-specific workarounds

+

+## Current Reality

+

+This repo is ahead of Sprint 0 scaffolding, but it is not yet a full linker.

+The roadmap in `.docs/overview.md` and `.docs/sprints/` is broader than the

+code that exists today.

+

+What is implemented now:

+

+- hand-rolled CLI parsing for a small flag subset plus dump modes

+- Mach-O header/load-command/section/symbol/string-table reading

+- relocation parsing, fusion, validation, and round-trip support

+- archive parsing and lazy member fetch support

+- binary dylib parsing and export-trie walking

+- TAPI TBD v4 parsing, including the custom YAML subset parser

+- linker-side symbol interning, symbol table modeling, and resolution passes

+- subsections-via-symbols atomization

+- `--dump`, `--dump-archive`, `--dump-dylib`, and `--dump-tbd`

+

+What is not implemented yet:

+

+- real `Linker::run` output production

+- output layout and Mach-O writing

+- dyld metadata synthesis

+- code signing

+- dead-strip / ICF / thunks

+- real differential linking against Apple `ld`

+- driver integration with armfortas

+- the full `ld`-compatible CLI surface described in Sprint 19

+

+Important practical note:

+

+- `src/lib.rs` still returns `LinkError::NotYetImplemented` for real link runs.

+- `tests/common/harness.rs::link_both` still panics because full end-to-end

+  linker execution has not landed.

+- `README.md` still describes the crate as "Sprint 0 scaffolding only," which is

+  now too pessimistic for the read-side code but still accurate for the actual

+  link-producing path.

+

+As of 2026-04-15 in this checkout, `cargo test -p afs-ld` is green.

+

+## Strengths

+

+- The read-side core is already substantial and well-tested.

+- The project has strong bespoke discipline: no `clap`, `serde`, `object`,

+  `goblin`, `byteorder`, or other format-parsing shortcuts.

+- Raw wire structures are modeled explicitly and usually paired with

+  round-trip-oriented tests.

+- The type modeling is strong: opaque ids, interned strings, explicit symbol

+  states, explicit atom ownership, explicit relocation referents.

+- Real-world fixtures are already in play: afs-as corpus objects,

+  `libarmfortas_rt.a`, `libSystem.tbd`, and small clang-built dylibs.

+- The codebase already separates concerns cleanly enough that writer/layout work

+  can land without tearing up the read-side foundation.

+- Dump modes make inspection easy and are useful while the full writer does not

+  exist yet.

+

+## Weaknesses And Risk Areas

+

+- The actual link-producing pipeline does not exist yet, so the hardest parity

+  bugs are still ahead of us.

+- Some tracked docs are aspirational. `.docs/overview.md` is the intended end

+  state, not a guarantee that every listed module already exists.

+- `README.md` is stale in the opposite direction: it understates how much

+  read-side work has landed.

+- The current diagnostics surface is still minimal. `src/diag.rs` only prints

+  `afs-ld: error: ...`; the richer caret diagnostics are planned, not present.

+- The CLI surface is intentionally tiny right now. Any work that assumes

+  `ld`-compatibility must start by checking `src/args.rs`, not by trusting the

+  sprint plan.

+- Performance characteristics are mostly unknown because the writer, layout, and

+  full-link path are not in place yet.

+- The differential harness is only half-built: the diff engine exists, but the

+  "run both linkers" machinery is not wired.

+- Several future modules named in the roadmap do not exist yet:

+  `layout.rs`, `driver.rs`, `map.rs`, `gc.rs`, `icf.rs`, `synth/`,

+  `macho/writer.rs`, and the code-signing path are all still planned work.

+

+## Build And Test

+

+Primary commands:

+

+```bash

+cargo build -p afs-ld

+cargo test -p afs-ld

+cargo clippy -p afs-ld --all-targets -- -D warnings

+```

+

+Useful targeted commands:

+

+```bash

+cargo test --lib -p afs-ld

+cargo test --test reader_corpus_round_trip -p afs-ld

+cargo test --test archive_runtime -p afs-ld

+cargo test --test dylib_integration -p afs-ld

+cargo test --test tbd_integration -p afs-ld

+cargo test --test resolve_integration -p afs-ld

+cargo test --test atom_integration -p afs-ld

+cargo test -p afs-ld -- <substring>

+```

+

+Environment assumptions:

+

+- macOS on Apple Silicon

+- Xcode command-line tools available through `xcrun`

+- access to the parent workspace, especially `runtime/` and `.refs/`

+

+Integration tests already shell out to system tools in a few places. Do not

+replace those with fake fixtures if a real toolchain interaction is the thing

+being tested.

+

+## Project Structure

+

+Actual source tree today:

+

+```text

+afs-ld/

+├── CLAUDE.md

+├── README.md

+├── .docs/

+│   ├── overview.md

+│   └── sprints/

+├── src/

+│   ├── archive.rs

+│   ├── args.rs

+│   ├── atom.rs

+│   ├── diag.rs

+│   ├── dump.rs

+│   ├── input.rs

+│   ├── leb.rs

+│   ├── lib.rs

+│   ├── main.rs

+│   ├── resolve.rs

+│   ├── section.rs

+│   ├── string_table.rs

+│   ├── symbol.rs

+│   ├── macho/

+│   │   ├── constants.rs

+│   │   ├── dylib.rs

+│   │   ├── exports.rs

+│   │   ├── reader.rs

+│   │   ├── tbd.rs

+│   │   └── tbd_yaml.rs

+│   └── reloc/

+│       └── mod.rs

+└── tests/

+    ├── common/harness.rs

+    ├── archive_runtime.rs

+    ├── atom_integration.rs

+    ├── diff_harness_*.rs

+    ├── dylib_integration.rs

+    ├── reader_*.rs

+    ├── resolve_integration.rs

+    ├── tbd_*.rs

+    └── reader_corpus_round_trip.rs

+```

+

+Planned future modules listed in the docs should be treated as design intent,

+not as present-tense implementation.

+

+## Implemented Pipeline Vs Planned Pipeline

+

+Implemented today:

+

+```text

+argv

+  -> args.rs

+  -> dump/read paths

+  -> archive/object/dylib/TBD ingestion

+  -> symbol/section/reloc decoding

+  -> resolve.rs

+  -> atom.rs

+```

+

+Current real-link path:

+

+```text

+argv -> args.rs -> Linker::run -> NotYetImplemented

+```

+

+Planned end-to-end pipeline from the roadmap:

+

+```text

+args -> inputs -> resolve -> atomize -> layout -> apply relocs

+     -> synth sections -> write -> sign

+```

+

+When you are planning work, always identify which of those stages is real in

+this checkout and which stage is still only described in docs.

+

+## Development Guidance

+

+### 1. Trust code and tests over roadmap prose

+

+Read these in order before substantial work:

+

+1. `CLAUDE.md`

+2. `.docs/overview.md`

+3. the relevant sprint file in `.docs/sprints/`

+4. the actual Rust module you will touch

+5. the tests covering that module

+

+If the docs and the code disagree, treat the code plus tests as the truth about

+what exists today, then decide whether the docs need to be refreshed.

+

+### 2. Keep the bespoke contract intact

+

+- Stdlib only unless a dependency discussion happens first.

+- Do not couple afs-ld to afs-as at a Rust type level.

+- Duplicate Mach-O constants locally when needed.

+- Do not hide format details behind clever abstractions that erase wire truth.

+

+### 3. Preserve the wire

+

+- Keep raw bytes or raw fields accessible when lossless re-emission matters.

+- Prefer explicit parse and write pairs for on-disk structures.

+- Avoid converting fixed-size or padded wire data into lossy higher-level forms

+  unless the raw representation is still available somewhere.

+- If a new decoder lands, pair it with tests that prove it round-trips or at

+  least preserves the exact bytes relevant to the current stage.

+

+### 4. Be explicit about incomplete work

+

+- Hard errors are better than silent wrong answers.

+- If something is not implemented, say so directly.

+- Do not introduce "temporary" behavior that quietly emits malformed Mach-O.

+- Do not soften a missing feature into a no-op unless the flag or structure is

+  explicitly intended to be ignored.

+

+### 5. Exhaustive matches matter

+

+- Prefer enums for wire forms and linker-side states.

+- Avoid catch-all `_` arms in production matches when a new variant should force

+  the compiler to help us.

+- When adding a new variant, update every relevant match deliberately.

+

+### 6. Keep dump surfaces useful

+

+- `--dump*` modes are an active debugging tool, not a side feature.

+- When new reader functionality lands, extend the corresponding dump output.

+- If you add a new parsed field but the dump cannot show it, the repo loses one

+  of its best inspection surfaces.

+

+### 7. Respect deterministic behavior

+

+- Avoid nondeterministic iteration when output order matters.

+- Avoid timestamps, random ids, or unstable hashing in any future write path.

+- When adding diagnostics, keep them stable and testable.

+

+## Testing Practices

+

+- Every bug fix gets a regression test.

+- New parser behavior should land with unit tests close to the module.

+- When touching integration behavior, prefer real fixtures over mocked ones.

+- For archive work, look first at `tests/archive_runtime.rs`.

+- For dylib and TBD work, look first at `tests/dylib_integration.rs`,

+  `tests/tbd_integration.rs`, and `tests/tbd_smoke.rs`.

+- For reader invariants, `tests/reader_corpus_round_trip.rs` is a key guardrail.

+- For resolution and atomization, `tests/resolve_integration.rs` and

+  `tests/atom_integration.rs` should move with the code.

+- If you add future write-side functionality, extend the differential harness

+  rather than building a parallel ad hoc test path.

+

+Run focused tests first, then widen:

+

+- module-local or single integration test while developing

+- `cargo test -p afs-ld` before handing work off

+- `cargo clippy -p afs-ld --all-targets -- -D warnings` when changing code paths

+  broadly enough to justify it

+

+## Documentation Practices

+

+- `CLAUDE.md` is policy and development discipline.

+- `.docs/overview.md` is the intended architecture and scope.

+- `.docs/sprints/` is the staged roadmap.

+- `README.md` is user-facing and currently stale relative to the read-side code.

+

+When a change materially shifts reality, update the tracked docs that are now

+misleading. This is especially important in this repo because the roadmap is

+ambitious and can otherwise create false assumptions for future work.

+

+## References

+

+Use the parent repository's references when you need to confirm Mach-O or linker

+behavior instead of inventing from memory:

+

+- `.refs/llvm/lld/MachO/` for architecture and pass structure

+- `.refs/ld64/` for Apple-parity edge cases

+- `.refs/mold/` for performance ideas and comparative implementation choices

+

+Also use Apple's Mach-O and arm64 relocation headers as the numeric source of

+truth for constants mirrored in `src/macho/constants.rs`.

+

+## Working Style For This Repo

+

+- Prefer small, reviewable changes.

+- Keep commit messages terse and imperative.

+- Do not mention sprint numbers in commit subjects.

+- Avoid monolithic "land the whole linker" changes; the sprint plan is granular

+  for a reason.

+- Before implementing a planned module from the roadmap, make sure the crate

+  actually has the prerequisites the sprint assumed.

+- If you are about to say "the docs say this exists," stop and confirm with

+  `ls`, `rg`, and the tests.

+

+## Practical Shortcuts

+

+- Use `rg --files` and `rg` first; the repo is small enough that this is fast

+  and keeps context grounded in the actual tree.

+- For current status, start with `src/lib.rs`, `src/main.rs`, `src/args.rs`,

+  `tests/common/harness.rs`, and `README.md`.

+- For architectural intent, then read `.docs/overview.md` and the relevant

+  sprint file.

+

+That order will save a lot of confusion.

+use crate::resolve::{levenshtein, UndefinedTreatment};

+use crate::{FrameworkSpec, IcfMode, LinkOptions, OutputKind, PlatformVersion, ThunkMode};

+

+const KNOWN_FLAGS: &[&str] = &[

+    "-o",

+    "-e",

+    "-arch",

+    "-l",

+    "-L",

+    "-framework",

+    "-weak_framework",

+    "-ObjC",

+    "-syslibroot",

+    "-platform_version",

+    "-r",

+    "-bundle",

+    "-undefined",

+    "-rpath",

+    "-install_name",

+    "-current_version",

+    "-compatibility_version",

+    "-exported_symbols_list",

+    "-unexported_symbols_list",

+    "-exported_symbol",

+    "-unexported_symbol",

+    "-S",

+    "-no_uuid",

+    "-no_loh",

+    "-thunks=none",

+    "-thunks=safe",

+    "-thunks=all",

+    "-dead_strip",

+    "-icf=safe",

+    "-icf=none",

+    "-icf=all",

+    "-fixup_chains",

+    "-no_fixup_chains",

+    "-map",

+    "-why_live",

+    "-t",

+    "-trace",

+    "-v",

+    "--version",

+    "-h",

+    "--help",

+    "-x",

+    "-dylib",

+    "-all_load",

+    "-force_load",

+    "-j",

+    "--dump",

+    "--dump-archive",

+    "--dump-dylib",

+    "--dump-tbd",

+];

+    /// A recognized flag got a value we do not accept.

+    InvalidValue {

+        flag: String,

+        value: String,

+        expected: String,

+    },

+    UnknownFlag {

+        flag: String,

+        suggestion: Option<String>,

+    },

+            ArgsError::InvalidValue {

+                flag,

+                value,

+                expected,

+            } => {

+                    "flag `{flag}` got invalid value `{value}` (expected {expected})"

+            ArgsError::UnknownFlag { flag, suggestion } => {

+                write!(f, "unknown flag `{flag}`")?;

+                if let Some(suggestion) = suggestion {

+                    write!(f, " (did you mean `{suggestion}`?)")?;

+                }

+                write!(f, " (Sprint 19 adds the full `ld` surface)")

+            }

+fn unknown_flag(flag: &str) -> ArgsError {

+    let suggestion = KNOWN_FLAGS

+        .iter()

+        .map(|candidate| (levenshtein(flag, candidate), *candidate))

+        .filter(|(distance, _)| *distance <= 3)

+        .min_by_key(|(distance, candidate)| (*distance, candidate.len()))

+        .map(|(_, candidate)| candidate.to_string());

+    ArgsError::UnknownFlag {

+        flag: flag.to_string(),

+        suggestion,

+    }

+}

+

+fn parse_version_component(flag: &str, value: &str) -> Result<u32, ArgsError> {

+    let mut parts = value.split('.');

+    let parse_part = |piece: Option<&str>| -> Result<u32, ArgsError> {

+        let raw = piece.unwrap_or("0");

+        raw.parse::<u32>().map_err(|_| ArgsError::InvalidValue {

+            flag: flag.to_string(),

+            value: value.to_string(),

+            expected: "version like <major>[.<minor>[.<patch>]]".into(),

+        })

+    };

+    let major = parse_part(parts.next())?;

+    let minor = parse_part(parts.next())?;

+    let patch = parse_part(parts.next())?;

+    if parts.next().is_some() {

+        return Err(ArgsError::InvalidValue {

+            flag: flag.to_string(),

+            value: value.to_string(),

+            expected: "version like <major>[.<minor>[.<patch>]]".into(),

+        });

+    }

+    Ok((major << 16) | ((minor & 0xff) << 8) | (patch & 0xff))

+}

+

+fn parse_jobs(value: &str) -> Result<usize, ArgsError> {

+    let jobs = value

+        .parse::<usize>()

+        .map_err(|_| ArgsError::InvalidValue {

+            flag: "-j".into(),

+            value: value.to_string(),

+            expected: "positive integer job count".into(),

+        })?;

+    if jobs == 0 {

+        return Err(ArgsError::InvalidValue {

+            flag: "-j".into(),

+            value: value.to_string(),

+            expected: "positive integer job count".into(),

+        });

+    }

+    Ok(jobs)

+}

+

+    let normalized = normalize_wl(argv);

+    let mut it = normalized.iter();

+            "-l" => {

+                opts.library_names.push(

+                    it.next()

+                        .ok_or_else(|| ArgsError::MissingValue("-l".into()))?

+                        .clone(),

+                );

+            }

+            s if s.starts_with("-l") && s.len() > 2 => {

+                opts.library_names.push(s[2..].to_string());

+            }

+            "-L" => {

+                opts.search_paths.push(PathBuf::from(

+                    it.next()

+                        .ok_or_else(|| ArgsError::MissingValue("-L".into()))?,

+                ));

+            }

+            "-framework" => {

+                opts.frameworks.push(FrameworkSpec {

+                    name: it

+                        .next()

+                        .ok_or_else(|| ArgsError::MissingValue("-framework".into()))?

+                        .clone(),

+                    weak: false,

+                });

+            }

+            "-weak_framework" => {

+                opts.frameworks.push(FrameworkSpec {

+                    name: it

+                        .next()

+                        .ok_or_else(|| ArgsError::MissingValue("-weak_framework".into()))?

+                        .clone(),

+                    weak: true,

+                });

+            }

+            "-ObjC" => {

+                opts.objc_force_load = true;

+            }

+            "-syslibroot" => {

+                opts.syslibroot =

+                    Some(PathBuf::from(it.next().ok_or_else(|| {

+                        ArgsError::MissingValue("-syslibroot".into())

+                    })?));

+            }

+            "-platform_version" => {

+                let platform = it

+                    .next()

+                    .ok_or_else(|| ArgsError::MissingValue("-platform_version".into()))?;

+                if platform != "macos" {

+                    return Err(ArgsError::InvalidValue {

+                        flag: "-platform_version".into(),

+                        value: platform.clone(),

+                        expected: "platform `macos`".into(),

+                    });

+                }

+                let minos_raw = it

+                    .next()

+                    .ok_or_else(|| ArgsError::MissingValue("-platform_version".into()))?;

+                let sdk_raw = it

+                    .next()

+                    .ok_or_else(|| ArgsError::MissingValue("-platform_version".into()))?;

+                opts.platform_version = Some(PlatformVersion {

+                    minos: parse_version_component("-platform_version", minos_raw)?,

+                    sdk: parse_version_component("-platform_version", sdk_raw)?,

+                });

+            }

+            "-r" => {

+                opts.relocatable = true;

+            }

+            "-bundle" => {

+                opts.bundle = true;

+            }

+            "-undefined" => {

+                let value = it

+                    .next()

+                    .ok_or_else(|| ArgsError::MissingValue("-undefined".into()))?;

+                opts.undefined_treatment = match value.as_str() {

+                    "error" => UndefinedTreatment::Error,

+                    "warning" => UndefinedTreatment::Warning,

+                    "suppress" => UndefinedTreatment::Suppress,

+                    "dynamic_lookup" => UndefinedTreatment::DynamicLookup,

+                    _ => {

+                        return Err(ArgsError::InvalidValue {

+                            flag: "-undefined".into(),

+                            value: value.clone(),

+                            expected: "`error`, `warning`, `suppress`, or `dynamic_lookup`".into(),

+                        });

+                    }

+                };

+            }

+            "-rpath" => {

+                opts.rpaths.push(

+                    it.next()

+                        .ok_or_else(|| ArgsError::MissingValue("-rpath".into()))?

+                        .clone(),

+                );

+            }

+            "-install_name" => {

+                opts.install_name = Some(

+                    it.next()

+                        .ok_or_else(|| ArgsError::MissingValue("-install_name".into()))?

+                        .clone(),

+                );

+            }

+            "-current_version" => {

+                let value = it

+                    .next()

+                    .ok_or_else(|| ArgsError::MissingValue("-current_version".into()))?;

+                opts.current_version = Some(parse_version_component("-current_version", value)?);

+            }

+            "-compatibility_version" => {

+                let value = it

+                    .next()

+                    .ok_or_else(|| ArgsError::MissingValue("-compatibility_version".into()))?;

+                opts.compatibility_version =

+                    Some(parse_version_component("-compatibility_version", value)?);

+            }

+            "-exported_symbols_list" => {

+                opts.exported_symbols_lists

+                    .push(PathBuf::from(it.next().ok_or_else(|| {

+                        ArgsError::MissingValue("-exported_symbols_list".into())

+                    })?));

+            }

+            "-unexported_symbols_list" => {

+                opts.unexported_symbols_lists.push(PathBuf::from(

+                    it.next().ok_or_else(|| {

+                        ArgsError::MissingValue("-unexported_symbols_list".into())

+                    })?,

+                ));

+            }

+            "-exported_symbol" => {

+                opts.exported_symbols.push(

+                    it.next()

+                        .ok_or_else(|| ArgsError::MissingValue("-exported_symbol".into()))?

+                        .clone(),

+                );

+            }

+            "-unexported_symbol" => {

+                opts.unexported_symbols.push(

+                    it.next()

+                        .ok_or_else(|| ArgsError::MissingValue("-unexported_symbol".into()))?

+                        .clone(),

+                );

+            }

+            "-S" => {

+                opts.strip_debug = true;

+            }

+            "-no_uuid" => {

+                opts.emit_uuid = false;

+            }

+            "-no_loh" => {

+                opts.no_loh = true;

+            }

+            s if s.starts_with("-thunks=") => {

+                opts.thunks = match s {

+                    "-thunks=none" => ThunkMode::None,

+                    "-thunks=safe" => ThunkMode::Safe,

+                    "-thunks=all" => ThunkMode::All,

+                    _ => {

+                        let value = s.trim_start_matches("-thunks=").to_string();

+                        return Err(ArgsError::InvalidValue {

+                            flag: "-thunks".into(),

+                            value,

+                            expected: "`none`, `safe`, or `all`".into(),

+                        });

+                    }

+                };

+            }

+            "-dead_strip" => {

+                opts.dead_strip = true;

+            }

+            s if s.starts_with("-icf=") => {

+                opts.icf_mode = match s {

+                    "-icf=none" => IcfMode::None,

+                    "-icf=safe" => IcfMode::Safe,

+                    "-icf=all" => IcfMode::All,

+                    _ => {

+                        let value = s.trim_start_matches("-icf=").to_string();

+                        return Err(ArgsError::InvalidValue {

+                            flag: "-icf".into(),

+                            value,

+                            expected: "`safe`, `none`, or `all`".into(),

+                        });

+                    }

+                };

+            }

+            "-fixup_chains" => {

+                opts.fixup_chains = true;

+            }

+            "-no_fixup_chains" => {

+                opts.fixup_chains = false;

+            }

+            "-map" => {

+                opts.map = Some(PathBuf::from(

+                    it.next()

+                        .ok_or_else(|| ArgsError::MissingValue("-map".into()))?,

+                ));

+            }

+            "-why_live" => {

+                opts.why_live.push(

+                    it.next()

+                        .ok_or_else(|| ArgsError::MissingValue("-why_live".into()))?

+                        .clone(),

+                );

+            }

+            "-t" | "-trace" => {

+                opts.trace_inputs = true;

+            }

+            "-v" | "--version" => {

+                opts.show_version = true;

+            }

+            "-h" | "--help" => {

+                opts.show_help = true;

+            }

+            "-all_load" => {

+                opts.all_load = true;

+            }

+            "-force_load" => {

+                opts.force_load_archives

+                    .push(PathBuf::from(it.next().ok_or_else(|| {

+                        ArgsError::MissingValue("-force_load".into())

+                    })?));

+            }

+            "-j" => {

+                let value = it

+                    .next()

+                    .ok_or_else(|| ArgsError::MissingValue("-j".into()))?;

+                opts.jobs = Some(parse_jobs(value)?);

+            }

+                return Err(unknown_flag(s));

+fn normalize_wl(argv: &[String]) -> Vec<String> {

+    let mut out = Vec::with_capacity(argv.len());

+    for arg in argv {

+        if let Some(rest) = arg.strip_prefix("-Wl,") {

+            out.extend(

+                rest.split(',')

+                    .filter(|piece| !piece.is_empty())

+                    .map(ToString::to_string),

+            );

+        } else {

+            out.push(arg.clone());

+        }

+    }

+    out

+}

+

+    #[test]

+    fn deferred_output_flags_are_recorded() {

+        let opts = parse(&argv(&["-r", "-bundle", "foo.o"])).unwrap();

+        assert!(opts.relocatable);

+        assert!(opts.bundle);

+    }

+

+    #[test]

+    fn strip_debug_and_uuid_flags_are_recorded() {

+        let opts = parse(&argv(&["-S", "-no_uuid", "foo.o"])).unwrap();

+        assert!(opts.strip_debug);

+        assert!(!opts.emit_uuid);

+    }

+

+    #[test]

+    fn no_loh_flag_is_recorded() {

+        let opts = parse(&argv(&["-no_loh", "foo.o"])).unwrap();

+        assert!(opts.no_loh);

+    }

+

+    #[test]

+    fn dead_strip_icf_and_fixup_chain_flags_are_recorded() {

+        let opts = parse(&argv(&[

+            "-dead_strip",

+            "-thunks=all",

+            "-icf=safe",

+            "-fixup_chains",

+            "-no_fixup_chains",

+            "-icf=none",

+            "foo.o",

+        ]))

+        .unwrap();

+        assert!(opts.dead_strip);

+        assert_eq!(opts.thunks, ThunkMode::All);

+        assert_eq!(opts.icf_mode, IcfMode::None);

+        assert!(!opts.fixup_chains);

+    }

+

+    #[test]

+    fn thunks_flag_rejects_unknown_modes() {

+        let err = parse(&argv(&["-thunks=clustered", "main.o"])).unwrap_err();

+        assert!(matches!(

+            err,

+            ArgsError::InvalidValue {

+                ref flag,

+                ref value,

+                ..

+            } if flag == "-thunks" && value == "clustered"

+        ));

+    }

+

+    #[test]

+    fn icf_all_flag_is_recorded() {

+        let opts = parse(&argv(&["-icf=all", "foo.o"])).unwrap();

+        assert_eq!(opts.icf_mode, IcfMode::All);

+    }

+

+    #[test]

+    fn icf_flag_rejects_unknown_modes() {

+        let err = parse(&argv(&["-icf=aggressive", "main.o"])).unwrap_err();

+        assert!(matches!(

+            err,

+            ArgsError::InvalidValue {

+                ref flag,

+                ref value,

+                ..

+            } if flag == "-icf" && value == "aggressive"

+        ));