kit

link.c (73398B)

---

 /* link_emit_coff: write a PE32+ MH_EXECUTABLE-style image to the
  * caller-provided Writer.
  *
  * Phase 3.1 deliverable per doc/OBJ.md: skeleton + base-reloc
  * handling for the four standard PE sections.  Import-table synthesis
  * (.idata / IAT) lands in Phase 3.2; per-arch IAT stub bytes in 3.3;
  * TLS directory in 3.5; debug directory in 3.6 — those code paths
  * panic loudly here so the strict-by-default posture surfaces them.
  *
  * File layout (in write order):
  *
  *   [DOS stub IMAGE_DOS_HEADER]                  -- 64 bytes; e_lfanew=0x40
  *   [PE signature "PE\0\0"]                      -- 4 bytes
  *   [IMAGE_FILE_HEADER]                          -- 20 bytes
  *   [IMAGE_OPTIONAL_HEADER64]                    -- 240 bytes (PE32+)
  *   [IMAGE_SECTION_HEADER * nsec]                -- 40 bytes each
  *   [pad to FileAlignment]
  *   [.text bytes, padded to FileAlignment]
  *   [.rdata bytes, padded to FileAlignment]
  *   [.data bytes, padded to FileAlignment]
  *   [.reloc bytes, padded to FileAlignment]
  *
  * .bss is uninitialized — it has a section header (with VirtualSize)
  * but no file bytes and PointerToRawData=0.
  *
  * RVAs follow SectionAlignment (0x1000); FileAlignment is 0x200; the
  * first section starts at RVA 0x1000 (right after the headers map).
  * ImageBase is the Win64 convention 0x140000000.
  *
  * Reloc strategy.  The link layout pass has already placed every kept
  * input section into img->sections / img->segments under the ELF/Mach-O
  * coordinate system (image-relative vaddrs, often packed by permission
  * bucket).  COFF wants a different packing — the four standard
  * sections at SectionAlignment-aligned RVAs — so this writer re-derives
  * per-input-section vaddrs from scratch and shifts each LinkSection /
  * symbol / LinkRelocApply by its section's per-section delta before
  * applying relocations.  link_emit_macho takes the same tack for its
  * __DATA_CONST splits; the ELF writer leaves vaddrs alone because the
  * link layout already matches ELF's PT_LOAD shape. */
 
 #include "link/link.h"
 
 #include <stdlib.h>
 #include <string.h>
 
 #include "core/core.h"
 #include "core/heap.h"
 #include "core/pool.h"
 #include "core/slice.h"
 #include "core/util.h"
 #include "core/vec.h"
 #include "link/link_internal.h"
 #include "obj/coff/coff.h"
 #include "obj/format.h"
 
 /* ---- .idata layout constants ----
  *
  * Per doc/OBJ.md: the .idata content is a concatenation of an
  * IMAGE_IMPORT_DESCRIPTOR table (NULL-terminated), one ILT per DLL
  * (each NULL-terminated u64 array), one IAT per DLL (same shape),
  * a hint/name table, and a DLL-name string pool.  Each block is
  * pointer-sized aligned within the section.  AArch64 import thunks use
  * PAGEOFFSET_12L for 64-bit ILT/IAT slots, so those sub-blocks must be
  * 8-byte aligned. */
 #define PE_IDATA_BLOCK_ALIGN 8u
 /* Hint field on IMAGE_IMPORT_BY_NAME records.  kit never has a real
  * hint (the OS loader doesn't need one to do the bsearch on the DLL's
  * export name table), so 0 is the canonical "no hint" value. */
 #define PE_IMPORT_HINT_NONE 0u
 
 /* ---- PE/Win64 layout constants ----
  *
  * Centralised here so the wire-format numbers in this TU stay named
  * (and the magic-numbers rule in CLAUDE.md is honoured).  Values match
  * the PE/COFF spec + Win64 conventions; mingw-w64's ld defaults agree. */
 #define PE_IMAGE_BASE LINK_PE_IMAGE_BASE
 #define PE_SECTION_ALIGNMENT 0x1000u
 #define PE_FILE_ALIGNMENT 0x200u
 #define PE_FIRST_SECTION_RVA 0x1000u
 #define PE_DOS_E_LFANEW 0x40u
 #define PE_NUM_DATA_DIRS COFF_NUM_DATA_DIRECTORIES
 #define PE_OPT_HDR_SIZE COFF_OPT_HDR64_SIZE
 #define PE_LINKER_MAJOR 0u
 #define PE_LINKER_MINOR 1u
 #define PE_OS_MAJOR 6u /* Windows Vista+ — mingw default */
 #define PE_OS_MINOR 0u
 #define PE_SUBSYS_MAJOR 6u
 #define PE_SUBSYS_MINOR 0u
 #define PE_STACK_RESERVE 0x100000ULL
 #define PE_STACK_COMMIT 0x1000ULL
 #define PE_HEAP_RESERVE 0x100000ULL
 #define PE_HEAP_COMMIT 0x1000ULL
 /* DllCharacteristics bits that apply regardless of relocatability. */
 #define PE_DLL_CHARS_BASE               \
   (IMAGE_DLLCHARACTERISTICS_NX_COMPAT | \
    IMAGE_DLLCHARACTERISTICS_TERMINAL_SERVER_AWARE)
 /* ASLR bits — only valid when the image carries base relocations (PIE).
  * Advertising DYNAMIC_BASE / HIGH_ENTROPY_VA alongside RELOCS_STRIPPED is
  * contradictory: the loader has nothing to fix up, so it can't relocate. */
 #define PE_DLL_CHARS_ASLR                     \
   (IMAGE_DLLCHARACTERISTICS_HIGH_ENTROPY_VA | \
    IMAGE_DLLCHARACTERISTICS_DYNAMIC_BASE)
 
 /* PE32+ DOS-stub-to-PE-signature offsets (manual, since we marshal
  * field-by-field rather than memcpy'ing the packed struct). */
 #define PE_DOS_HDR_SIZE COFF_DOS_HEADER_SIZE
 #define PE_SIG_SIZE 4u
 #define PE_FILE_HDR_SIZE COFF_FILE_HEADER_SIZE
 #define PE_SECTION_HDR_SIZE COFF_SECTION_HEADER_SIZE
 
 /* Standard PE output buckets, plus .idata (import directory) and
  * .reloc — both synthesised here rather than copied from input
  * sections.  Order matters: it's the on-image RVA order. */
 typedef enum CoffBucket {
   COFF_BUCKET_TEXT = 0,
   COFF_BUCKET_RDATA = 1,
   COFF_BUCKET_IDATA = 2,
   COFF_BUCKET_DATA = 3,
   COFF_BUCKET_TLS = 4,
   COFF_BUCKET_BSS = 5,
   COFF_BUCKET_PDATA = 6,
   COFF_BUCKET_RELOC = 7,
   COFF_NBUCKETS = 8,
 } CoffBucket;
 
 /* IMAGE_TLS_DIRECTORY64 wire size: u64*4 + u32*2 = 40 bytes. */
 #define COFF_TLS_DIRECTORY64_SIZE 40u
 /* Byte offsets of the four u64 VA fields within IMAGE_TLS_DIRECTORY64
  * — they need base relocations so ASLR can fix them up. */
 #define COFF_TLSDIR_OFF_START_ADDR 0u
 #define COFF_TLSDIR_OFF_END_ADDR 8u
 #define COFF_TLSDIR_OFF_INDEX_ADDR 16u
 #define COFF_TLSDIR_OFF_CALLBACKS 24u
 
 typedef struct CoffSection {
   const char* name; /* short ASCII; <= 8 bytes including NUL pad */
   u32 characteristics;
   u8* bytes;         /* NULL for .bss / .reloc-before-build */
   u32 size;          /* VirtualSize (real bytes; for .bss, mem size) */
   u32 size_raw;      /* SizeOfRawData (file size, FileAlignment-padded) */
   u32 rva;           /* VirtualAddress in image */
   u32 file_offset;   /* PointerToRawData; 0 for .bss */
   u8 in_image;       /* 1 if this bucket is emitted as a section */
   u8 has_file_bytes; /* 0 for .bss */
   u8 pad[2];
 } CoffSection;
 
 /* ---- byte writer helpers ---- */
 
 static void coff_write_zeroes(Writer* w, u64 n) {
   static const u8 zeroes[256] = {0};
   while (n) {
     u64 step = n > sizeof(zeroes) ? sizeof(zeroes) : n;
     kit_writer_write(w, zeroes, (size_t)step);
     n -= step;
   }
 }
 
 /* Return the COFF bucket for a kept LinkSection.  SF_TLS sections route
  * into the dedicated .tls bucket so SECREL relocations from TLS access
  * code resolve against the merged TLS image, not against .data.
  * Everything else partitions on SF_EXEC / SF_WRITE plus the SSEM_NOBITS
  * bit for .bss. */
 static CoffBucket coff_bucket_for(Compiler* c, const LinkSection* ls) {
   if (ls->name) {
     Slice nm = pool_slice(c->global, ls->name);
     if (nm.s && nm.len >= 6u && memcmp(nm.s, ".pdata", 6u) == 0)
       return COFF_BUCKET_PDATA;
   }
   if (ls->flags & SF_EXEC) return COFF_BUCKET_TEXT;
   if (ls->flags & SF_TLS) return COFF_BUCKET_TLS;
   if (ls->sem == SSEM_NOBITS) return COFF_BUCKET_BSS;
   if (ls->flags & SF_WRITE) return COFF_BUCKET_DATA;
   return COFF_BUCKET_RDATA;
 }
 
 /* True for relocation kinds that need an entry in .reloc so the OS
  * loader can patch the site after ASLR picks a runtime ImageBase.
  * PC-relative fixups don't need base-relocs — the displacement is
  * load-invariant. */
 static int coff_reloc_needs_base_reloc(RelocKind k) {
   return k == R_ABS64 || k == R_ABS32;
 }
 
 /* Look up the LinkSection whose [vaddr, vaddr+size] range covers the
  * given image-relative address `v`, or return NULL.  Used to attribute
  * symbol vaddrs to a containing section so we can apply per-section
  * vaddr deltas after re-laying out for PE. */
 static const LinkSection* coff_section_at(const LinkImage* img, u64 v) {
   u32 i;
   for (i = 0; i < img->nsections; ++i) {
     const LinkSection* ls = &img->sections[i];
     if (v >= ls->vaddr && v <= ls->vaddr + ls->size) return ls;
   }
   return NULL;
 }
 
 /* Per-input-section delta map.  Indexed by `LinkSection.id - 1`.
  * Populated by coff_build_buckets.  Consumed by every subsequent pass
  * that needs to translate input-coordinate offsets (the world that
  * img->sections / img->relocs live in) into PE-coordinate ones (where
  * the writer plants bytes).  delta is stored explicitly so callers
  * avoid recomputing (new_rva + bucket.rva - old_vaddr) for every
  * LinkRelocApply whose link_section_id points at the section. */
 typedef struct CoffSecMap {
   u32 new_rva;      /* image-relative RVA after PE relayout */
   u32 new_file_off; /* file offset of the patched byte */
   i64 delta;        /* new_rva - old_vaddr */
   u8 bucket;
   u8 pad[3];
 } CoffSecMap;
 
 /* TLS directory placement state. Populated when at least one SF_TLS
  * section survives dead-strip; consumed by the optional-header writer,
  * the .reloc builder (base-relocs for the four absolute VA fields),
  * and the .rdata emit pass that writes the final 40-byte record. */
 typedef struct CoffTlsLayout {
   int present;       /* 1 iff at least one TLS section was kept */
   u32 dir_rdata_off; /* byte offset of the IMAGE_TLS_DIRECTORY64 within .rdata
                       */
   u32 tls_size;      /* size of the merged .tls bucket */
   LinkSymId tls_index_sym; /* resolved _tls_index LinkSymbol */
   LinkSymId callbacks_sym; /* __xl_a when mingw's TLS callbacks are linked */
   u64 callbacks_addend;    /* mingw points past the leading NULL sentinel */
 } CoffTlsLayout;
 
 static LinkSymId coff_find_sym(LinkImage* img, const char* name) {
   Sym sym = pool_intern_cstr(img->c->global, name);
   u32 n = LinkSyms_count(&img->syms);
   u32 i;
   for (i = 0; i < n; ++i) {
     const LinkSymbol* s = LinkSyms_at(&img->syms, i);
     if (s->name == sym) return (LinkSymId)(i + 1);
   }
   return LINK_SYM_NONE;
 }
 
 /* Locate _tls_index by name in the resolved symbol table. mingw's
  * libmingwex defines it (as part of tlsmcrt); without a CRT the link
  * fails here with a clear message rather than producing a TLS
  * directory pointing at a stale address. */
 static LinkSymId coff_find_tls_index_sym(LinkImage* img) {
   return coff_find_sym(img, "_tls_index");
 }
 
 static const LinkSection* coff_symbol_section(const LinkImage* img,
                                               const LinkSymbol* s) {
   if (s->name) {
     Slice nm_s = pool_slice(img->c->global, s->name);
     const char* nm = nm_s.s;
     size_t n = nm_s.len;
     const char* sec_name = NULL;
     if (nm && n == 6 && memcmp(nm, "__xd_a", 6) == 0)
       sec_name = ".CRT$XDA";
     else if (nm && n == 6 && memcmp(nm, "__xd_z", 6) == 0)
       sec_name = ".CRT$XDZ";
     else if (nm && n == 6 && memcmp(nm, "__xl_a", 6) == 0)
       sec_name = ".CRT$XLA";
     else if (nm && n == 6 && memcmp(nm, "__xl_c", 6) == 0)
       sec_name = ".CRT$XLC";
     else if (nm && n == 6 && memcmp(nm, "__xl_d", 6) == 0)
       sec_name = ".CRT$XLD";
     else if (nm && n == 6 && memcmp(nm, "__xl_z", 6) == 0)
       sec_name = ".CRT$XLZ";
     if (sec_name) {
       u32 i;
       for (i = 0; i < img->nsections; ++i) {
         const LinkSection* ls = &img->sections[i];
         if (ls->name &&
             slice_eq_cstr(pool_slice(img->c->global, ls->name), sec_name))
           return ls;
       }
     }
   }
   if (s->section_id != LINK_SEC_NONE && s->section_id <= img->nsections)
     return &img->sections[s->section_id - 1];
   return coff_section_at(img, s->vaddr);
 }
 
 static u64 coff_symbol_final_va(const LinkImage* img,
                                 const CoffSection out[COFF_NBUCKETS],
                                 const CoffSecMap* map, LinkSymId id,
                                 const char* what) {
   const LinkSymbol* s = LinkSyms_at(&img->syms, id - 1);
   if (!s->defined || s->kind == SK_ABS) {
     compiler_panic(img->c, SRCLOC_NONE,
                    "link_emit_coff: `%.*s` is not a defined section-bound "
                    "symbol",
                    SLICE_ARG(slice_from_cstr(what)));
   }
   const LinkSection* sec = coff_symbol_section(img, s);
   if (!sec) {
     compiler_panic(img->c, SRCLOC_NONE,
                    "link_emit_coff: `%.*s` has no containing section",
                    SLICE_ARG(slice_from_cstr(what)));
   }
   u8 b = map[sec->id - 1].bucket;
   return PE_IMAGE_BASE + (u64)out[b].rva + (u64)map[sec->id - 1].new_rva +
          (s->vaddr - sec->vaddr);
 }
 
 /* Reserve 40 bytes at the tail of the .rdata bucket for the
  * IMAGE_TLS_DIRECTORY64 record. Records the offset for later emit and
  * grows the bucket if needed. The bytes start zeroed; coff_emit_tls_dir
  * fills them in once final RVAs are known. */
 static void coff_plan_tls_layout(LinkImage* img, CoffSection out[COFF_NBUCKETS],
                                  u32* rdata_cap, CoffTlsLayout* tls) {
   memset(tls, 0, sizeof(*tls));
   if (out[COFF_BUCKET_TLS].size == 0) return;
   tls->present = 1;
   tls->tls_size = out[COFF_BUCKET_TLS].size;
   tls->tls_index_sym = coff_find_tls_index_sym(img);
   if (tls->tls_index_sym == LINK_SYM_NONE) {
     compiler_panic(img->c, SRCLOC_NONE,
                    "link_emit_coff: .tls section requires `_tls_index` "
                    "(provided by mingw libmingwex / tlsmcrt.o) — none of "
                    "the linked inputs define it");
   }
   /* IMAGE_TLS_DIRECTORY64 needs 8-byte alignment for its u64 fields;
    * round the .rdata size up before reserving the 40-byte record. */
   tls->callbacks_sym = coff_find_sym(img, "__xl_a");
   if (tls->callbacks_sym != LINK_SYM_NONE) {
     tls->callbacks_addend = 8;
   } else {
     tls->callbacks_sym = coff_find_sym(img, "__xl_c");
     tls->callbacks_addend = 0;
   }
   u32 rdata_size = (u32)ALIGN_UP((u64)out[COFF_BUCKET_RDATA].size, 8ull);
   u32 need = rdata_size + COFF_TLS_DIRECTORY64_SIZE;
   if (need > *rdata_cap) {
     (void)VEC_GROW(img->heap, out[COFF_BUCKET_RDATA].bytes, *rdata_cap, need);
   }
   /* Zero any padding bytes introduced by the alignment bump and the
    * directory slot itself. */
   if (rdata_size > out[COFF_BUCKET_RDATA].size) {
     memset(out[COFF_BUCKET_RDATA].bytes + out[COFF_BUCKET_RDATA].size, 0,
            rdata_size - out[COFF_BUCKET_RDATA].size);
   }
   memset(out[COFF_BUCKET_RDATA].bytes + rdata_size, 0,
          COFF_TLS_DIRECTORY64_SIZE);
   tls->dir_rdata_off = rdata_size;
   out[COFF_BUCKET_RDATA].size = need;
 }
 
 /* Write the IMAGE_TLS_DIRECTORY64 bytes once all bucket RVAs are
  * final. Each u64 VA field gets ImageBase + RVA; the base-reloc pass
  * will emit IMAGE_REL_BASED_DIR64 entries so ASLR keeps them valid. */
 static void coff_emit_tls_dir(const LinkImage* img,
                               const CoffSection out[COFF_NBUCKETS],
                               const CoffSecMap* map, const CoffTlsLayout* tls) {
   if (!tls->present) return;
   u64 tls_start = PE_IMAGE_BASE + (u64)out[COFF_BUCKET_TLS].rva;
   u64 tls_end = tls_start + (u64)tls->tls_size;
   u64 idx_vaddr =
       coff_symbol_final_va(img, out, map, tls->tls_index_sym, "_tls_index");
   const char* callbacks_name = tls->callbacks_addend ? "__xl_a" : "__xl_c";
   u64 callbacks_vaddr =
       tls->callbacks_sym
           ? coff_symbol_final_va(img, out, map, tls->callbacks_sym,
                                  callbacks_name) +
                 tls->callbacks_addend
           : 0;
 
   u8* p = out[COFF_BUCKET_RDATA].bytes + tls->dir_rdata_off;
   wr_u64_le(p + COFF_TLSDIR_OFF_START_ADDR, tls_start);
   wr_u64_le(p + COFF_TLSDIR_OFF_END_ADDR, tls_end);
   wr_u64_le(p + COFF_TLSDIR_OFF_INDEX_ADDR, idx_vaddr);
   wr_u64_le(p + COFF_TLSDIR_OFF_CALLBACKS, callbacks_vaddr);
   wr_u32_le(p + 32, 0); /* SizeOfZeroFill */
   wr_u32_le(p + 36, 0); /* Characteristics */
 }
 
 static void coff_define_tls_used(LinkImage* img,
                                  const CoffSection out[COFF_NBUCKETS],
                                  const CoffTlsLayout* tls) {
   if (!tls->present) return;
   if (!img->linker) return;
   link_emit_boundary_sym(img->linker, img, "_tls_used",
                          PE_IMAGE_BASE + (u64)out[COFF_BUCKET_RDATA].rva +
                              (u64)tls->dir_rdata_off);
 }
 
 /* ---- import-table synthesis (Phase 3.2) ---------------------------
  *
  * Per doc/OBJ.md: every LinkSymbol with `imported = 1` gets
  * routed through an IAT slot synthesized in `.idata`.  Function
  * imports additionally receive a small per-arch stub in `.text`
  * (`ff 25 disp32` on x64 / `adrp;ldr;br` on aa64) so a direct CALL26
  * or PC32 against the symbol lands on a stub that indirects through
  * the IAT.  Data imports skip the stub — the symbol's final vaddr is
  * just the IAT slot vaddr, and code-gen emits a `mov rax, [slot]`
  * sequence the same way it would for any other GOT-style load.
  *
  * kit's COFF code-gen uses direct symbol references; there is no
  * separate `__imp_<name>` LinkSymbol consulted at link time.  The
  * IAT-slot rewrite happens entirely by overriding the imported
  * symbol's vaddr in apply_all_relocs. */
 
 typedef struct CoffImport {
   LinkSymId sym;   /* canonical LinkSymId from img->syms */
   Sym import_name; /* DLL export name override (short-import NameType); 0=use
                       sym */
   u32 dll_idx;     /* index into CoffImportTable.dlls */
   u32 stub_off;    /* offset in .text bucket (functions only) */
   u32 iat_off;     /* offset in .idata IAT block */
   u32 ilt_off;     /* offset in .idata ILT block */
   u32 hint_off;    /* offset in .idata hint/name table */
   u8 is_func;
   u8 pad[3];
 } CoffImport;
 
 typedef struct CoffImportDll {
   Sym soname;
   u32 first; /* index of first import in CoffImportTable.imports */
   u32 count;
   u32 ilt_off;  /* offset of this DLL's ILT block in .idata */
   u32 iat_off;  /* offset of this DLL's IAT block in .idata */
   u32 name_off; /* offset of DLL name string in .idata */
 } CoffImportDll;
 
 typedef struct CoffImportTable {
   CoffImport* imports;
   u32 nimports;
   u32 imports_cap;   /* heap-allocation size for cleanup */
   u32 nfunc_imports; /* subset of nimports that needs a .text stub */
   CoffImportDll* dlls;
   u32 ndlls;
   u32 dlls_cap; /* heap-allocation size for cleanup */
   /* Offsets within .idata of the five sub-blocks.  Filled in by
    * coff_plan_idata_layout once nimports / ndlls is known. */
   u32 desc_off; /* always 0 — descriptors come first */
   u32 desc_size;
   u32 ilt_base;
   u32 ilt_total;
   u32 iat_base;
   u32 iat_total;
   u32 hint_base;
   u32 hint_total;
   u32 name_base;
   u32 name_total;
   u32 idata_size;
   /* Stub region in .text bucket.  Stubs are appended after every
    * input .text section has been bucketed.  stub_text_off is the
    * bucket-local offset of the first stub; per-import stub offsets
    * are stored in CoffImport.stub_off. */
   u32 stub_text_off;
   u32 stub_total;
 } CoffImportTable;
 
 /* Sort comparator: imports grouped by DLL slot, stable on input
  * order within a DLL (sort is stable enough via secondary key). */
 static int coff_import_cmp(const void* a, const void* b) {
   const CoffImport* ia = (const CoffImport*)a;
   const CoffImport* ib = (const CoffImport*)b;
   if (ia->dll_idx < ib->dll_idx) return -1;
   if (ia->dll_idx > ib->dll_idx) return 1;
   /* Secondary: LinkSymId so the order is reproducible. */
   if (ia->sym < ib->sym) return -1;
   if (ia->sym > ib->sym) return 1;
   return 0;
 }
 
 static const char* coff_import_lookup_name(Compiler* c, const LinkSymbol* s,
                                            size_t* nlen_out) {
   Slice nm_s = s->name ? pool_slice(c->global, s->name) : SLICE_NULL;
   const char* nm = nm_s.s;
   size_t nlen = nm_s.len;
   static const char kImpPrefix[] = "__imp_";
   const size_t kImpPrefixLen = sizeof(kImpPrefix) - 1u;
   if (nm && nlen > kImpPrefixLen &&
       memcmp(nm, kImpPrefix, kImpPrefixLen) == 0) {
     nm += kImpPrefixLen;
     nlen -= kImpPrefixLen;
   }
   if (nlen_out) *nlen_out = nlen;
   return nm;
 }
 
 /* The name placed in the PE hint/name table for an import. Honors the
  * short-import NameType override (CoffImport.import_name, e.g. EXPORTAS's real
  * DLL export name) when present, else derives it from the symbol name. */
 static const char* coff_import_emit_name(Compiler* c, const CoffImport* imp,
                                          const LinkSymbol* s,
                                          size_t* nlen_out) {
   if (imp->import_name) {
     Slice nm_s = pool_slice(c->global, imp->import_name);
     if (nlen_out) *nlen_out = nm_s.len;
     return nm_s.s;
   }
   return coff_import_lookup_name(c, s, nlen_out);
 }
 
 /* True iff the import classifies as function-like.  Mirrors the ELF
  * `sym_is_func_import` heuristic: if the canonical kind is known
  * we trust it, otherwise we default to function (which matches the
  * COFF code-gen contract — direct calls are by far the common case
  * and a data import wrongly stubbed would still fail loudly via the
  * IAT-routed call). */
 static int coff_import_is_func(Compiler* c, const LinkSymbol* s) {
   if (s->name) {
     Slice nm_s = pool_slice(c->global, s->name);
     const char* nm = nm_s.s;
     size_t nlen = nm_s.len;
     if (nm && nlen > 6u && memcmp(nm, "__imp_", 6u) == 0) return 0;
   }
   if (s->kind == SK_FUNC || s->kind == SK_IFUNC) return 1;
   if (s->kind == SK_OBJ) return 0;
   /* SK_UNDEF / SK_NOTYPE: assume function (the common case). */
   return 1;
 }
 
 /* Walk LinkSyms, collect imports, group by DLL soname.  Returns 1 if
  * any imports were collected, 0 otherwise (caller skips the entire
  * .idata path). */
 static int coff_collect_imports(LinkImage* img, CoffImportTable* it) {
   Heap* heap = img->heap;
   Compiler* c = img->c;
   Linker* l = img->linker;
   u32 nsyms = LinkSyms_count(&img->syms);
   u32 imp_cap = 0;
   u32 dll_cap = 0;
   u32 i;
 
   memset(it, 0, sizeof(*it));
   if (!l) return 0;
   for (i = 0; i < nsyms; ++i) {
     LinkSymbol* s = LinkSyms_at(&img->syms, i);
     LinkInput* in;
     u32 dll_idx = (u32)-1;
     u32 d;
     if (!s->imported) continue;
     if (s->name == 0) continue;
     if (s->dso_input_id == LINK_INPUT_NONE) {
       compiler_panic(c, SRCLOC_NONE,
                      "link_emit_coff: imported symbol has no providing DSO");
     }
     /* img->globals only carries defined globals/weaks; imported undefs
      * never land there.  Dedup by name: skip if any earlier slot
      * already collected this name. */
     {
       int dup = 0;
       for (u32 k = 0; k < it->nimports; ++k) {
         LinkSymbol* prev = LinkSyms_at(&img->syms, it->imports[k].sym - 1);
         if (prev->name == s->name) {
           dup = 1;
           break;
         }
       }
       if (dup) continue;
     }
     if (s->dso_input_id - 1u >= LinkInputs_count(&l->inputs)) {
       compiler_panic(c, SRCLOC_NONE,
                      "link_emit_coff: import dso_input_id out of range");
     }
     in = LinkInputs_at(&l->inputs, s->dso_input_id - 1u);
     if (in->soname == 0) {
       compiler_panic(c, SRCLOC_NONE,
                      "link_emit_coff: providing DSO has no soname; cannot "
                      "emit IMAGE_IMPORT_DESCRIPTOR.Name");
     }
     /* Find-or-add the DLL slot. */
     for (d = 0; d < it->ndlls; ++d) {
       if (it->dlls[d].soname == in->soname) {
         dll_idx = d;
         break;
       }
     }
     if (dll_idx == (u32)-1) {
       if (VEC_GROW(heap, it->dlls, dll_cap, it->ndlls + 1u))
         compiler_panic(c, SRCLOC_NONE, "link_emit_coff: oom on import dlls");
       dll_idx = it->ndlls++;
       memset(&it->dlls[dll_idx], 0, sizeof(it->dlls[dll_idx]));
       it->dlls[dll_idx].soname = in->soname;
     }
     if (VEC_GROW(heap, it->imports, imp_cap, it->nimports + 1u))
       compiler_panic(c, SRCLOC_NONE, "link_emit_coff: oom on imports");
     memset(&it->imports[it->nimports], 0, sizeof(it->imports[it->nimports]));
     it->imports[it->nimports].sym = s->id;
     it->imports[it->nimports].import_name = in->coff_import_name;
     it->imports[it->nimports].dll_idx = dll_idx;
     it->imports[it->nimports].is_func = (u8)coff_import_is_func(c, s);
     if (it->imports[it->nimports].is_func) ++it->nfunc_imports;
     ++it->nimports;
     it->dlls[dll_idx].count++;
   }
   if (it->nimports == 0) return 0;
   /* Re-bucket the imports array so each DLL's run is contiguous. */
   qsort(it->imports, it->nimports, sizeof(*it->imports), coff_import_cmp);
   /* Fix up CoffImportDll.first now that imports[] is sorted. */
   {
     u32 cur = 0;
     for (u32 d = 0; d < it->ndlls; ++d) {
       it->dlls[d].first = cur;
       cur += it->dlls[d].count;
     }
   }
   it->imports_cap = imp_cap;
   it->dlls_cap = dll_cap;
   return 1;
 }
 
 static void coff_imports_free(LinkImage* img, CoffImportTable* it) {
   Heap* heap = img->heap;
   if (it->imports) {
     heap->free(heap, it->imports,
                (size_t)it->imports_cap * sizeof(*it->imports));
   }
   if (it->dlls) {
     heap->free(heap, it->dlls, (size_t)it->dlls_cap * sizeof(*it->dlls));
   }
 }
 
 /* Compute every per-block / per-import offset inside .idata and the
  * total .idata size in bytes.  Also assigns per-import hint/name and
  * dll-name offsets so the descriptor table can reference them by RVA
  * later (RVAs need the bucket's final RVA, added in coff_emit_idata). */
 static void coff_plan_idata_layout(LinkImage* img, CoffImportTable* it) {
   Compiler* c = img->c;
   u32 off;
 
   /* Block 1: import descriptors (one per DLL + zero terminator). */
   it->desc_off = 0;
   it->desc_size = (it->ndlls + 1u) * COFF_IMPORT_DESCRIPTOR_SIZE;
   off = (u32)ALIGN_UP((u64)it->desc_size, (u64)PE_IDATA_BLOCK_ALIGN);
 
   /* Block 2: ILTs.  Per DLL: count entries + 1 (terminator), 8 B each. */
   it->ilt_base = off;
   for (u32 d = 0; d < it->ndlls; ++d) {
     it->dlls[d].ilt_off = off;
     /* Per-import: assign ilt_off within this DLL's block. */
     for (u32 k = 0; k < it->dlls[d].count; ++k) {
       it->imports[it->dlls[d].first + k].ilt_off =
           off + k * (u32)COFF_THUNK_DATA64_SIZE;
     }
     off += (it->dlls[d].count + 1u) * (u32)COFF_THUNK_DATA64_SIZE;
   }
   it->ilt_total = off - it->ilt_base;
   off = (u32)ALIGN_UP((u64)off, (u64)PE_IDATA_BLOCK_ALIGN);
 
   /* Block 3: IATs (same shape as ILTs). */
   it->iat_base = off;
   for (u32 d = 0; d < it->ndlls; ++d) {
     it->dlls[d].iat_off = off;
     for (u32 k = 0; k < it->dlls[d].count; ++k) {
       it->imports[it->dlls[d].first + k].iat_off =
           off + k * (u32)COFF_THUNK_DATA64_SIZE;
     }
     off += (it->dlls[d].count + 1u) * (u32)COFF_THUNK_DATA64_SIZE;
   }
   it->iat_total = off - it->iat_base;
   off = (u32)ALIGN_UP((u64)off, (u64)PE_IDATA_BLOCK_ALIGN);
 
   /* Block 4: hint/name records.  Each: u16 hint + NUL-term name +
    * 1-byte pad if the resulting size is odd (PE/COFF spec). */
   it->hint_base = off;
   for (u32 i = 0; i < it->nimports; ++i) {
     LinkSymbol* s = LinkSyms_at(&img->syms, it->imports[i].sym - 1);
     size_t nlen = 0;
     const char* nm = coff_import_emit_name(c, &it->imports[i], s, &nlen);
     if (!nm || nlen == 0)
       compiler_panic(c, SRCLOC_NONE,
                      "link_emit_coff: imported symbol has empty name");
     it->imports[i].hint_off = off;
     /* hint (2 B) + name (nlen + 1) + optional pad to even. */
     u32 rec = 2u + (u32)nlen + 1u;
     if (rec & 1u) ++rec;
     off += rec;
   }
   it->hint_total = off - it->hint_base;
   off = (u32)ALIGN_UP((u64)off, (u64)PE_IDATA_BLOCK_ALIGN);
 
   /* Block 5: DLL name strings (NUL-terminated). */
   it->name_base = off;
   for (u32 d = 0; d < it->ndlls; ++d) {
     Slice nm_s = pool_slice(c->global, it->dlls[d].soname);
     const char* nm = nm_s.s;
     size_t nlen = nm_s.len;
     if (!nm || nlen == 0)
       compiler_panic(c, SRCLOC_NONE,
                      "link_emit_coff: providing DSO has empty soname");
     it->dlls[d].name_off = off;
     off += (u32)nlen + 1u;
   }
   it->name_total = off - it->name_base;
   it->idata_size = off;
 }
 
 /* Append the function-import stubs to the .text bucket.  Each stub is
  * the format arch descriptor's stub size. Records each stub's bucket-
  * local offset on the matching CoffImport so the per-symbol stub vaddr
  * can be computed once the .text bucket's RVA is final. */
 static void coff_append_stubs(LinkImage* img, CoffImportTable* it,
                               CoffSection* text_bucket, u32* text_bucket_cap) {
   Heap* heap = img->heap;
   Compiler* c = img->c;
   const ObjFormatImpl* fmt = obj_format_lookup(KIT_OBJ_COFF);
   const ObjCoffArchOps* arch =
       fmt && fmt->coff_arch ? fmt->coff_arch(c->target.arch) : NULL;
   u32 stub_size;
   u32 stub_align;
   u64 cur;
   if (!arch || arch->stub_size == 0 || !arch->emit_iat_stub) {
     compiler_panic(c, SRCLOC_NONE,
                    "link_emit_coff: arch has no COFF IAT stub emitter");
   }
   stub_size = arch->stub_size;
   /* Stubs are pure code; aligning to instruction alignment is enough.
    * x64 wants byte-granular, aa64 wants 4 B; align to stub size as a
    * convenient upper bound. */
   stub_align = stub_size;
   cur = (u64)text_bucket->size;
   cur = ALIGN_UP(cur, (u64)stub_align);
   it->stub_text_off = (u32)cur;
   for (u32 i = 0; i < it->nimports; ++i) {
     if (!it->imports[i].is_func) continue;
     it->imports[i].stub_off = (u32)cur;
     cur += stub_size;
   }
   it->stub_total = (u32)cur - it->stub_text_off;
   if (it->stub_total == 0) return;
   /* Grow the .text bucket buffer to hold the new region. */
   u32 need = (u32)cur;
   if (need > *text_bucket_cap) {
     (void)VEC_GROW(heap, text_bucket->bytes, *text_bucket_cap, need);
   }
   /* Zero the alignment pad; stub bytes are written later by
    * coff_emit_stubs once vaddrs are known. */
   if ((u32)cur > text_bucket->size) {
     memset(text_bucket->bytes + text_bucket->size, 0,
            (size_t)((u32)cur - text_bucket->size));
   }
   text_bucket->size = (u32)cur;
 }
 
 /* Emit each function import's IAT stub into the .text bucket.  Must
  * run after coff_assign_layout has fixed both .text's RVA and
  * .idata's RVA, since the stub bakes in the post-shift IAT slot
  * displacement. */
 static void coff_emit_stubs(LinkImage* img, const CoffImportTable* it,
                             const CoffSection out[COFF_NBUCKETS]) {
   Compiler* c = img->c;
   const ObjFormatImpl* fmt = obj_format_lookup(KIT_OBJ_COFF);
   const ObjCoffArchOps* arch =
       fmt && fmt->coff_arch ? fmt->coff_arch(c->target.arch) : NULL;
   u64 img_base = PE_IMAGE_BASE;
   u32 text_rva = out[COFF_BUCKET_TEXT].rva;
   u32 idata_rva = out[COFF_BUCKET_IDATA].rva;
   if (!arch || !arch->emit_iat_stub) {
     compiler_panic(c, SRCLOC_NONE,
                    "link_emit_coff: arch has no COFF IAT stub emitter");
   }
   for (u32 i = 0; i < it->nimports; ++i) {
     u64 stub_va, slot_va;
     if (!it->imports[i].is_func) continue;
     stub_va = img_base + (u64)text_rva + (u64)it->imports[i].stub_off;
     slot_va = img_base + (u64)idata_rva + (u64)it->imports[i].iat_off;
     arch->emit_iat_stub(out[COFF_BUCKET_TEXT].bytes + it->imports[i].stub_off,
                         stub_va, slot_va);
   }
 }
 
 /* Emit .idata content into the bucket buffer.  Allocates the buffer
  * here (size is already known from coff_plan_idata_layout). */
 static void coff_emit_idata(LinkImage* img, const CoffImportTable* it,
                             CoffSection out[COFF_NBUCKETS],
                             u32* idata_bucket_cap) {
   Heap* heap = img->heap;
   Compiler* c = img->c;
   CoffSection* idata = &out[COFF_BUCKET_IDATA];
   u32 idata_rva = idata->rva;
   u8* buf;
   /* Allocate the bucket buffer (idata_size is already block-aligned). */
   buf = (u8*)heap->alloc(heap, it->idata_size, _Alignof(u64));
   if (!buf)
     compiler_panic(c, SRCLOC_NONE, "link_emit_coff: oom on .idata buffer");
   memset(buf, 0, it->idata_size);
   idata->bytes = buf;
   idata->size = it->idata_size;
   *idata_bucket_cap = it->idata_size;
 
   /* Block 1: IMAGE_IMPORT_DESCRIPTOR table. */
   for (u32 d = 0; d < it->ndlls; ++d) {
     u8* p = buf + d * (u32)COFF_IMPORT_DESCRIPTOR_SIZE;
     u32 ilt_rva = idata_rva + it->dlls[d].ilt_off;
     u32 iat_rva = idata_rva + it->dlls[d].iat_off;
     u32 name_rva = idata_rva + it->dlls[d].name_off;
     wr_u32_le(p + 0, ilt_rva);   /* OriginalFirstThunk */
     wr_u32_le(p + 4, 0u);        /* TimeDateStamp */
     wr_u32_le(p + 8, 0u);        /* ForwarderChain */
     wr_u32_le(p + 12, name_rva); /* Name */
     wr_u32_le(p + 16, iat_rva);  /* FirstThunk */
   }
   /* Trailing zero descriptor already zero-filled by memset. */
 
   /* Blocks 2+3: ILT + IAT.  Both initially point at the same hint/name
    * record for each import; the OS loader rewrites IAT entries at
    * load time. */
   for (u32 i = 0; i < it->nimports; ++i) {
     u64 hint_rva = (u64)idata_rva + (u64)it->imports[i].hint_off;
     wr_u64_le(buf + it->imports[i].ilt_off, hint_rva);
     wr_u64_le(buf + it->imports[i].iat_off, hint_rva);
   }
   /* Per-DLL ILT/IAT terminators are u64 0, already zero-filled. */
 
   /* Block 4: hint/name records. */
   for (u32 i = 0; i < it->nimports; ++i) {
     LinkSymbol* s = LinkSyms_at(&img->syms, it->imports[i].sym - 1);
     size_t nlen = 0;
     const char* nm = coff_import_emit_name(c, &it->imports[i], s, &nlen);
     u8* p = buf + it->imports[i].hint_off;
     wr_u16_le(p, PE_IMPORT_HINT_NONE);
     memcpy(p + 2, nm, nlen);
     /* NUL terminator + optional pad already zero. */
   }
 
   /* Block 5: DLL name strings. */
   for (u32 d = 0; d < it->ndlls; ++d) {
     Slice nm_s = pool_slice(c->global, it->dlls[d].soname);
     const char* nm = nm_s.s;
     size_t nlen = nm_s.len;
     memcpy(buf + it->dlls[d].name_off, nm, nlen);
     /* NUL already zero. */
   }
 }
 
 /* Per-LinkSymId vaddr override table for imports.  Indexed by
  * LinkSymId-1; 0 means "not an import".  Built once after the .idata
  * bucket RVA is final.  Consumed by coff_apply_all_relocs in lieu of
  * the symbol's own vaddr field (which is 0 for imports). */
 typedef struct CoffImportVaddr {
   u64* by_sym; /* size = nsyms; 0 entries mean "not imported" */
   u32 nsyms;
 } CoffImportVaddr;
 
 static void coff_import_vaddr_build(LinkImage* img, const CoffImportTable* it,
                                     const CoffSection out[COFF_NBUCKETS],
                                     CoffImportVaddr* iv) {
   Heap* heap = img->heap;
   u64 img_base = PE_IMAGE_BASE;
   u32 text_rva = out[COFF_BUCKET_TEXT].rva;
   u32 idata_rva = out[COFF_BUCKET_IDATA].rva;
   iv->nsyms = LinkSyms_count(&img->syms);
   iv->by_sym = (u64*)heap->alloc(heap, sizeof(u64) * (size_t)(iv->nsyms + 1u),
                                  _Alignof(u64));
   if (!iv->by_sym)
     compiler_panic(img->c, SRCLOC_NONE,
                    "link_emit_coff: oom on import vaddr table");
   memset(iv->by_sym, 0, sizeof(u64) * (size_t)(iv->nsyms + 1u));
   for (u32 i = 0; i < it->nimports; ++i) {
     LinkSymId sid = it->imports[i].sym;
     u64 va;
     if (it->imports[i].is_func) {
       va = img_base + (u64)text_rva + (u64)it->imports[i].stub_off;
     } else {
       va = img_base + (u64)idata_rva + (u64)it->imports[i].iat_off;
     }
     iv->by_sym[sid - 1u] = va;
     /* Fan out across every shadow LinkSymId with the same name so a
      * per-input undef reference resolves to the same import slot. */
     {
       LinkSymbol* canonical = LinkSyms_at(&img->syms, sid - 1u);
       for (u32 j = 0; j < iv->nsyms; ++j) {
         LinkSymbol* s = LinkSyms_at(&img->syms, j);
         if (s->name == canonical->name && s->imported) {
           iv->by_sym[s->id - 1u] = va;
         }
       }
     }
   }
 }
 
 static void coff_import_vaddr_free(LinkImage* img, CoffImportVaddr* iv) {
   Heap* heap = img->heap;
   if (iv->by_sym) {
     heap->free(heap, iv->by_sym, sizeof(u64) * (size_t)(iv->nsyms + 1u));
   }
 }
 
 /* Resolve Compiler.target.arch -> IMAGE_FILE_MACHINE_* via the per-arch
  * coff ops table.  Panic if the arch has no COFF descriptor or the
  * machine value is one kit doesn't ship (Phase 1 supports AMD64 and
  * ARM64 only). */
 static u16 coff_machine_or_panic(Compiler* c) {
   const ObjFormatImpl* fmt = obj_format_lookup(KIT_OBJ_COFF);
   const ObjCoffArchOps* arch =
       fmt && fmt->coff_arch ? fmt->coff_arch(c->target.arch) : NULL;
   u16 m;
   if (!arch)
     compiler_panic(c, SRCLOC_NONE, "link_emit_coff: no COFF arch descriptor");
   m = arch->machine;
   if (m != IMAGE_FILE_MACHINE_AMD64 && m != IMAGE_FILE_MACHINE_ARM64)
     compiler_panic(c, SRCLOC_NONE, "link_emit_coff: unsupported machine 0x%x",
                    (unsigned)m);
   return m;
 }
 
 static int coff_section_name_starts(Compiler* c, const LinkSection* ls,
                                     const char* prefix) {
   size_t pn = slice_from_cstr(prefix).len;
   Slice s_s = ls->name ? pool_slice(c->global, ls->name) : SLICE_NULL;
   const char* s = s_s.s;
   size_t n = s_s.len;
   return s && n >= pn && memcmp(s, prefix, pn) == 0;
 }
 
 static int coff_section_name_cmp(Compiler* c, const LinkSection* a,
                                  const LinkSection* b) {
   Slice as_s = a->name ? pool_slice(c->global, a->name) : SLICE_NULL;
   Slice bs_s = b->name ? pool_slice(c->global, b->name) : SLICE_NULL;
   const char* as = as_s.s ? as_s.s : "";
   const char* bs = bs_s.s ? bs_s.s : "";
   size_t an = as_s.len, bn = bs_s.len;
   size_t n = an < bn ? an : bn;
   int cmp = n ? memcmp(as, bs, n) : 0;
   if (cmp) return cmp;
   if (an < bn) return -1;
   if (an > bn) return 1;
   if (a->id < b->id) return -1;
   if (a->id > b->id) return 1;
   return 0;
 }
 
 static void coff_place_section(LinkImage* img, CoffSection out[COFF_NBUCKETS],
                                CoffSecMap* map, u64 bucket_cur[COFF_NBUCKETS],
                                u32 bucket_cap[COFF_NBUCKETS],
                                const LinkSection* ls) {
   Heap* heap = img->heap;
   CoffBucket b2 = coff_bucket_for(img->c, ls);
   u32 align = ls->align ? ls->align : 1u;
   u64 cur = bucket_cur[b2];
   cur = ALIGN_UP(cur, (u64)align);
   map[ls->id - 1].bucket = (u8)b2;
   /* Record the bucket-local offset; the absolute RVA / file offset
    * are filled in after bucket placement (RVAs need
    * SectionAlignment, file offsets need FileAlignment). */
   map[ls->id - 1].new_rva = (u32)cur;
   if (b2 != COFF_BUCKET_BSS) {
     /* Copy bytes from the source segment buffer into the bucket. */
     if (ls->size) {
       u32 need = (u32)(cur + ls->size);
       if (need > bucket_cap[b2]) {
         (void)VEC_GROW(heap, out[b2].bytes, bucket_cap[b2], need);
       }
       memset(out[b2].bytes + bucket_cur[b2], 0, (size_t)(cur - bucket_cur[b2]));
       if (ls->sem != SSEM_NOBITS) {
         const LinkSegment* seg = &img->segments[ls->segment_id - 1];
         const u8* src = img->segment_bytes[seg->id - 1] +
                         (size_t)(ls->file_offset - seg->file_offset);
         memcpy(out[b2].bytes + cur, src, (size_t)ls->size);
       } else {
         memset(out[b2].bytes + cur, 0, (size_t)ls->size);
       }
     }
   }
   cur += ls->size;
   bucket_cur[b2] = cur;
   out[b2].size = (u32)cur;
 }
 
 static void coff_insert_sorted_section(Compiler* c, const LinkSection** a,
                                        u32* n, const LinkSection* ls) {
   u32 i = *n;
   while (i > 0 && coff_section_name_cmp(c, ls, a[i - 1u]) < 0) {
     a[i] = a[i - 1u];
     --i;
   }
   a[i] = ls;
   *n += 1u;
 }
 
 /* ---- pass 1: bucket input sections, assemble bytes, assign deltas ----
  * CoffSecMap is defined above (alongside CoffTlsLayout) because the
  * TLS planning helpers need to consume one. */
 
 /* Build the four payload buckets (.text/.rdata/.data/.bss).
  *
  * `map[secid-1]` is populated for every kept LinkSection with the
  * section's new RVA, new file offset, the bucket it landed in, and the
  * delta to add to in-section vaddrs.  Bucket buffers are
  * heap-allocated; the caller frees them after emit. */
 static void coff_build_buckets(LinkImage* img, CoffSection out[COFF_NBUCKETS],
                                CoffSecMap* map) {
   Heap* heap = img->heap;
   Compiler* c = img->c;
   const LinkSection** tls_sorted = NULL;
   const LinkSection** crt_sorted = NULL;
   u32 ntls_sorted = 0;
   u32 ncrt_sorted = 0;
   u32 i, b;
 
   for (b = 0; b < COFF_NBUCKETS; ++b) {
     memset(&out[b], 0, sizeof(out[b]));
   }
   out[COFF_BUCKET_TEXT].name = ".text";
   out[COFF_BUCKET_TEXT].characteristics =
       IMAGE_SCN_CNT_CODE | IMAGE_SCN_MEM_EXECUTE | IMAGE_SCN_MEM_READ;
   out[COFF_BUCKET_TEXT].has_file_bytes = 1;
   out[COFF_BUCKET_RDATA].name = ".rdata";
   out[COFF_BUCKET_RDATA].characteristics =
       IMAGE_SCN_CNT_INITIALIZED_DATA | IMAGE_SCN_MEM_READ;
   out[COFF_BUCKET_RDATA].has_file_bytes = 1;
   out[COFF_BUCKET_IDATA].name = ".idata";
   out[COFF_BUCKET_IDATA].characteristics =
       IMAGE_SCN_CNT_INITIALIZED_DATA | IMAGE_SCN_MEM_READ;
   out[COFF_BUCKET_IDATA].has_file_bytes = 1;
   out[COFF_BUCKET_DATA].name = ".data";
   out[COFF_BUCKET_DATA].characteristics =
       IMAGE_SCN_CNT_INITIALIZED_DATA | IMAGE_SCN_MEM_READ | IMAGE_SCN_MEM_WRITE;
   out[COFF_BUCKET_DATA].has_file_bytes = 1;
   /* The Windows loader uses .tls as a *template*: the bytes on disk
    * seed each thread's per-TLS copy at thread creation, and threads
    * write to their copies, not the template.  The PE section is still
    * marked writable because that's what mingw and link.exe emit; the
    * loader special-cases it via the TLS directory. */
   out[COFF_BUCKET_TLS].name = ".tls";
   out[COFF_BUCKET_TLS].characteristics =
       IMAGE_SCN_CNT_INITIALIZED_DATA | IMAGE_SCN_MEM_READ | IMAGE_SCN_MEM_WRITE;
   out[COFF_BUCKET_TLS].has_file_bytes = 1;
   out[COFF_BUCKET_BSS].name = ".bss";
   out[COFF_BUCKET_BSS].characteristics = IMAGE_SCN_CNT_UNINITIALIZED_DATA |
                                          IMAGE_SCN_MEM_READ |
                                          IMAGE_SCN_MEM_WRITE;
   out[COFF_BUCKET_BSS].has_file_bytes = 0;
   out[COFF_BUCKET_PDATA].name = ".pdata";
   out[COFF_BUCKET_PDATA].characteristics =
       IMAGE_SCN_CNT_INITIALIZED_DATA | IMAGE_SCN_MEM_READ;
   out[COFF_BUCKET_PDATA].has_file_bytes = 1;
   out[COFF_BUCKET_RELOC].name = ".reloc";
   out[COFF_BUCKET_RELOC].characteristics = IMAGE_SCN_CNT_INITIALIZED_DATA |
                                            IMAGE_SCN_MEM_READ |
                                            IMAGE_SCN_MEM_DISCARDABLE;
   out[COFF_BUCKET_RELOC].has_file_bytes = 1;
 
   /* Track per-bucket cursors.  Bucket sizes are bounded by the sum of
    * input section sizes plus per-section alignment padding; we grow
    * lazily via VEC_GROW. */
   u64 bucket_cur[COFF_NBUCKETS];
   u32 bucket_cap[COFF_NBUCKETS];
   for (b = 0; b < COFF_NBUCKETS; ++b) {
     bucket_cur[b] = 0;
     bucket_cap[b] = 0;
   }
 
   tls_sorted = img->nsections ? (const LinkSection**)heap->alloc(
                                     heap, sizeof(*tls_sorted) * img->nsections,
                                     _Alignof(const LinkSection*))
                               : NULL;
   crt_sorted = img->nsections ? (const LinkSection**)heap->alloc(
                                     heap, sizeof(*crt_sorted) * img->nsections,
                                     _Alignof(const LinkSection*))
                               : NULL;
   if (img->nsections && (!tls_sorted || !crt_sorted))
     compiler_panic(c, SRCLOC_NONE, "link_emit_coff: oom sorting sections");
 
   for (i = 0; i < img->nsections; ++i) {
     const LinkSection* ls = &img->sections[i];
     if (!(ls->flags & SF_ALLOC)) continue;
     if (ls->flags & SF_TLS) {
       coff_insert_sorted_section(c, tls_sorted, &ntls_sorted, ls);
       continue;
     }
     if (coff_section_name_starts(c, ls, ".CRT$")) {
       coff_insert_sorted_section(c, crt_sorted, &ncrt_sorted, ls);
       continue;
     }
     coff_place_section(img, out, map, bucket_cur, bucket_cap, ls);
   }
 
   for (i = 0; i < ntls_sorted; ++i) {
     coff_place_section(img, out, map, bucket_cur, bucket_cap, tls_sorted[i]);
   }
   for (i = 0; i < ncrt_sorted; ++i) {
     coff_place_section(img, out, map, bucket_cur, bucket_cap, crt_sorted[i]);
   }
 
   /* Track caps so we can free with the right size later (heap->free
    * needs the original allocation size).  Stash into size_raw
    * temporarily — overwritten below with the proper PE value. */
   for (b = 0; b < COFF_NBUCKETS; ++b) out[b].size_raw = bucket_cap[b];
   if (tls_sorted)
     heap->free(heap, tls_sorted, sizeof(*tls_sorted) * img->nsections);
   if (crt_sorted)
     heap->free(heap, crt_sorted, sizeof(*crt_sorted) * img->nsections);
 }
 
 /* Assign RVAs and file offsets to the buckets that participate in the
  * image.  Returns the file offset at which trailing pad-to-EOF should
  * land (== file size). */
 static u64 coff_assign_layout(CoffSection out[COFF_NBUCKETS],
                               u32 headers_file_size, u32 first_section_rva) {
   u32 rva = first_section_rva;
   u64 file = ALIGN_UP((u64)headers_file_size, (u64)PE_FILE_ALIGNMENT);
   u32 b;
   for (b = 0; b < COFF_NBUCKETS; ++b) {
     if (out[b].size == 0) {
       out[b].in_image = 0;
       out[b].rva = 0;
       out[b].file_offset = 0;
       out[b].size_raw = 0;
       continue;
     }
     out[b].in_image = 1;
     out[b].rva = (u32)ALIGN_UP((u64)rva, (u64)PE_SECTION_ALIGNMENT);
     if (out[b].has_file_bytes) {
       out[b].file_offset = (u32)file;
       out[b].size_raw = (u32)ALIGN_UP((u64)out[b].size, (u64)PE_FILE_ALIGNMENT);
       file += out[b].size_raw;
     } else {
       out[b].file_offset = 0;
       out[b].size_raw = 0;
     }
     rva = out[b].rva + out[b].size;
   }
   return file;
 }
 
 /* Build the .reloc bytes by grouping absolute relocs by 4-KiB page.
  * The map[] array maps LinkSectionId-1 to the per-section post-PE-relayout
  * RVA, so we can compute each reloc's site_rva = section_rva + (orig
  * write_vaddr - orig section_vaddr).
  *
  * Layout per page:
  *   u32 page_rva
  *   u32 size_of_block (8 + n_entries*2, padded to a multiple of 4)
  *   u16 entries[]: (type << 12) | (offset & 0xfff)
  *   optional trailing u16 = 0 (IMAGE_REL_BASED_ABSOLUTE) for u32 alignment */
 typedef struct CoffRelocEntry {
   u32 site_rva;
   u16 type;
   u16 pad;
 } CoffRelocEntry;
 
 static int coff_reloc_entry_cmp(const void* a, const void* b) {
   const CoffRelocEntry* ea = (const CoffRelocEntry*)a;
   const CoffRelocEntry* eb = (const CoffRelocEntry*)b;
   if (ea->site_rva < eb->site_rva) return -1;
   if (ea->site_rva > eb->site_rva) return 1;
   return 0;
 }
 
 static void coff_build_reloc_section(LinkImage* img,
                                      const CoffSection out[COFF_NBUCKETS],
                                      const CoffSecMap* map, CoffSection* reloc,
                                      const CoffRelocEntry* extras,
                                      u32 n_extras) {
   Heap* heap = img->heap;
   Compiler* c = img->c;
   u32 nrel = LinkRelocs_count(&img->relocs);
   CoffRelocEntry* entries = NULL;
   u32 nentries = 0;
   u32 cap = 0;
   u32 i;
 
   for (i = 0; i < nrel; ++i) {
     const LinkRelocApply* r = LinkRelocs_at(&img->relocs, i);
     const LinkSection* ls;
     u64 site_old_vaddr;
     u32 site_rva;
     u16 type;
     if (!coff_reloc_needs_base_reloc(r->kind)) continue;
     if (r->link_section_id == LINK_SEC_NONE) continue;
     ls = &img->sections[r->link_section_id - 1];
     /* r->write_vaddr is in the pre-relayout coordinate system (same as
      * ls->vaddr), so the offset into the section is stable.  Add the
      * containing bucket's final RVA to land at the image RVA. */
     site_old_vaddr = r->write_vaddr;
     u8 sb = map[ls->id - 1].bucket;
     site_rva = out[sb].rva + map[ls->id - 1].new_rva +
                (u32)(site_old_vaddr - ls->vaddr);
     if (r->kind == R_ABS64) {
       type = (u16)IMAGE_REL_BASED_DIR64;
     } else {
       type = (u16)IMAGE_REL_BASED_HIGHLOW;
     }
     if (nentries == cap) {
       (void)VEC_GROW(heap, entries, cap, nentries + 1u);
     }
     entries[nentries].site_rva = site_rva;
     entries[nentries].type = type;
     entries[nentries].pad = 0;
     ++nentries;
   }
   /* Append caller-supplied extras (TLS directory absolute-VA fields,
    * etc.). These are already site-RVAs in the final image. */
   for (i = 0; i < n_extras; ++i) {
     if (nentries == cap) {
       (void)VEC_GROW(heap, entries, cap, nentries + 1u);
     }
     entries[nentries] = extras[i];
     ++nentries;
   }
   if (nentries == 0) {
     reloc->bytes = NULL;
     reloc->size = 0;
     if (entries) heap->free(heap, entries, cap * sizeof(*entries));
     (void)c;
     return;
   }
   /* Sort entries by RVA so we can group runs sharing a 4-KiB page. */
   qsort(entries, nentries, sizeof(*entries), coff_reloc_entry_cmp);
 
   /* Two-pass: first compute the total size (so we can allocate the
    * blob exactly), then emit. */
   u32 blob_size = 0;
   u32 run_start = 0;
   while (run_start < nentries) {
     u32 page = entries[run_start].site_rva & ~0xfffu;
     u32 run_end = run_start;
     while (run_end < nentries &&
            (entries[run_end].site_rva & ~0xfffu) == page) {
       ++run_end;
     }
     u32 n = run_end - run_start;
     u32 block = COFF_BASE_RELOCATION_SIZE + n * 2u;
     block = (u32)ALIGN_UP((u64)block, 4ull);
     blob_size += block;
     run_start = run_end;
   }
   reloc->bytes = (u8*)heap->alloc(heap, blob_size, 4);
   if (!reloc->bytes && blob_size)
     compiler_panic(c, SRCLOC_NONE, "link_emit_coff: oom on .reloc blob");
   memset(reloc->bytes, 0, blob_size);
   reloc->size = blob_size;
   /* Stash allocation size for free path. */
   reloc->size_raw = blob_size;
 
   u32 cursor = 0;
   run_start = 0;
   while (run_start < nentries) {
     u32 page = entries[run_start].site_rva & ~0xfffu;
     u32 run_end = run_start;
     while (run_end < nentries &&
            (entries[run_end].site_rva & ~0xfffu) == page) {
       ++run_end;
     }
     u32 n = run_end - run_start;
     u32 raw_size = COFF_BASE_RELOCATION_SIZE + n * 2u;
     u32 block = (u32)ALIGN_UP((u64)raw_size, 4ull);
     u8* p = reloc->bytes + cursor;
     wr_u32_le(p, page);
     wr_u32_le(p + 4, block);
     u32 k;
     for (k = 0; k < n; ++k) {
       u16 entry = (u16)(((u16)entries[run_start + k].type << 12) |
                         (entries[run_start + k].site_rva & 0xfffu));
       wr_u16_le(p + 8 + k * 2u, entry);
     }
     /* Optional trailing pad: a single IMAGE_REL_BASED_ABSOLUTE (0). */
     if (block > raw_size) {
       wr_u16_le(p + 8 + n * 2u, 0);
     }
     cursor += block;
     run_start = run_end;
   }
   heap->free(heap, entries, cap * sizeof(*entries));
 }
 
 /* Patch each LinkRelocApply against the PE-relayout coordinates and
  * apply.  `bucket_bytes[bucket]` gives the writable buffer for that
  * bucket; the per-section delta in map[] turns the old in-section
  * offsets into bucket-local offsets.
  *
  * Imported targets (LinkSymbol.imported == 1) have no vaddr of their
  * own — instead the .idata pass populated `iv->by_sym[id-1]` with the
  * function stub's vaddr (for callable imports) or the IAT slot's
  * vaddr (for data imports).  This is the spot where that table is
  * consulted in lieu of the symbol's own zero vaddr. */
 static void coff_apply_all_relocs(LinkImage* img,
                                   const CoffSection out[COFF_NBUCKETS],
                                   const CoffSecMap* map,
                                   const CoffImportVaddr* iv) {
   Compiler* c = img->c;
   u32 i;
   u64 img_base = PE_IMAGE_BASE;
   u32 nrel = LinkRelocs_count(&img->relocs);
   for (i = 0; i < nrel; ++i) {
     LinkRelocApply* r = LinkRelocs_at(&img->relocs, i);
     const LinkSymbol* tgt = LinkSyms_at(&img->syms, r->target - 1);
     const LinkSection* sec;
     const LinkSection* tgt_sec;
     u64 S, P;
     u8* P_bytes;
     u8 bucket;
     u32 site_off_in_sec;
     u32 site_bucket_off;
     if (r->link_section_id == LINK_SEC_NONE) continue;
     sec = &img->sections[r->link_section_id - 1];
     bucket = map[sec->id - 1].bucket;
     if (!out[bucket].has_file_bytes || !out[bucket].bytes) {
       /* Shouldn't happen — .bss has no relocations. */
       continue;
     }
     site_off_in_sec = (u32)(r->write_vaddr - sec->vaddr);
     site_bucket_off = map[sec->id - 1].new_rva + site_off_in_sec;
     P_bytes = out[bucket].bytes + site_bucket_off;
     /* P = ImageBase + bucket_rva + map[].new_rva + site_off_in_sec
      * — i.e. the final runtime address of the patch site. */
     P = img_base + (u64)out[bucket].rva + (u64)map[sec->id - 1].new_rva +
         site_off_in_sec;
 
     /* Resolve S: target symbol's new image-relative address.  Look up
      * the LinkSection that contains the symbol's original vaddr, then
      * apply that section's delta. */
     if (tgt->imported) {
       /* IAT-routed: stub vaddr (functions) / slot vaddr (data). */
       if (!iv || iv->by_sym[r->target - 1u] == 0)
         compiler_panic(c, SRCLOC_NONE,
                        "link_emit_coff: imported target lacks IAT slot");
       S = iv->by_sym[r->target - 1u];
     } else if (tgt->kind == SK_ABS) {
       S = tgt->vaddr;
     } else if (tgt->defined) {
       tgt_sec = coff_symbol_section(img, tgt);
       if (!tgt_sec) {
         compiler_panic(c, SRCLOC_NONE,
                        "link_emit_coff: symbol vaddr 0x%llx has no "
                        "containing section",
                        (unsigned long long)tgt->vaddr);
       }
       u8 tb = map[tgt_sec->id - 1].bucket;
       u64 sym_off = tgt->vaddr - tgt_sec->vaddr;
       S = img_base + (u64)out[tb].rva + (u64)map[tgt_sec->id - 1].new_rva +
           sym_off;
     } else {
       /* Undef and not imported — shouldn't survive resolve_undefs. */
       compiler_panic(c, SRCLOC_NONE,
                      "link_emit_coff: unresolved non-imported symbol");
     }
     /* COFF-only section-relative kinds: the SECREL value is the
      * symbol's offset from the start of its containing output section
      * (PE bucket), and SECTION is the 1-based PE section index.
      * link_reloc_apply only sees S and P, so we patch these inline
      * before delegating common kinds. */
     if (r->kind == R_COFF_SECREL || r->kind == R_COFF_SECTION ||
         r->kind == R_COFF_AARCH64_SECREL_LOW12A ||
         r->kind == R_COFF_AARCH64_SECREL_HIGH12A ||
         r->kind == R_COFF_AARCH64_SECREL_LOW12L) {
       if (!tgt->defined || tgt->kind == SK_ABS) {
         compiler_panic(c, SRCLOC_NONE,
                        "link_emit_coff: COFF SECREL/SECTION requires a "
                        "defined section-bound target symbol");
       }
       u8 tb = map[tgt_sec->id - 1].bucket;
       u64 sym_off_in_bucket =
           (u64)map[tgt_sec->id - 1].new_rva + (tgt->vaddr - tgt_sec->vaddr);
       if (r->kind == R_COFF_SECREL) {
         u64 v = sym_off_in_bucket + (u64)r->addend;
         wr_u32_le(P_bytes, (u32)(v & 0xffffffffu));
       } else if (r->kind == R_COFF_SECTION) {
         /* PE section indices are 1-based; buckets are 0-based, so add 1. */
         wr_u16_le(P_bytes, (u16)((tb + 1u) & 0xffffu));
       } else if (r->kind == R_COFF_AARCH64_SECREL_LOW12L) {
         /* AArch64 SECREL_LOW12L: patch a load/store unsigned-immediate
          * imm12. The encoded immediate is scaled by the access width, which
          * is recoverable from the instruction's size/opc bits. */
         u64 v = sym_off_in_bucket + (u64)r->addend;
         u64 lo12 = v & 0xfffu;
         u32 instr = rd_u32_le(P_bytes);
         u32 sz = (instr >> 30) & 0x3u;
         u32 shift = (((instr >> 26) & 0x1u) && ((instr >> 23) & 0x1u)) ? 4u : sz;
         u32 align_mask = (1u << shift) - 1u;
         if (lo12 & align_mask)
           compiler_panic(c, SRCLOC_NONE,
                          "link_emit_coff: ARM64 SECREL_LOW12L misaligned "
                          "offset 0x%llx for scale %u",
                          (unsigned long long)lo12, (unsigned)shift);
         instr = (instr & ~(0xfffu << 10)) |
                 ((u32)((lo12 >> shift) & 0xfffu) << 10);
         wr_u32_le(P_bytes, instr);
       } else {
         /* AArch64 SECREL_{LOW,HIGH}12A: patch the imm12 field of an
          * existing ADD-imm12 instruction. LOW12A = bits [11:0] of the
          * SECREL; HIGH12A = bits [23:12]. The instruction's sh bit was
          * already set by the codegen (0 for LOW, 1 for HIGH). */
         u64 v = sym_off_in_bucket + (u64)r->addend;
         u32 imm12 = (r->kind == R_COFF_AARCH64_SECREL_HIGH12A)
                         ? (u32)((v >> 12) & 0xfffu)
                         : (u32)(v & 0xfffu);
         u32 instr = rd_u32_le(P_bytes);
         instr = (instr & ~(0xfffu << 10)) | (imm12 << 10);
         wr_u32_le(P_bytes, instr);
       }
       continue;
     }
     if (r->kind == R_COFF_ADDR32NB) {
       u64 inline_addend = rd_u32_le(P_bytes);
       u64 v = (S - img_base) + inline_addend + (u64)r->addend;
       wr_u32_le(P_bytes, (u32)(v & 0xffffffffu));
       continue;
     }
     if (tgt->bind == SB_WEAK && tgt->kind == SK_ABS && tgt->vaddr == 0) {
       /* AArch64 cannot generally ADRP from a PE image base down to absolute
        * NULL. Materialize the weak-undef address as zero directly; the paired
        * ADD low-12 relocation is already a no-op. */
       if (r->kind == R_AARCH64_ADR_PREL_PG_HI21 ||
           r->kind == R_AARCH64_ADR_PREL_PG_HI21_NC) {
         u32 instr = rd_u32_le(P_bytes);
         u32 rd = instr & 0x1fu;
         wr_u32_le(P_bytes, 0xd2800000u | rd); /* movz Xrd, #0 */
         continue;
       }
       if (r->kind == R_AARCH64_ADD_ABS_LO12_NC) continue;
     }
     link_reloc_apply(c, r->kind, P_bytes, S, r->addend, P);
   }
 }
 
 /* ---- header marshalling ----
  *
  * Each helper streams its on-disk shape to the writer field-by-field;
  * we avoid sizeof(struct) on the packed PE wire types since they carry
  * implicit-padding hazards on hosts that disagree with #pragma pack(1)
  * defaults. */
 
 static void coff_write_dos_stub(Writer* w) {
   u8 buf[PE_DOS_HDR_SIZE];
   memset(buf, 0, sizeof(buf));
   /* e_magic ("MZ") + e_lfanew (offset of PE signature).  All other
    * legacy fields zero. */
   buf[0] = (u8)(IMAGE_DOS_SIGNATURE & 0xffu);
   buf[1] = (u8)((IMAGE_DOS_SIGNATURE >> 8) & 0xffu);
   wr_u32_le(buf + 0x3c, PE_DOS_E_LFANEW);
   kit_writer_write(w, buf, sizeof(buf));
 }
 
 static void coff_write_file_header(Writer* w, u16 machine, u16 nsec,
                                    u16 characteristics) {
   coff_wr_u16(w, machine);
   coff_wr_u16(w, nsec);
   coff_wr_u32(w, 0u);                   /* TimeDateStamp */
   coff_wr_u32(w, 0u);                   /* PointerToSymbolTable */
   coff_wr_u32(w, 0u);                   /* NumberOfSymbols */
   coff_wr_u16(w, (u16)PE_OPT_HDR_SIZE); /* SizeOfOptionalHeader */
   coff_wr_u16(w, characteristics);
 }
 
 static void coff_write_optional_header(Writer* w, u32 entry_rva,
                                        const CoffSection out[COFF_NBUCKETS],
                                        u32 headers_size_padded, u32 image_size,
                                        int dynamic_base, u16 subsystem,
                                        const CoffImportTable* it,
                                        const CoffTlsLayout* tls) {
   /* Standard fields. */
   coff_wr_u16(w, IMAGE_NT_OPTIONAL_HDR64_MAGIC);
   coff_wr_u8(w, PE_LINKER_MAJOR);
   coff_wr_u8(w, PE_LINKER_MINOR);
   /* SizeOfCode / SizeOfInitializedData / SizeOfUninitializedData. */
   u32 size_code =
       out[COFF_BUCKET_TEXT].in_image ? out[COFF_BUCKET_TEXT].size_raw : 0;
   u32 size_init =
       (out[COFF_BUCKET_RDATA].in_image ? out[COFF_BUCKET_RDATA].size_raw : 0) +
       (out[COFF_BUCKET_IDATA].in_image ? out[COFF_BUCKET_IDATA].size_raw : 0) +
       (out[COFF_BUCKET_DATA].in_image ? out[COFF_BUCKET_DATA].size_raw : 0) +
       (out[COFF_BUCKET_TLS].in_image ? out[COFF_BUCKET_TLS].size_raw : 0) +
       (out[COFF_BUCKET_PDATA].in_image ? out[COFF_BUCKET_PDATA].size_raw : 0) +
       (out[COFF_BUCKET_RELOC].in_image ? out[COFF_BUCKET_RELOC].size_raw : 0);
   u32 size_uninit =
       out[COFF_BUCKET_BSS].in_image ? out[COFF_BUCKET_BSS].size : 0;
   coff_wr_u32(w, size_code);
   coff_wr_u32(w, size_init);
   coff_wr_u32(w, size_uninit);
   coff_wr_u32(w, entry_rva);
   coff_wr_u32(w,
               out[COFF_BUCKET_TEXT].in_image ? out[COFF_BUCKET_TEXT].rva : 0);
   /* Windows-specific fields. */
   coff_wr_u64(w, PE_IMAGE_BASE);
   coff_wr_u32(w, PE_SECTION_ALIGNMENT);
   coff_wr_u32(w, PE_FILE_ALIGNMENT);
   coff_wr_u16(w, PE_OS_MAJOR);
   coff_wr_u16(w, PE_OS_MINOR);
   coff_wr_u16(w, 0u); /* MajorImageVersion */
   coff_wr_u16(w, 0u); /* MinorImageVersion */
   coff_wr_u16(w, PE_SUBSYS_MAJOR);
   coff_wr_u16(w, PE_SUBSYS_MINOR);
   coff_wr_u32(w, 0u); /* Win32VersionValue */
   coff_wr_u32(w, image_size);
   coff_wr_u32(w, headers_size_padded);
   coff_wr_u32(w, 0u); /* CheckSum */
   coff_wr_u16(w, subsystem ? subsystem : IMAGE_SUBSYSTEM_WINDOWS_CUI);
   coff_wr_u16(
       w, (u16)(PE_DLL_CHARS_BASE | (dynamic_base ? PE_DLL_CHARS_ASLR : 0)));
   coff_wr_u64(w, PE_STACK_RESERVE);
   coff_wr_u64(w, PE_STACK_COMMIT);
   coff_wr_u64(w, PE_HEAP_RESERVE);
   coff_wr_u64(w, PE_HEAP_COMMIT);
   coff_wr_u32(w, 0u); /* LoaderFlags */
   coff_wr_u32(w, (u32)PE_NUM_DATA_DIRS);
   /* DataDirectory[16].  Populated entries:
    *   [1]  IMPORT    — descriptor table RVA + total descriptor bytes
    *   [3]  EXCEPTION — .pdata runtime-function table
    *   [5]  BASERELOC — when PIE and .reloc is in the image
    *   [12] IAT       — first IAT block RVA + sum of per-DLL IAT sizes
    * Everything else stays zero. */
   u32 i;
   int has_idata = it && it->nimports > 0 && out[COFF_BUCKET_IDATA].in_image;
   for (i = 0; i < PE_NUM_DATA_DIRS; ++i) {
     if (i == IMAGE_DIRECTORY_ENTRY_IMPORT && has_idata) {
       coff_wr_u32(w, out[COFF_BUCKET_IDATA].rva + it->desc_off);
       coff_wr_u32(w, it->desc_size);
     } else if (i == IMAGE_DIRECTORY_ENTRY_EXCEPTION &&
                out[COFF_BUCKET_PDATA].in_image) {
       coff_wr_u32(w, out[COFF_BUCKET_PDATA].rva);
       coff_wr_u32(w, out[COFF_BUCKET_PDATA].size);
     } else if (i == IMAGE_DIRECTORY_ENTRY_IAT && has_idata) {
       coff_wr_u32(w, out[COFF_BUCKET_IDATA].rva + it->iat_base);
       coff_wr_u32(w, it->iat_total);
     } else if (i == IMAGE_DIRECTORY_ENTRY_BASERELOC && dynamic_base &&
                out[COFF_BUCKET_RELOC].in_image) {
       coff_wr_u32(w, out[COFF_BUCKET_RELOC].rva);
       coff_wr_u32(w, out[COFF_BUCKET_RELOC].size);
     } else if (i == IMAGE_DIRECTORY_ENTRY_TLS && tls && tls->present) {
       coff_wr_u32(w, out[COFF_BUCKET_RDATA].rva + tls->dir_rdata_off);
       coff_wr_u32(w, COFF_TLS_DIRECTORY64_SIZE);
     } else {
       coff_wr_u32(w, 0u);
       coff_wr_u32(w, 0u);
     }
   }
 }
 
 static void coff_write_section_header(Writer* w, const char* name, u32 vsize,
                                       u32 rva, u32 size_raw, u32 file_offset,
                                       u32 characteristics) {
   u8 nm[8] = {0, 0, 0, 0, 0, 0, 0, 0};
   size_t n = slice_from_cstr(name).len;
   if (n > 8) n = 8;
   memcpy(nm, name, n);
   kit_writer_write(w, nm, 8);
   coff_wr_u32(w, vsize);
   coff_wr_u32(w, rva);
   coff_wr_u32(w, size_raw);
   coff_wr_u32(w, file_offset);
   coff_wr_u32(w, 0u); /* PointerToRelocations */
   coff_wr_u32(w, 0u); /* PointerToLinenumbers */
   coff_wr_u16(w, 0u); /* NumberOfRelocations */
   coff_wr_u16(w, 0u); /* NumberOfLinenumbers */
   coff_wr_u32(w, characteristics);
 }
 
 /* ---- main entry ---- */
 
 void link_emit_coff(LinkImage* img, Writer* w) {
   Heap* heap = img->heap;
   Compiler* c = img->c;
   u16 machine = coff_machine_or_panic(c);
   if (img->entry_sym == LINK_SYM_NONE)
     compiler_panic(c, SRCLOC_NONE, "link_emit_coff: no resolved entry symbol");
 
   /* ---- pass 1: build buckets + per-section delta map ---- */
   CoffSection out[COFF_NBUCKETS];
   CoffSecMap* map = (CoffSecMap*)heap->alloc(
       heap, sizeof(CoffSecMap) * (img->nsections + 1u), _Alignof(CoffSecMap));
   if (!map && img->nsections)
     compiler_panic(c, SRCLOC_NONE, "link_emit_coff: oom on section map");
   memset(map, 0, sizeof(CoffSecMap) * (img->nsections + 1u));
 
   /* coff_build_buckets stashes per-bucket allocation caps in size_raw;
    * we read them back into a local before size_raw is recomputed by
    * coff_assign_layout so the cleanup path can free with the right
    * size. */
   coff_build_buckets(img, out, map);
   /* coff_build_buckets stashes per-bucket allocation caps in size_raw
    * (the only bucket field we own for the duration of layout); read
    * them out before coff_assign_layout overwrites the field.  .reloc
    * and .idata aren't touched by coff_build_buckets — their caps are
    * filled in below once coff_build_reloc_section / coff_emit_idata
    * run. */
   u32 bucket_caps[COFF_NBUCKETS];
   u32 b;
   for (b = 0; b < COFF_NBUCKETS; ++b) bucket_caps[b] = out[b].size_raw;
 
   /* ---- pass 1b: collect imports and reserve .idata + .text stubs ----
    *
    * Builds the per-DLL / per-import layout and appends one IAT-routing
    * stub per imported function to the .text bucket.  The .idata bucket
    * size is set here (so it counts in nsec); the stub vaddrs and
    * IAT-slot vaddrs are finalised after coff_assign_layout. */
   CoffImportTable imports;
   int have_imports = coff_collect_imports(img, &imports);
   if (have_imports) {
     coff_plan_idata_layout(img, &imports);
     coff_append_stubs(img, &imports, &out[COFF_BUCKET_TEXT],
                       &bucket_caps[COFF_BUCKET_TEXT]);
     /* Reserve the .idata bucket size so coff_assign_layout / nsec
      * accounting sees it.  Actual bytes are written by coff_emit_idata
      * once the bucket RVA is known. */
     out[COFF_BUCKET_IDATA].size = imports.idata_size;
   }
 
   /* ---- pass 1c: plan the TLS directory record ----
    *
    * If any SF_TLS sections survived, reserve 40 bytes at the tail of
    * .rdata for the IMAGE_TLS_DIRECTORY64. Bytes are zeroed now and
    * filled in by coff_emit_tls_dir once the bucket RVAs are final. */
   CoffTlsLayout tls;
   coff_plan_tls_layout(img, out, &bucket_caps[COFF_BUCKET_RDATA], &tls);
 
   /* ---- pass 2: decide whether .reloc will be in the image ----
    *
    * The headers' file size (and therefore every section's file
    * offset) depends on the section-table entry count, so we need to
    * commit to "is .reloc emitted?" before laying out file offsets.
    * .reloc lights up iff at least one absolute VA reloc points into a kept
    * section, OR a TLS directory is emitted (its VA fields need base-relocs).
    * ARM64 Windows rejects fixed images (/dynamicbase:no), and x64 Windows
    * accepts ASLR images by default, so PE images advertise DYNAMIC_BASE when
    * this table is present instead of tying the table to the generic ELF/Mach-O
    * img->pie flag. */
   int emit_reloc = 0;
   {
     u32 i;
     u32 nrel = LinkRelocs_count(&img->relocs);
     for (i = 0; i < nrel; ++i) {
       const LinkRelocApply* r = LinkRelocs_at(&img->relocs, i);
       if (!coff_reloc_needs_base_reloc(r->kind)) continue;
       if (r->link_section_id == LINK_SEC_NONE) continue;
       emit_reloc = 1;
       break;
     }
     if (!emit_reloc && tls.present) emit_reloc = 1;
   }
 
   u32 nsec = 0;
   for (b = 0; b < COFF_NBUCKETS; ++b) {
     if (b == COFF_BUCKET_RELOC) {
       if (emit_reloc) ++nsec; /* tentative; size set below */
       continue;
     }
     if (out[b].size) ++nsec;
   }
   u32 headers_size_unpadded = PE_DOS_HDR_SIZE + PE_SIG_SIZE + PE_FILE_HDR_SIZE +
                               PE_OPT_HDR_SIZE + nsec * PE_SECTION_HDR_SIZE;
   u32 headers_size_padded =
       (u32)ALIGN_UP((u64)headers_size_unpadded, (u64)PE_FILE_ALIGNMENT);
 
   /* First layout pass: fixes RVAs / file offsets for buckets that
    * already have a finalised size (.text, .rdata, .idata, .data, .bss).
    * .reloc's RVA is provisional — it depends on .reloc's own size,
    * which is still 0 at this point. */
   (void)coff_assign_layout(out, headers_size_padded, PE_FIRST_SECTION_RVA);
 
   /* ---- pass 2b: emit .idata bytes + per-arch IAT stubs ----
    *
    * The .idata bucket's RVA is final after the first assign_layout;
    * stubs need it (the indirect-jump displacement targets an IAT slot)
    * and .idata's own descriptor / ILT / IAT records all carry RVAs.
    * coff_import_vaddr_build builds the per-LinkSymId override table
    * that apply_all_relocs consults in place of the (zero) symbol
    * vaddr for imported targets. */
   CoffImportVaddr import_vaddr;
   memset(&import_vaddr, 0, sizeof(import_vaddr));
   if (have_imports) {
     coff_emit_idata(img, &imports, out, &bucket_caps[COFF_BUCKET_IDATA]);
     coff_emit_stubs(img, &imports, out);
     coff_import_vaddr_build(img, &imports, out, &import_vaddr);
   }
 
   /* Write the TLS directory bytes now that bucket RVAs are final. */
   coff_emit_tls_dir(img, out, map, &tls);
 
   /* ---- pass 3: build .reloc using the now-final bucket RVAs ----
    *
    * coff_build_reloc_section reads out[bucket].rva indirectly via
    * map[].new_rva + (write_vaddr - sec->vaddr) → site offset within
    * the bucket; the absolute site_rva is bucket.rva + that offset.
    * Patch site RVAs are page-quantised in the emitted blob, so this
    * is the spot where the bucket RVAs need to be already final.
    *
    * TLS directory's four absolute-VA fields ride into the entries via
    * the `extras` array — they aren't ordinary symbol relocations, so
    * they don't show up in img->relocs. */
   if (emit_reloc) {
     CoffRelocEntry tls_extras[4];
     u32 n_tls_extras = 0;
     if (tls.present) {
       u32 dir_rva = out[COFF_BUCKET_RDATA].rva + tls.dir_rdata_off;
       static const u32 field_offs[4] = {
           COFF_TLSDIR_OFF_START_ADDR,
           COFF_TLSDIR_OFF_END_ADDR,
           COFF_TLSDIR_OFF_INDEX_ADDR,
           COFF_TLSDIR_OFF_CALLBACKS,
       };
       u32 k;
       for (k = 0; k < 4; ++k) {
         if (field_offs[k] == COFF_TLSDIR_OFF_CALLBACKS && !tls.callbacks_sym)
           continue;
         tls_extras[n_tls_extras].site_rva = dir_rva + field_offs[k];
         tls_extras[n_tls_extras].type = (u16)IMAGE_REL_BASED_DIR64;
         tls_extras[n_tls_extras].pad = 0;
         ++n_tls_extras;
       }
     }
     coff_build_reloc_section(img, out, map, &out[COFF_BUCKET_RELOC], tls_extras,
                              n_tls_extras);
     bucket_caps[COFF_BUCKET_RELOC] = out[COFF_BUCKET_RELOC].size_raw;
     /* size_raw was stashed by build; assign_layout below recomputes it
      * as the FileAlignment-padded length. */
     (void)coff_assign_layout(out, headers_size_padded, PE_FIRST_SECTION_RVA);
   }
 
   /* `_tls_used` is the public mingw/PE name for the TLS directory
    * record. Keep it in lockstep with the optional-header TLS data
    * directory, rather than leaving references bound to mingw's tlssup.o
    * placeholder record. */
   coff_define_tls_used(img, out, &tls);
 
   /* ---- pass 4: resolve entry symbol's PE RVA ----
    *
    * Done before apply so the optional-header field has its final
    * value. */
   const LinkSymbol* entry_sym = LinkSyms_at(&img->syms, img->entry_sym - 1);
   if (!entry_sym->defined || entry_sym->kind == SK_ABS)
     compiler_panic(c, SRCLOC_NONE,
                    "link_emit_coff: entry symbol is not a defined "
                    "image-relative function");
   const LinkSection* entry_sec = coff_section_at(img, entry_sym->vaddr);
   if (!entry_sec)
     compiler_panic(c, SRCLOC_NONE,
                    "link_emit_coff: entry symbol has no containing "
                    "section");
   u8 entry_bucket = map[entry_sec->id - 1].bucket;
   u32 entry_rva = out[entry_bucket].rva + map[entry_sec->id - 1].new_rva +
                   (u32)(entry_sym->vaddr - entry_sec->vaddr);
 
   /* ---- pass 5: apply all relocations into bucket bytes ---- */
   coff_apply_all_relocs(img, out, map, have_imports ? &import_vaddr : NULL);
 
   /* ---- pass 6: compute SizeOfImage (in-memory size) ---- */
   u32 image_size = 0;
   for (b = 0; b < COFF_NBUCKETS; ++b) {
     if (!out[b].in_image) continue;
     u32 end = out[b].rva + out[b].size;
     if (end > image_size) image_size = end;
   }
   image_size = (u32)ALIGN_UP((u64)image_size, (u64)PE_SECTION_ALIGNMENT);
 
   /* ---- pass 7: write everything ---- */
   u16 file_chars = IMAGE_FILE_EXECUTABLE_IMAGE | IMAGE_FILE_LARGE_ADDRESS_AWARE;
   int dynamic_base = out[COFF_BUCKET_RELOC].in_image;
   if (!dynamic_base) {
     file_chars |= IMAGE_FILE_RELOCS_STRIPPED;
   }
 
   coff_write_dos_stub(w);
   /* PE signature. */
   coff_wr_u32(w, IMAGE_NT_SIGNATURE);
   coff_write_file_header(w, machine, (u16)nsec, file_chars);
   u16 subsystem = img->linker ? img->linker->pe_subsystem : 0;
   coff_write_optional_header(w, entry_rva, out, headers_size_padded, image_size,
                              dynamic_base, subsystem,
                              have_imports ? &imports : NULL, &tls);
 
   /* Section table. */
   for (b = 0; b < COFF_NBUCKETS; ++b) {
     if (!out[b].in_image) continue;
     coff_write_section_header(w, out[b].name, out[b].size, out[b].rva,
                               out[b].size_raw, out[b].file_offset,
                               out[b].characteristics);
   }
 
   /* Pad to first section's file offset. */
   u64 cur = (u64)headers_size_unpadded;
   u64 first_file_off = headers_size_padded;
   if (cur < first_file_off) {
     coff_write_zeroes(w, first_file_off - cur);
     cur = first_file_off;
   }
 
   /* Section bodies. */
   for (b = 0; b < COFF_NBUCKETS; ++b) {
     if (!out[b].in_image) continue;
     if (!out[b].has_file_bytes) continue;
     if (cur < out[b].file_offset) {
       coff_write_zeroes(w, out[b].file_offset - cur);
       cur = out[b].file_offset;
     }
     kit_writer_write(w, out[b].bytes, out[b].size);
     cur += out[b].size;
     if (out[b].size_raw > out[b].size) {
       coff_write_zeroes(w, out[b].size_raw - out[b].size);
       cur += out[b].size_raw - out[b].size;
     }
   }
 
   /* ---- cleanup ---- */
   for (b = 0; b < COFF_NBUCKETS; ++b) {
     if (out[b].bytes) heap->free(heap, out[b].bytes, bucket_caps[b]);
   }
   heap->free(heap, map, sizeof(CoffSecMap) * (img->nsections + 1u));
   if (have_imports) {
     coff_import_vaddr_free(img, &import_vaddr);
     coff_imports_free(img, &imports);
   }
 }