feat(dwarf): emit .rel.debug_* so a linker fixes up DWARF .text addresses (VCR-DBG-001 PR C, #394)

[avrabe]

What

PR C of v0.12.0 (VCR-DBG-001, epic #242). PR A captured the per-instruction machine_offset → wasm_op_index map; PR B (#429) emitted debugger-reachable DWARF — but with object-relative (.text base 0) addresses and no relocations. Correct in the unlinked ET_REL object, silently wrong on a linked image: a --debug-line consumer (jess, debugging gust on silicon via gdb/lldb) would get wrong source lines after ld. This wires the relocations that make the linker shift them — the property the v0.12.0 tag was held for.

How

C1 — elf_builder per-section REL generalization

• ElfBuilder gains extra_relocations + add_section_relocations(target, ..), emitting .rel.<name> sections (REL form, sh_link=symtab, sh_info=target section).
• Byte-identical when empty: every new byte (shstrtab names, rel tables, headers, +N to e_shnum) is appended after .rel.text and only when non-empty.

C2 — gimli RelocWriter + .text base symbol

• A custom write::Writer delegates to EndianVec but overrides only write_address, so just the two .text references (the line program's DW_LNE_set_address anchor + the CU DW_AT_low_pc) become relocations; internal DWARF cross-refs stay concrete (no section symbols needed).
• Single-base-reloc + addend 0 ⇒ the .debug_* bytes are byte-identical to PR B (Address::Symbol{_,0} writes the same in-place 0 as Address::Constant(0)); rows stay text-relative deltas, so one relocation per section covers all 110 rows.
• A dedicated global __synth_text_base (st_shndx=.text, value 0) anchors the R_ARM_ABS32 records; appended last ⇒ no symbol-index shift, .symtab sh_info untouched, present only under --debug-line.
• --debug-line on a self-contained ET_EXEC / RISC-V build (where DWARF isn't emitted) now warns loudly rather than silently dropping (native-pointer-abi: size the wasm .bss to data high-water-mark, not the full declared memory page (blocks tiny-RAM targets) #383 honest-fail).

Oracle (the gate the advisor required)

rel_debug_relocations_shift_addresses_to_correct_line_394: asserts .debug_line/.debug_info each carry exactly one R_ARM_ABS32 against __synth_text_base with in-place addend 0, then applies the .debug_line reloc at base 0x08000000 and re-walks the line program — every row shifts by exactly the base and its source line is preserved (relocate-at-nonzero-base, correct line, not just "a reloc exists").

Confirmed end-to-end with a real linker:

arm-none-eabi-ld -Ttext=0x08000000 → readelf --debug-dump=decodedline
synth.wasm  175  0x800023c
synth.wasm  175  0x8000260   …

A real toolchain links it and GNU's own DWARF reader resolves correct linked addresses.

Frozen-safe

• All 4 dwarf_debug_line_emit_394 oracles green; PR B additivity/no-op oracles unchanged (the gust whole-.o no-op oracle is the end-to-end C1 byte-identity proof).
• cabi_arena_realloc_linkability_418 .rel.text fixture byte-identical.
• fmt + clippy clean; rivet gate (non-xref) = 0; bazel build //crates:synth green.

Known limitation (EXPERIMENTAL, documented in --debug-line help)

__synth_text_base is a global symbol, so linking >1 synth --debug-line object into one image collides (multiple definition) — fails loud, not the silent-wrong-line shape. Common case (one synth .o + the C kiln bridge) is correct and verified. Idiomatic fix (a local STT_SECTION symbol) is a fast-follow blocked by the hardcoded .symtab sh_info=1; jumps priority if jess's image links multiple synth objects.

Closes the v0.12.0 tag-hold on VCR-DBG-001.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 95.45455% with 7 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
crates/synth-cli/src/main.rs	88.23%	4 Missing ⚠️
crates/synth-backend/src/elf_builder.rs	97.05%	2 Missing ⚠️
crates/synth-core/src/dwarf_line.rs	98.07%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!