kit

obj.h (56092B)

---

 #ifndef KIT_OBJ_H
 #define KIT_OBJ_H
 
 #include "core/buf.h"
 #include "core/core.h"
 
 /* Forward decl: the synthetic-input hook (obj_format_synth_inputs) takes a
  * Linker but obj.h must not pull in the link subsystem. Defined in
  * src/link; only used here as an opaque pointer. */
 typedef struct Linker Linker;
 
 typedef enum SecKind {
   SEC_TEXT,
   SEC_RODATA,
   SEC_DATA,
   SEC_BSS,
   SEC_DEBUG,
   SEC_OTHER,
 } SecKind;
 
 typedef enum SecFlag {
   SF_EXEC = 1u << 0,
   SF_WRITE = 1u << 1,
   SF_ALLOC = 1u << 2,
   SF_TLS = 1u << 3,
   SF_MERGE = 1u << 4,
   SF_STRINGS = 1u << 5,
   SF_GROUP = 1u << 6,
   SF_LINK_ORDER = 1u << 7,
   SF_RETAIN = 1u << 8, /* SHF_GNU_RETAIN: do not GC even if unreferenced */
 } SecFlag;
 
 typedef enum SecSem {
   SSEM_PROGBITS,
   SSEM_NOBITS,
   SSEM_SYMTAB,
   SSEM_STRTAB,
   SSEM_RELA,
   SSEM_REL,
   SSEM_NOTE,
   SSEM_INIT_ARRAY,
   SSEM_FINI_ARRAY,
   SSEM_PREINIT_ARRAY,
   SSEM_GROUP,
   SSEM_WASM_CUSTOM,
 } SecSem;
 
 typedef enum SymBind {
   SB_LOCAL,
   SB_GLOBAL,
   SB_WEAK,
 } SymBind;
 
 typedef enum SymVis {
   SV_DEFAULT,
   SV_HIDDEN,
   SV_PROTECTED,
   SV_INTERNAL,
 } SymVis;
 
 typedef enum SymKind {
   SK_UNDEF,
   SK_FUNC,
   SK_OBJ,
   SK_SECTION,
   SK_FILE,
   SK_COMMON,
   SK_TLS,
   SK_ABS,
   /* Defined symbol with no specific type — assembly labels, AArch64
    * mapping symbols (`$x`, `$d`). Distinct from SK_UNDEF (undefined
    * external) so the linker keeps definedness keyed on SK_UNDEF. */
   SK_NOTYPE,
   /* GNU IFUNC: a function whose implementation is selected at runtime
    * by a resolver. Round-trips as STT_GNU_IFUNC (10); presence forces
    * EI_OSABI=ELFOSABI_GNU on emit. */
   SK_IFUNC,
 } SymKind;
 
 typedef enum ObjExtKind {
   OBJ_EXT_NONE,
   OBJ_EXT_ELF,
   OBJ_EXT_COFF,
   OBJ_EXT_MACHO,
   OBJ_EXT_WASM,
   /* Wasm-target frontend-supplied import descriptors keyed by symbol name.
    * Populated by lang/c when an extern declaration carries
    * __attribute__((import_module(...), import_name(...))); consumed by the
    * wasm backend when promoting undefined function symbols to imports. */
   OBJ_EXT_WASM_IMPORTS,
 } ObjExtKind;
 
 typedef u32 ObjSecId;
 #define OBJ_SEC_NONE 0u
 
 typedef u32 ObjGroupId;
 #define OBJ_GROUP_NONE 0u
 
 /* Per-ObjBuilder symbol handle. Object files own their symbol namespace:
  * local/static symbols, section symbols, file symbols, unnamed labels, common
  * definitions, and external references are all represented by ObjSymId values
  * scoped to one builder. 0 is reserved as "none". */
 typedef u32 ObjSymId;
 #define OBJ_SYM_NONE 0u
 
 typedef u32 ObjAtomId;
 #define OBJ_ATOM_NONE 0u
 
 typedef enum ObjAtomFlag {
   OBJ_ATOM_RETAIN = 1u << 0,
 } ObjAtomFlag;
 
 typedef enum RelocKind {
   R_NONE = 0,
   R_ABS32,
   R_ABS64,
   R_REL32,
   R_REL64,
   R_PC32,
   R_PC64,
   R_GOT32,
   R_PLT32,
   /* Neutral data-word kinds completing the ABS/PREL/TPOFF families. */
   R_ABS8,
   R_ABS16,
   R_PREL16,
   /* Internal-only: a raw 64-bit local-exec tpoff written into a TLS GOT
    * slot by link_emit_internal_tpoff64.  Never appears on the wire.
    * x86_64 stores variant-II (X - tls_memsz); AArch64 and RISC-V store
    * variant-I ((X - tls_vaddr) + TCB).  Byte encoding is identical on
    * all three arches: a plain 64-bit little-endian write. */
   R_TPOFF64,
   R_AARCH64_ADR_GOT_PAGE,
   R_AARCH64_LD64_GOT_LO12_NC,
   R_AARCH64_JUMP26,
   R_AARCH64_CALL26,
   R_AARCH64_CONDBR19,
   R_AARCH64_TSTBR14,
   R_AARCH64_LD_PREL_LO19,
   R_AARCH64_ADR_PREL_LO21,
   /* MCEmitter-only function-local label address materialization. The fixup
    * patches a fixed 16-byte sequence as either ADR+B+literal when in range,
    * or LDR-literal+B+relocated-literal when the ADR range is exceeded. */
   R_AARCH64_INTRA_LABEL_ADDR,
   R_AARCH64_ADR_PREL_PG_HI21,
   R_AARCH64_ADR_PREL_PG_HI21_NC,
   R_AARCH64_ADD_ABS_LO12_NC,
   R_AARCH64_LDST8_ABS_LO12_NC,
   R_AARCH64_LDST16_ABS_LO12_NC,
   R_AARCH64_LDST32_ABS_LO12_NC,
   R_AARCH64_LDST64_ABS_LO12_NC,
   R_AARCH64_LDST128_ABS_LO12_NC,
   /* AArch64 Mach-O TLV (thread-local variable) descriptor access. The
    * compiler emits these to reference a TLV descriptor in
    * __DATA,__thread_vars; the linker routes both through a synthetic
    * __DATA,__thread_ptrs slot (analogous to __got for non-TLV externs).
    *
    *   adrp x0, _var@TLVPPAGE         ; TLVP_LOAD_PAGE21
    *   ldr  x0, [x0, _var@TLVPPAGEOFF]; TLVP_LOAD_PAGEOFF12  -> descriptor
    *   ldr  x1, [x0]                  ; thunk (filled by dyld)
    *   blr  x1                        ; thunk(x0=descriptor) -> x0 = TLV addr
    *
    * Encoding-wise PAGE21 is ADRP-form and PAGEOFF12 is a 64-bit-LDR
    * lo12 (scale=3). The linker rewrites S to the matching __thread_ptrs
    * slot's vaddr before applying. */
   R_AARCH64_TLVP_LOAD_PAGE21,
   R_AARCH64_TLVP_LOAD_PAGEOFF12,
   /* AArch64 TLS Local-Exec model. */
   R_AARCH64_TLSLE_ADD_TPREL_HI12,
   R_AARCH64_TLSLE_ADD_TPREL_LO12,
   R_AARCH64_TLSLE_ADD_TPREL_LO12_NC,
   R_AARCH64_TLSLE_LDST8_TPREL_LO12,
   R_AARCH64_TLSLE_LDST8_TPREL_LO12_NC,
   R_AARCH64_TLSLE_LDST16_TPREL_LO12,
   R_AARCH64_TLSLE_LDST16_TPREL_LO12_NC,
   R_AARCH64_TLSLE_LDST32_TPREL_LO12,
   R_AARCH64_TLSLE_LDST32_TPREL_LO12_NC,
   R_AARCH64_TLSLE_LDST64_TPREL_LO12,
   R_AARCH64_TLSLE_LDST64_TPREL_LO12_NC,
   /* Dynamic-only relocs: emitted into .rela.dyn / .rela.plt of an
    * ET_DYN/ET_EXEC output and processed by the runtime loader. They
    * never appear in ET_REL inputs from a compiler; the linker may
    * synthesize them during dynamic-exe / shared-lib emit, and the
    * reader recognizes them when it walks an ET_DYN's .rela.* sections
    * (currently only used for symbol-name extraction, not applied). */
   R_AARCH64_GLOB_DAT,
   R_AARCH64_JUMP_SLOT,
   R_AARCH64_RELATIVE,
   R_AARCH64_COPY,
   /* x86_64 reloc kinds. Most map directly to the existing R_ABS and
    * R_PC entries; the few here are the x86_64-only encodings (8-bit
    * displacements, GOT/PLT, dynamic linker-only entries). */
   R_X64_PC8,
   R_X64_32S,
   R_X64_PLT32,
   R_X64_GOTPCREL,
   R_X64_GOTPCRELX,
   R_X64_REX_GOTPCRELX,
   R_X64_GOTPC32,
   R_X64_GOTOFF64,
   R_X64_TPOFF32,
   R_X64_DTPOFF32,
   R_X64_DTPMOD64,
   R_X64_DTPOFF64,
   R_X64_TLSGD,
   R_X64_TLSLD,
   R_X64_GOTTPOFF,
   R_X64_GLOB_DAT,
   R_X64_JUMP_SLOT,
   R_X64_RELATIVE,
   R_X64_COPY,
   /* Mach-O x86_64 TLV access: RIP-relative disp32 in `movq sym@TLVP(%rip),
    * %rdi` addressing the __thread_ptrs slot that holds the TLV descriptor
    * address (the descriptor-model peer of arm64's TLVP_LOAD_PAGE21/PAGEOFF12;
    * maps to X86_64_RELOC_TLV). Distinct from the ELF R_X64_TPOFF32 Local-Exec
    * kind. */
   R_X64_TLV,
   R_RV_HI20,
   R_RV_LO12_I,
   R_RV_LO12_S,
   R_RV_BRANCH,
   R_RV_JAL,
   R_RV_CALL,
   R_RV_PCREL_HI20,
   R_RV_PCREL_LO12_I,
   R_RV_PCREL_LO12_S,
   /* Intra-section label address materialization via an AUIPC+ADDI pair.
    * Used only by MCEmitter intra-section label fixups (CGTarget
    * load_label_addr). Width is 8 bytes, covering both instructions; the
    * fixup site is the AUIPC and the disp is the label byte offset
    * relative to the AUIPC site. */
   R_RV_INTRA_AUIPC_ADDI,
   R_RV_GOT_HI20,
   /* TLS Initial-Exec: %tls_ie_pcrel_hi(sym). Paired with R_RV_PCREL_LO12_I
    * on the follow-on ld. The GOT entry holds (&sym - tp); the AUIPC/ld
    * pair materializes that offset into a register so the caller adds tp. */
   R_RV_TLS_GOT_HI20,
   R_RV_TPREL_HI20,
   R_RV_TPREL_LO12_I,
   R_RV_TPREL_LO12_S,
   R_RV_TPREL_ADD,
   R_ADD8,
   R_ADD16,
   R_ADD32,
   R_ADD64,
   R_SUB8,
   R_SUB16,
   R_SUB32,
   R_SUB64,
   R_RV_ALIGN,
   R_RV_RVC_BRANCH,
   R_RV_RVC_JUMP,
   R_RV_RELAX,
   R_SUB6,
   R_SET6,
   R_SET_ULEB128,
   R_SUB_ULEB128,
   R_WASM_FUNCIDX,
   R_WASM_TABLEIDX,
   R_WASM_MEMOFS,
   R_WASM_TYPEIDX,
   /* COFF/PE-only reloc kinds — section-relative fixups used by Windows
    * TLS Local-Exec lowering and debug info. SECREL = 32-bit offset
    * from the start of the containing section. SECTION = 16-bit section
    * index (1-based). Both arch-independent on the kit side; the
    * per-arch translators map to IMAGE_REL_{AMD64,ARM64}_SECREL/SECTION. */
   R_COFF_SECREL,
   R_COFF_SECTION,
   /* AArch64 Windows TLS access uses an ADD-imm12-pair to materialize a
    * 24-bit SECREL value into a register:
    *   add  xd, xd, #:secrel_hi12:sym, lsl #12   ; HIGH12A bits [23:12]
    *   add  xd, xd, #:secrel_lo12:sym            ; LOW12A  bits [11:0]
    * The instruction at the patch site already has sh=1 (HIGH) or sh=0
    * (LOW) preset by the codegen; the linker only patches the imm12
    * field at bits [21:10]. NC variants ("no carry / no overflow check"
    * in PE terminology) mean the high bits of SECREL above 24 are
    * discarded — fine for any .tls section under 16 MiB. */
   R_COFF_AARCH64_SECREL_LOW12A,
   R_COFF_AARCH64_SECREL_HIGH12A,
   /* AArch64 TLS Initial-Exec. The ADRP/LDR pair loads the symbol's
    * TP-relative offset from a GOT slot; the linker fills that slot with a
    * 64-bit tpoff (R_TPOFF64) and redirects these to the slot, so they apply
    * exactly like the regular ADR_GOT_PAGE / LD64_GOT_LO12_NC pair.
    * Appended at the enum tail so the public KIT_RELOC_* values (object.h)
    * keep their pinned numbering. */
   R_AARCH64_TLSIE_ADR_GOTTPREL_PAGE21,
   R_AARCH64_TLSIE_LD64_GOTTPREL_LO12_NC,
   /* COFF ADDR32NB: 32-bit image-relative RVA (S + A - ImageBase), used by
    * PE exception tables and other image metadata. */
   R_COFF_ADDR32NB,
   /* AArch64 Mach-O POINTER_TO_GOT: a 32-bit PC-relative data relocation that
    * materializes the address of a GOT entry. Used by Apple toolchains in
    * unwind metadata such as __eh_frame. */
   R_AARCH64_POINTER_TO_GOT,
   /* AArch64 ELF TLSDESC static relocations. The ELF executable linker
    * currently accepts these only for defined local TLS and relaxes the
    * four-instruction descriptor call sequence to materialize a TP-relative
    * local-exec offset. Dynamic TLSDESC descriptors are intentionally not
    * represented yet. */
   R_AARCH64_TLSDESC_ADR_PAGE21,
   R_AARCH64_TLSDESC_LD64_LO12,
   R_AARCH64_TLSDESC_ADD_LO12,
   R_AARCH64_TLSDESC_CALL,
   /* RISC-V TLS General-Dynamic / Local-Dynamic access. Executable links
    * currently relax it to local-exec when the TLS symbol is defined in the
    * image. Appended at the enum tail to keep existing public values stable. */
   R_RV_TLS_GD_HI20,
   /* AArch64 Windows SECREL low-12 load/store form. Appended at the enum tail
    * to keep existing public relocation values stable. */
   R_COFF_AARCH64_SECREL_LOW12L,
   /* 32-bit ARM (Thumb-2, M-profile) ELF relocations. Static-only, Thumb-only:
    * BL never relaxes to BLX (everything is Thumb on Cortex-M). The split-
    * immediate byte patcher lives in src/arch/arm32/reloc.c. Data words reuse
    * the neutral R_ABS32/R_REL32/R_ABS16/R_ABS8 kinds. Appended at the enum
    * tail to keep existing public relocation values stable. */
   R_ARM_THM_CALL,         /* BL/BLX (T1): 25-bit {S,I1,I2,imm10,imm11}, +-16MB */
   R_ARM_THM_JUMP24,       /* B.W (T4): same 25-bit field */
   R_ARM_THM_JUMP19,       /* B<cond>.W (T3): 21-bit {S,J2,J1,imm6,imm11}, +-1MB */
   R_ARM_THM_MOVW_ABS_NC,  /* MOVW (T3): imm16 = (S+A)[15:0], imm4:i:imm3:imm8 */
   R_ARM_THM_MOVT_ABS,     /* MOVT (T3): imm16 = (S+A)[31:16] */
   R_ARM_THM_MOVW_PREL_NC, /* PC-rel MOVW (PIC; follow-on) */
   R_ARM_THM_MOVT_PREL,    /* PC-rel MOVT (PIC; follow-on) */
   R_ARM_TLS_LE32,         /* TLS local-exec: S + A - tp (variant I; follow-on) */
 } RelocKind;
 
 typedef struct Section {
   Sym name;
   u16 kind;
   u16 flags;
   u16 sem;      /* SecSem */
   u16 ext_kind; /* ObjExtKind */
   u32 align;
   u32 entsize;
   ObjSecId link;       /* section index or OBJ_SEC_NONE */
   u32 info;            /* section-format dependent, typed by sem/ext_kind */
   ObjGroupId group_id; /* OBJ_GROUP_NONE if not in a COMDAT/group */
   u32 bss_size;        /* nonzero only for SEC_BSS */
   u64 addr;            /* load vaddr (sh_addr); 0 for relocatable inputs */
   /* Format-specific raw section type (ELF sh_type, COFF Characteristics
    * subfield, etc.).  Set by .o readers when the canonical SecSem
    * mapping is lossy — e.g., SHT_LLVM_ADDRSIG (0x6FFF4C03) and
    * SHT_ARM_ATTRIBUTES (0x70000003) collapse to SSEM_PROGBITS but
    * the emitter must write back the original value to round-trip.
    * Zero means "no override; derive from sem". */
   u32 ext_type;
   u32 ext_flags; /* same idea for format-specific sh_flags bits
                     not represented in SecFlag (e.g. SHF_EXCLUDE) */
   /* Tombstone for strip/objcopy-style mutations. Set by
    * obj_section_remove; honored by obj_sweep_dead and the emitters.
    * Iterators / direct ID-based access on the builder must consult this
    * bit and skip removed entries. */
   u8 removed;
   Buf bytes;
 } Section;
 
 typedef struct Reloc {
   ObjSecId section_id;
   u32 offset;
   u16 kind;
   u8 has_explicit_addend;
   u8 pair; /* paired/following relocation, format-specific */
   /* Tombstone set by obj_sweep_dead when the reloc points at a removed
    * section or symbol. Lives in the slack between `pair` and `sym` — no
    * struct-size change. */
   u8 removed;
   ObjSymId sym;
   i64 addend;
 } Reloc;
 
 typedef struct ObjSym {
   Sym name;
   u16 bind;
   u16 kind;
   u8 vis;
   u8 ext_kind;
   u16 flags;
   ObjSecId section_id; /* OBJ_SEC_NONE if undef */
   u64 value;           /* offset within section, or absolute */
   u64 size;
   u64 common_align; /* nonzero for SK_COMMON */
   /* Lifecycle gate for spurious-UNDEF pruning at .o emit time.
    *
    * The C frontend mints an ObjSym for every `extern` declaration it
    * parses (so a header like <stdio.h> creates 50+ ObjSyms in one TU).
    * Most of those are never the target of any relocation. `referenced`
    * tracks that distinction: obj_reloc_ex sets it on the target, and
    * the file emitters (elf_emit / macho_emit) drop entries that are
    * still SK_UNDEF + (SB_GLOBAL|SB_WEAK) + !referenced from the output
    * symbol table.
    *
    * Definitions never need the gate — kind != SK_UNDEF for those, so
    * the filter never considers them. Readers (elf_read, macho_read)
    * mark every read-in symbol referenced=1 so a roundtrip preserves
    * UNDEFs that came from another tool's output. */
   u8 referenced;
   /* Tombstone for strip/objcopy. Set by obj_symbol_remove or cascaded
    * by obj_sweep_dead when this symbol is defined in a removed section.
    * The UNDEF-prune predicate (was: !referenced && SK_UNDEF && global/weak)
    * is also folded into the sweep, so emit-time symbol loops only need to
    * check `removed`. */
   u8 removed;
   /* This symbol names an address subordinate to the preceding content unit
    * rather than starting a separately collectible/reorderable atom. Mach-O
    * writes this semantic as N_ALT_ENTRY; other formats may ignore it. */
   u8 atom_subordinate;
 } ObjSym;
 
 typedef struct ObjGroup {
   Sym name;
   ObjSymId signature;
   ObjSecId* sections;
   u32 nsections;
   u32 flags;
   /* Tombstone — set by obj_group_remove, or cascaded by obj_sweep_dead
    * when every member section has been removed (or the signature symbol
    * has been removed). */
   u8 removed;
 } ObjGroup;
 
 typedef struct ObjAtom {
   ObjSecId section_id;
   u32 offset;
   u32 size;
   ObjSymId signature;
   u32 flags;
   u8 removed;
 } ObjAtom;
 
 /* The single concrete in-memory object representation.
  * Written by MCEmitter/CGTarget (during compile) or by an .o reader (during
  * link). Read by file emitters, the linker (file and JIT), and objdump.
  *
  * Invariant: post-finalize state is identical in shape to what an .o reader
  * would produce from a written-out object — so consumers don't care which
  * path produced it.
  *
  * Lifecycle gates:
  *   1. MCEmitter/CGTarget (or a .o reader) issues writes.
  *   2. cgtarget_finalize must be called before any debug_emit or read access on
  *      the builder. At -O2 it flushes lowered code into sections.
  *   3. debug_emit (if -g) writes .debug_* sections.
  *   4. obj_finalize closes the builder: computes flat section offsets, applies
  *      pending fixups within sections, and freezes the read-side view.
  *      No further writes are permitted afterward.
  *   5. File emitters and the linker consume via the read API.
  *
  * The handle type itself is the public KitObjBuilder, aliased to ObjBuilder
  * inside libkit (see src/core/core.h). */
 
 ObjBuilder* obj_new(Compiler*);
 void obj_free(ObjBuilder*);
 
 /* The owning Compiler; needed by consumers (e.g. kit_disasm_iter_new)
  * that take a bare ObjBuilder and still must pool_str() symbol names
  * against the right pool. */
 Compiler* obj_compiler(const ObjBuilder*);
 
 /* Pre-size the symbol-name index for `n` incoming symbols (object readers know
  * the count from the symtab header). Skips the resize cascade when ingesting a
  * symbol-heavy object. No-op if already large enough; order-preserving. */
 void obj_reserve_symbols(ObjBuilder*, u32 n);
 
 /* ---- write side (MCEmitter/CGTarget and .o readers) ---- */
 ObjSecId obj_section(ObjBuilder*, Sym name, SecKind, u16 flags, u32 align);
 ObjSecId obj_section_ex(ObjBuilder*, Sym name, SecKind, SecSem, u16 flags,
                         u32 align, u32 entsize, u32 link, u32 info);
 void obj_section_set_flags(ObjBuilder*, ObjSecId, u16 flags);
 void obj_section_set_entsize(ObjBuilder*, ObjSecId, u32 entsize);
 void obj_section_set_align(ObjBuilder*, ObjSecId, u32 align);
 void obj_section_set_group(ObjBuilder*, ObjSecId, ObjGroupId);
 void obj_section_set_link_info(ObjBuilder*, ObjSecId, ObjSecId link, u32 info);
 void obj_section_set_addr(ObjBuilder*, ObjSecId, u64 addr);
 /* Set format-specific raw sh_type/sh_flags overrides (see Section.ext_type
  * comment).  Zero ext_type means "no override". */
 void obj_section_set_ext(ObjBuilder*, ObjSecId, ObjExtKind, u32 ext_type,
                          u32 ext_flags);
 void obj_write(ObjBuilder*, ObjSecId section_id, const void* data, size_t n);
 /* Resolve a section's byte buffer for direct emit. Returns NULL for the
  * OBJ_SEC_NONE sentinel, an unknown id, or a NOBITS/.bss section (which stores
  * only a size, not bytes — callers must route those through obj_write so the
  * bss_size accounting runs). The returned pointer is stable: SegVec elements do
  * not move, so callers may cache it until the next set_section. */
 Buf* obj_section_bytes(ObjBuilder*, ObjSecId section_id);
 u8* obj_reserve(ObjBuilder*, ObjSecId section_id, size_t n);
 void obj_reserve_bss(ObjBuilder*, ObjSecId section_id, u32 size, u32 align);
 /* Pad `section_id` to `align`, returning the resulting offset.  For
  * PROGBITS sections this writes zero bytes; for NOBITS it bumps
  * bss_size.  Callers that share a section across multiple symbols use
  * this to ensure each placement starts at the symbol's required
  * alignment, since dedup of obj_section means a placement isn't
  * automatically aligned just because the section's own align is set. */
 u32 obj_align_to(ObjBuilder*, ObjSecId section_id, u32 align);
 u32 obj_pos(ObjBuilder*, ObjSecId section_id);
 void obj_patch(ObjBuilder*, ObjSecId section_id, u32 ofs, const void* data,
                size_t n);
 
 ObjSymId obj_symbol(ObjBuilder*, Sym name, SymBind, SymKind,
                     ObjSecId section_id, u64 value, u64 size);
 ObjSymId obj_symbol_ex(ObjBuilder*, Sym name, SymBind, SymVis, SymKind,
                        ObjSecId section_id, u64 value, u64 size,
                        u64 common_align);
 /* Allocate a stable symbol id for data that may be discarded before emission.
  * The returned symbol is tombstoned and not entered in the name index; callers
  * must publish it with obj_symbol_define_live if the data is actually emitted.
  */
 ObjSymId obj_symbol_defer(ObjBuilder*, Sym name, SymBind, SymVis, SymKind,
                           u64 size);
 ObjSymId obj_symbol_find(ObjBuilder*, Sym name);
 /* obj_symbol_ex creates a symbol; obj_symbol_define fills in the
  * (section_id, value, size) fields of an already-created symbol. The pair
  * supports forward references: an undefined ObjSymId is created when first
  * needed for a relocation, and defined later when its definition is emitted. */
 void obj_symbol_define(ObjBuilder*, ObjSymId, ObjSecId section_id, u64 value,
                        u64 size);
 void obj_symbol_define_live(ObjBuilder*, ObjSymId, ObjSecId section_id,
                             u64 value, u64 size);
 
 void obj_reloc(ObjBuilder*, ObjSecId section_id, u32 offset, RelocKind,
                ObjSymId sym, i64 addend);
 void obj_reloc_ex(ObjBuilder*, ObjSecId section_id, u32 offset, RelocKind,
                   ObjSymId sym, i64 addend, int explicit_addend, int pair);
 
 /* Force ObjSym::referenced = 1 on the named symbol. obj_reloc_ex calls this
  * automatically; the readers (elf_read / macho_read) call it on every
  * ingested symbol so a roundtrip preserves UNDEFs that another tool
  * emitted into the input. */
 void obj_sym_mark_referenced(ObjBuilder*, ObjSymId);
 void obj_sym_set_referenced(ObjBuilder*, ObjSymId, int referenced);
 
 ObjAtomId obj_atom_define(ObjBuilder*, ObjSecId section_id, u32 offset,
                           u32 size, ObjSymId signature, u32 flags);
 
 ObjGroupId obj_group(ObjBuilder*, Sym name, ObjSymId signature, u32 flags);
 void obj_group_add_section(ObjBuilder*, ObjGroupId group_id,
                            ObjSecId section_id);
 
 void obj_finalize(ObjBuilder*);
 
 /* ---- post-finalize mutators (strip / objcopy support) ----
  *
  * Mutators flip per-entry fields and / or `removed` tombstones. Cascading
  * cleanup (drop relocs against removed sections, etc.) is deferred to
  * obj_sweep_dead, which the emitters call automatically. Mutators are
  * cheap individual field writes; they do not re-index or compact storage,
  * so ObjSecId / ObjSymId / ObjGroupId remain stable.
  *
  * No-ops when given OBJ_SEC_NONE / OBJ_SYM_NONE / OBJ_GROUP_NONE, and
  * silently ignore ids that are out of range or already removed (the
  * driver tools call these in bulk and benefit from idempotency). */
 void obj_section_remove(ObjBuilder*, ObjSecId);
 void obj_symbol_remove(ObjBuilder*, ObjSymId);
 void obj_group_remove(ObjBuilder*, ObjGroupId);
 void obj_section_rename(ObjBuilder*, ObjSecId, Sym new_name);
 void obj_symbol_rename(ObjBuilder*, ObjSymId, Sym new_name);
 void obj_symbol_set_bind(ObjBuilder*, ObjSymId, SymBind);
 void obj_symbol_set_vis(ObjBuilder*, ObjSymId, SymVis);
 /* Replace `section_id`'s contents wholesale with `n` bytes from `data`.
  * Resets bss_size (so a former NOBITS section gains real bytes) and
  * preserves the section's other attributes (name, kind, flags, align).
  * Existing relocations against the section are kept — caller is
  * responsible for issuing obj_symbol_remove on any defined symbols whose
  * (value, size) no longer fits, etc. */
 void obj_section_replace_bytes(ObjBuilder*, ObjSecId, const u8* data, size_t n);
 
 /* Tombstone-driven consistency sweep. Called by each file-format emitter
  * at the top of emit; consumers that walk a builder by raw section/symbol/
  * reloc/group ID after sweep must respect the `removed` bit on each entry.
  *
  * Does the following passes:
  *   1. Cascade: any symbol defined in a removed section becomes removed.
  *   2. UNDEF prune: any non-referenced SK_UNDEF global/weak becomes removed
  *      (folds the historical "spurious extern from a header" filter).
  *   3. Reloc cleanup: any reloc whose containing section, defining section,
  *      or target symbol is removed becomes removed.
  *   4. Group compaction: each group's section list is filtered in place to
  *      drop removed members; a group whose list empties out (or whose
  *      signature symbol has been removed) is itself marked removed.
  *   5. Section link cleanup: Section.link cleared if it points at a
  *      removed section.
  *
  * Idempotent — safe to call multiple times. On a never-mutated builder
  * only pass 2 has any effect. */
 void obj_sweep_dead(ObjBuilder*);
 
 /* Format-specific ELF e_flags (per-arch ABI bits, e.g. EF_RISCV_RVC |
  * EF_RISCV_FLOAT_ABI_DOUBLE on RV64). Set by read_elf during input
  * parsing; consumed by emit_elf for round-trip. The setter records
  * a presence bit so emit_elf can distinguish "preserve from input"
  * from "no input — synthesize per-arch default". */
 void obj_set_elf_e_flags(ObjBuilder*, u32 e_flags);
 int obj_get_elf_e_flags(const ObjBuilder*, u32* out);
 
 /* COFF short-import shim annotation. Set by read_coff when the input
  * is a Microsoft "short import" record (Sig1=0, Sig2=0xFFFF) found
  * inside a .lib archive member: the ObjBuilder synthesizes the
  * imported symbol(s) the long-form import object would have provided,
  * and stores the providing DLL name here so the archive-ingestion
  * layer (Phase 4.3) can reclassify the resulting LinkInput as a
  * DSO with this name as the soname. Unset (returns 0 from the
  * getter) on every other input. The setter records a presence bit
  * the same way obj_set_elf_e_flags does. */
 void obj_set_coff_import_dll(ObjBuilder*, Sym dll_name);
 int obj_get_coff_import_dll(const ObjBuilder*, Sym* out);
 /* COFF short-import IMPORT NAME override: the name the loader resolves in the
  * DLL when the short-import NameType makes it differ from the local symbol
  * name (NOPREFIX/UNDECORATE strip decoration; EXPORTAS carries an explicit
  * export name). Set by read_coff_short_import; consumed by the COFF
  * import-table synthesis for the PE hint/name-table entry. The local symbol
  * keeps its own name so kit's references still resolve. Unset on inputs whose
  * import name equals the symbol name. */
 void obj_set_coff_import_name(ObjBuilder*, Sym import_name);
 int obj_get_coff_import_name(const ObjBuilder*, Sym* out);
 
 /* COFF WEAK_EXTERNAL alias: symbol `sym` is an alias for the symbol named
  * `target` (the aux record's fall-back/default symbol). Recorded by read_coff
  * for genuine alias declarations (IMAGE_WEAK_EXTERN_SEARCH_ALIAS) so the linker
  * can resolve the weak symbol to its target by name — e.g. mingw x86_64's
  * `_setjmp` aliasing `__intrinsic_setjmp`, a redirection the single-underscore
  * naming heuristic can't derive. The getter returns 0 when `sym` has no
  * recorded alias (the common case). See src/link/link_resolve.c. */
 void obj_set_weak_alias(ObjBuilder*, ObjSymId sym, Sym target);
 Sym obj_get_weak_alias(const ObjBuilder*, ObjSymId sym);
 /* Enumerate the recorded weak-external aliases (for building a cross-input
  * name->target map at link time). Count is 0 on inputs that carry none. */
 u32 obj_weak_alias_count(const ObjBuilder*);
 int obj_weak_alias_at(const ObjBuilder*, u32 i, ObjSymId* sym_out,
                       Sym* target_out);
 
 /* Per-symbol format-specific flag bits.  ObjSym.flags is otherwise
  * unused; readers stash format-specific attribute bits there so the
  * matching emitter can re-apply them.  Today this is Mach-O n_desc
  * pass-through (N_NO_DEAD_STRIP, etc.) — bits the canonical
  * ObjSym.bind/vis/kind triple doesn't model.  ELF callers are free
  * to use the same field for their own pass-through; the contract is
  * "bits go in / same bits come out", not a shared semantic. */
 void obj_symbol_set_flags(ObjBuilder*, ObjSymId, u16 flags);
 void obj_symbol_set_atom_subordinate(ObjBuilder*, ObjSymId, int subordinate);
 
 /* ---- read side (linker, file emitters, objdump) ---- */
 u32 obj_section_count(const ObjBuilder*);
 const Section* obj_section_get(const ObjBuilder*, ObjSecId id);
 u32 obj_reloc_count(const ObjBuilder*, ObjSecId section_id);
 u32 obj_reloc_total(const ObjBuilder*);
 const Reloc* obj_reloc_at(const ObjBuilder*, u32 idx); /* 0..total-1 */
 /* The global indices of section_id's live relocs, ascending (the order
  * obj_reloc_at expects), via a cached per-section index — O(1) lookup instead
  * of rescanning the flat table. *out_len gets the count (may be 0 -> NULL). */
 const u32* obj_reloc_section(const ObjBuilder*, ObjSecId section_id,
                              u32* out_len);
 
 /* Diagnostic spelling for a RelocKind. The returned pointer is a static
  * literal that mirrors the enum identifier without the R_ prefix (e.g.
  * R_RV_CALL -> "RV_CALL", R_AARCH64_CALL26 -> "AARCH64_CALL26"). NULL is
  * never returned; unknown kinds collapse to "UNKNOWN". */
 const char* reloc_kind_name(RelocKind);
 const ObjSym* obj_symbol_get(const ObjBuilder*, ObjSymId);
 u32 obj_atom_count(const ObjBuilder*);
 const ObjAtom* obj_atom_get(const ObjBuilder*, ObjAtomId);
 int obj_section_has_atoms(const ObjBuilder*, ObjSecId);
 ObjAtomId obj_atom_find(const ObjBuilder*, ObjSecId section_id, u32 offset);
 ObjAtomId obj_atom_find_symbol(const ObjBuilder*, ObjSymId);
 u32 obj_group_count(const ObjBuilder*);
 const ObjGroup* obj_group_get(const ObjBuilder*, ObjGroupId id);
 
 /* Symbol iteration: ObjSymId is scoped to this builder, but callers should not
  * assume dense contiguous ids or direct indexing. The builder may store symbols
  * in segments internally; use the cursor.
  *
  * The iterator is raw — it visits every symbol slot including those whose
  * `removed` tombstone is set. Callers that want post-sweep semantics must
  * check ObjSym::removed themselves. (Consistent with Section.removed and
  * Reloc.removed: tombstones live as a per-entry field, not behind the
  * iterator.) */
 typedef struct ObjSymIter ObjSymIter;
 typedef struct ObjSymEntry {
   ObjSymId id;
   const ObjSym* sym;
 } ObjSymEntry;
 ObjSymIter* obj_symiter_new(const ObjBuilder*);
 int obj_symiter_next(ObjSymIter*, ObjSymEntry* out); /* returns 0 at end */
 void obj_symiter_free(ObjSymIter*);
 
 /* Group iteration: peer of obj_symiter for groups (COMDAT and friends).
  * Same segmented-storage caveat — use the cursor, don't index directly.
  * Like obj_symiter, this is raw: tombstoned groups are still returned;
  * callers consult ObjGroup::removed. */
 typedef struct ObjGroupIter ObjGroupIter;
 typedef struct ObjGroupEntry {
   ObjGroupId id;
   const ObjGroup* group;
 } ObjGroupEntry;
 ObjGroupIter* obj_groupiter_new(const ObjBuilder*);
 int obj_groupiter_next(ObjGroupIter*, ObjGroupEntry* out); /* 0 at end */
 void obj_groupiter_free(ObjGroupIter*);
 
 /* Writer is the public KitWriter type aliased to Writer inside libkit
  * (see src/core/core.h). The streaming API lives in <kit/core.h> as
  * kit_writer_*. */
 
 /* ---- format-aware canonical section names ----
  *
  * For sections the linker synthesizes (init/fini arrays, TLS template
  * sections), the spelling diverges across object formats: ELF uses
  * `.init_array` / `.tdata` / etc., Mach-O uses
  * `__DATA,__mod_init_func` / `__DATA,__thread_data` / etc.  These
  * helpers pick the right name for the active target.obj so the linker
  * doesn't carry per-format switches at every synthesis site.  ELF
  * returns the historical names; Mach-O / COFF panic until those
  * writers land. */
 Sym obj_secname_init_array(Compiler*);
 Sym obj_secname_fini_array(Compiler*);
 Sym obj_secname_preinit_array(Compiler*);
 Sym obj_secname_tdata(Compiler*);
 Sym obj_secname_tbss(Compiler*);
 
 /* DWARF debug-section name translation for Mach-O.
  *
  * kit carries DWARF sections under their ELF spelling (".debug_info")
  * internally; on Mach-O they live in the __DWARF segment with "__"-
  * prefixed section names ("__debug_info").  The transform drops the
  * leading '.', prepends "__", and truncates to Mach-O's 16-byte
  * `sectname` field — which reproduces the names Apple's toolchain uses
  * (e.g. ".debug_str_offsets" -> "__debug_str_offs").
  *
  * Writes the bare Mach-O section name (NUL-terminated, <=16 chars) into
  * `out` (>=17 bytes) and returns 1 when (`name`,`len`) is a ".debug_*"
  * section; returns 0 otherwise, leaving `out` untouched.  Shared by the
  * Mach-O writer (emit) and the DWARF reader (section lookup) so the two
  * agree on the truncated spelling. */
 int obj_macho_debug_sectname(const char* name, size_t len, char out[17]);
 
 /* Canonical Mach-O "segname,sectname" spelling for a SecKind, as a
  * NUL-terminated literal.  The single source of truth shared by the Mach-O
  * object writer (name_to_seg_sect) and the `cc -S` printer (asm_emit.c), so
  * the textual `.section` directive and the binary section header never drift:
  *   SEC_RODATA -> "__TEXT,__const", SEC_DATA -> "__DATA,__data",
  *   SEC_BSS -> "__DATA,__bss", SEC_TEXT -> "__TEXT,__text".
  * Returns NULL for kinds with no fixed canonical Mach-O home (SEC_OTHER /
  * SEC_DEBUG), which callers spell from the section's own name. */
 const char* obj_macho_canon_secname(SecKind kind);
 
 /* Inverse of obj_macho_canon_secname: classify a Mach-O native
  * "segname,sectname" spelling (e.g. "__TEXT,__text", "__DATA,__bss")
  * into a SecKind.  Used by a format-neutral reader / objdump path that
  * holds the on-disk Mach-O section name and wants the canonical kit
  * SecKind without re-deriving the per-segment rules at every call.
  * `name` / `len` are the comma-joined spelling.  Returns 1 and writes
  * *kind on a recognized spelling; returns 0 (leaving *kind untouched)
  * for an unrecognized name (caller treats as SEC_OTHER). */
 int obj_macho_seckind_for_secname(const char* name, size_t len, SecKind* kind);
 
 /* Translate a kit-internal (ELF-spelled) section name to its Mach-O
  * native spelling.  Generalizes obj_macho_debug_sectname: handles the
  * ".debug_*" -> "__DWARF,__debug_*" DWARF case and ".eh_frame" ->
  * "__TEXT,__eh_frame".  Writes the comma-joined "segname,sectname"
  * (NUL-terminated) into `out` (>= 40 bytes covers seg(16)+','+sect(16)+
  * NUL) and returns 1 when `name` is one of the recognized
  * format-divergent sections; returns 0 (leaving `out` untouched)
  * otherwise, so the caller falls back to its own spelling. */
 int obj_macho_native_secname(const char* name, size_t len, char out[40]);
 
 /* ---- thread-local storage emission ---------------------------------
  *
  * The frontend collects a `_Thread_local` definition's bytes (or marks
  * it BSS), alignment, and any pointer-init relocs, then calls
  * obj_define_tls to materialize the storage and bind the user-visible
  * symbol.  The obj layer owns the format split:
  *
  *   ELF   : `sym` is defined directly in `.tdata` / `.tbss`; the
  *           supplied relocs are applied at the same section/offset.
  *
  *   Mach-O: the data lives under a private `<name>$tlv$init` symbol in
  *           `__DATA,__thread_data` / `__DATA,__thread_bss`; `sym` is
  *           defined onto a 24-byte TLV *descriptor* in
  *           `__DATA,__thread_vars` whose three slots are
  *           [_tlv_bootstrap, 0, &init].  dyld rewrites slot[0] to a
  *           per-descriptor thunk and fills slot[1] with a pthread_key
  *           during image-load; the compiler's TLVP_LOAD_PAGE21 /
  *           PAGEOFF12 codegen sequence targets the descriptor.
  *
  * The `_tlv_bootstrap` undef extern is cached on the ObjBuilder so a
  * second TLV var in the same TU shares one symbol entry. */
 typedef struct ObjTlsReloc {
   u32 offset; /* within the data buffer */
   RelocKind kind;
   ObjSymId target;
   i64 addend;
 } ObjTlsReloc;
 
 void obj_define_tls(Compiler*, ObjBuilder*, ObjSymId sym, const u8* data,
                     u32 size, int has_nonzero_init, u32 align,
                     const ObjTlsReloc* relocs, u32 nrelocs);
 
 /* True when reads of `_Thread_local` storage go through a per-variable
  * descriptor + thunk call rather than a direct TP-relative offset.
  * Mach-O: yes (TLVP_LOAD_PAGE21 + thunk in descriptor[0]).
  * ELF: no (Local-Exec / Initial-Exec: `mrs tpidr_el0` + tprel offset). */
 int obj_format_tls_via_descriptor(const Compiler*);
 
 /* ---- format-aware codegen policy ----
  *
  * Backends consult these predicates instead of branching on
  * target.os / target.obj directly, so the OS/format knowledge stays
  * concentrated in src/obj/ and a future format lands as one case here
  * rather than fan-out in every CGTarget. */
 
 /* True when references to undefined external symbols must be
  * materialized via an indirection slot (GOT / non-lazy pointer)
  * rather than direct page+offset addressing. Mach-O: yes — dyld
  * binds dylib imports through __DATA,__got at runtime, and the
  * direct PAGE21/PAGEOFF12 fixups can't carry that binding. ELF
  * static link: no — the linker resolves SK_UNDEFs at link time and
  * patches the direct ADRP/ADD bytes in place. */
 int obj_format_extern_via_got(const Compiler*);
 
 /* True when `sym` must be reached via the GOT at the current site: the
  * format binds extern data through indirection
  * (obj_format_extern_via_got) AND the symbol is undefined in this
  * object (section_id == OBJ_SEC_NONE). Pure format/symbol policy with
  * no per-arch behavior — shared by every backend that emits GOT loads. */
 int obj_symbol_extern_via_got(const Compiler*, ObjBuilder*, ObjSymId);
 int obj_format_split_sections_as_atoms(const Compiler*);
 
 /* Apply the active object format's C-symbol mangling to `name` (a
  * NUL-terminated C string) and return the result interned in
  * `c->global`.  Mach-O prepends a single `_`; ELF / COFF / Wasm intern
  * verbatim.  Mirrors the on-disk policy that decl.c / cc.c emit, so
  * link-time and JIT-time lookups by source-level name find the symbol
  * regardless of target.  Mach-O temp buffer is allocated from
  * `c->ctx->heap`. */
 Sym obj_format_c_mangle(Compiler*, const char* name);
 
 /* Inverse of obj_format_c_mangle for diagnostic display: if `*name`
  * carries the active format's leading C-mangle byte, advance the
  * pointer past it and decrement `*len`.  No-op for formats with no
  * prefix.  Lets diagnostics print the source-level symbol name across
  * targets. */
 void obj_format_demangle_c(const Compiler*, const char** name, size_t* len);
 
 /* Default entry symbol name for a freshly created Linker on the active
  * object format: `_main` for Mach-O (LC_MAIN names main, dyld owns
  * startup), `_start` for ELF / COFF / Wasm (set by crt1.o).  Returned
  * as a NUL-terminated literal; the caller interns. */
 const char* obj_format_default_entry_name(const Compiler*);
 
 /* C source-level symbol prefix the active object format prepends on disk:
  * "_" for Mach-O, "" for ELF / COFF / Wasm.  The single source of truth
  * read by obj_format_c_mangle / obj_format_demangle_c; never NULL (a
  * format with no prefix returns ""). */
 const char* obj_format_c_label_prefix(const Compiler*);
 
 /* ---- thread-local storage model ----
  *
  * How compiled code reaches a `_Thread_local` on a given (format, OS):
  *   OBJ_TLS_ELF_LE          : direct TP-relative offset (ELF Local-Exec /
  *                             Initial-Exec): `mrs tpidr_el0` + tprel.
  *   OBJ_TLS_MACHO_DESCRIPTOR: per-variable descriptor + thunk call; the
  *                             TLVP reloc pair targets the descriptor.
  *   OBJ_TLS_WINDOWS_TEB     : Windows TEB-based access (SECREL into the
  *                             per-thread TLS block via the TEB). */
 typedef enum ObjTlsModel {
   OBJ_TLS_ELF_LE = 0,
   OBJ_TLS_MACHO_DESCRIPTOR = 1,
   OBJ_TLS_WINDOWS_TEB = 2,
 } ObjTlsModel;
 
 /* Returns how compiled code reaches a `_Thread_local` on the active
  * (format, OS): OBJ_TLS_WINDOWS_TEB for COFF, OBJ_TLS_MACHO_DESCRIPTOR
  * for Mach-O, OBJ_TLS_ELF_LE otherwise.  The single source of truth for
  * the TLS-access decision; obj_format_tls_via_descriptor is now a thin
  * wrapper over (model == OBJ_TLS_MACHO_DESCRIPTOR). */
 ObjTlsModel obj_format_tls_model(const Compiler*);
 
 /* In-process JIT: true when a reference to symbol `name` is dropped because the
  * format's TLS access idiom that materializes it is relaxed to in-image
  * addressing (COFF Windows `_tls_index`; none elsewhere). Beside
  * obj_format_tls_model as the TLS-mechanism authority. */
 int obj_format_jit_drops_symbol_ref(const Compiler*, Sym name);
 
 /* In-process JIT: true when an *undefined* reference to `name` is satisfied
  * internally by the JIT image and so needs no external definition: Mach-O
  * `__tlv_bootstrap` (descriptor slot[0] rewritten to the JIT thunk) and COFF
  * `_tls_index` (TLS access relaxed to in-image addressing). The single arbiter
  * for every JIT undef-accept site, keeping src/link free of pseudo-symbol
  * names. Broader than obj_format_jit_drops_symbol_ref, which gates reloc
  * dropping and covers only `_tls_index`. */
 int obj_format_jit_undef_internal(const Compiler*, Sym name);
 
 /* True when the active object format carries DWARF debug sections
  * file-only (not mapped into a loadable segment): ELF / Mach-O yes,
  * COFF no. */
 int obj_format_carries_file_only_debug(const Compiler*);
 
 /* True when the active object format builds its own static GOT /
  * non-lazy-pointer table at link time even for a static image:
  * Mach-O yes, else no. */
 int obj_format_builds_own_static_got(const Compiler*);
 
 /* True when the active object format can represent a KitCgSymFeat
  * `symfeat`.  Today this is the TLS-model axis: ELF / Mach-O can
  * represent every modeled TLS feature, COFF cannot (Windows TEB TLS
  * uses a different mechanism).  Non-TLS features return 1 for every
  * format.  `symfeat` is a KitCgSymFeat value (cast to int at the
  * boundary). */
 int obj_format_supports_symbol_feature(const Compiler*, int symfeat);
 
 /* True when the active object format pulls an archive member to satisfy a
  * *weak* undefined reference (PE/COFF COMDAT semantics).  COFF yes,
  * ELF / Mach-O no (they pull only for strong undefs). */
 int obj_format_weak_undef_pulls_archive_member(const Compiler*);
 
 /* True when the active object format resolves archive libraries as a global
  * fixed point rather than by strictly positional POSIX order. COFF yes,
  * ELF / Mach-O / Wasm no. */
 int obj_format_global_archive_fixpoint(const Compiler*);
 
 /* True when the active object format recovers weak-external / undefined
  * references via the mingw single-underscore alias convention (e.g.
  * `__set_app_type` <-> `_set_app_type`) during link symbol resolution.
  * COFF yes, ELF / Mach-O / Wasm no. */
 int obj_format_weak_extern_underscore_alias(const Compiler*);
 
 /* True when static-IFUNC resolution on the active target goes through a
  * `[__rela_iplt_start, __rela_iplt_end)` table of R_*_IRELATIVE relocs
  * (walked by FreeBSD's crt before main) rather than kit's ctor-based
  * __kit_ifunc_init path.  The one place the (os == FREEBSD && obj == ELF)
  * knowledge lives. */
 int obj_format_static_ifunc_via_rela_iplt(const Compiler*);
 
 /* The R_*_IRELATIVE resolver reloc wire type for the active target's
  * __rela_iplt table (paired with the predicate above), resolved through the
  * target object format so the generic iplt pass names no format literal.
  * Returns 0 when the format has no such reloc. */
 u32 obj_format_static_ifunc_irelative_type(const Compiler*);
 
 /* Format boundary-symbol classifier.  Asks the active object format
  * whether `name` is a symbol the format itself owns as a boundary /
  * synthetic global, and if so what SymKind it carries.  Returns 1 and
  * writes *symkind (a SymKind value) when the format owns `name`
  * (PE `__ImageBase` / `_tls_used` -> SK_ABS); returns 0 otherwise,
  * leaving *symkind untouched.  Lets generic link code classify boundary
  * symbols without a per-format switch. */
 int obj_format_boundary_sym_kind(const Compiler*, KitSlice name, int* symkind);
 
 /* Invoke the active object format's synthetic-input hook (if any) before
  * symbol resolution.  No-op for formats with no synthetic inputs.  The
  * hook builds and appends a synthetic LinkInput via Linker internals, so
  * it takes the Linker; declared here as the obj-side dispatch point.
  * (The COFF body is wired by T-LINK — see registry.c synth_inputs note.) */
 void obj_format_synth_inputs(const Compiler*, Linker*);
 
 /* ---- format-specific extension payload ----
  *
  * Generic object tables stay format-neutral. Format-specific module-level
  * metadata (today: only the in-progress Wasm module model) hangs off the
  * builder under an ObjExtKind tag. One payload per kind. ObjBuilder owns the
  * pointer's lifetime — obj_free invokes the registered free function. */
 typedef void (*ObjExtFreeFn)(Compiler*, void*);
 void obj_ext_set(ObjBuilder*, ObjExtKind, void* payload, ObjExtFreeFn);
 void* obj_ext_get(const ObjBuilder*, ObjExtKind);
 void obj_ext_clear(ObjBuilder*, ObjExtKind);
 
 /* ============================================================
  * Linked-image view (executables / shared objects)
  *
  * Relocatable inputs (ET_REL / MH_OBJECT / COFF .obj) have no image:
  * obj_image() returns NULL. The ET_EXEC / ET_DYN (and Mach-O / PE peer)
  * readers attach an ObjImage carrying the segment + dynamic view that the
  * section / symbol tables don't model. The section and symbol tables stay
  * populated where the format still carries them; the image is the extra
  * dimension. The builder owns the image; obj_free releases it.
  * ============================================================ */
 
 typedef enum ObjKind {
   OBJ_KIND_REL,  /* relocatable object — no image */
   OBJ_KIND_EXEC, /* executable */
   OBJ_KIND_DYN,  /* shared object / dylib / DLL */
   OBJ_KIND_CORE, /* core dump — detected, not parsed (reserved) */
 } ObjKind;
 
 enum { /* ObjSegment.perms bits */
        OBJ_SEG_X = 1u << 0,
        OBJ_SEG_W = 1u << 1,
        OBJ_SEG_R = 1u << 2
 };
 
 typedef struct ObjSegment {
   Sym name;      /* PT_* spelling / Mach-O segname, or 0 */
   u64 vaddr;     /* virtual address */
   u64 paddr;     /* physical/load address where present; else vaddr */
   u64 vsize;     /* size in memory */
   u64 file_off;  /* offset of segment contents in the file */
   u64 file_size; /* size on disk (< vsize when the segment carries bss) */
   u32 perms;     /* OBJ_SEG_R | _W | _X */
   u32 align;     /* power of two; 1 if none */
 } ObjSegment;
 
 typedef struct ObjImageDep {
   Sym name;           /* DT_NEEDED / imported DLL / dylib install-name */
   const Sym* imports; /* imported symbol names (PE/Mach-O); NULL for ELF */
   u32 nimports;
 } ObjImageDep;
 
 /* Dynamic-table symbol. Distinct from the .symtab entries in the Symbols
  * table — these come from .dynsym / dyld export trie / PE export table. */
 typedef struct ObjImageSym {
   Sym name;
   SymBind bind;
   SymKind kind;
   ObjSecId section; /* OBJ_SEC_NONE for undefined imports */
   u64 value;
   u64 size;
   /* ELF symbol-version name (interned) for a DSO export. 0 when the input
    * carries no versioning for this entry. `version_hidden` distinguishes
    * non-default compatibility aliases such as fstat@FBSD_1.0 from default
    * exports such as fstat@@FBSD_1.5. The linker uses this both to emit the
    * default requirement for plain imports and to satisfy explicit
    * name@VERSION imports without losing the requested version. */
   Sym version;
   u8 version_hidden;
   u8 pad[3];
 } ObjImageSym;
 
 /* Dynamic relocation (.rela.dyn / .rela.plt, dyld binds, PE base relocs).
  * References the dynamic symbol by interned name; the sym index is implicit
  * in the dynamic table and not preserved here. */
 typedef struct ObjImageReloc {
   ObjSecId section; /* OBJ_SEC_NONE when the file has no section table */
   u64 offset;
   Sym sym_name; /* 0 for symbol-less relative relocs */
   i64 addend;
   RelocKind kind;
 } ObjImageReloc;
 
 /* Raw, format-specific image field that doesn't fit the neutral model.
  * One flat triple list per image, in the spirit of the per-section
  * kit_obj_section_format_flags escape hatch: a neutral container with
  * per-format tag semantics (documented on the public KitObjImageRaw):
  *   PE   : data dirs  tag=0..15 (index), value=RVA, extra=size;
  *          subsystem  tag=KIT_OBJ_RAW_PE_SUBSYSTEM, value=u16;
  *          dllchars   tag=KIT_OBJ_RAW_PE_DLLCHARS,  value=u16
  *   ELF  : .dynamic   tag=d_tag, value=d_val, extra=0
  *   Mach-O: load cmds tag=cmd,   value=file offset, extra=cmdsize */
 typedef struct ObjImageRaw {
   u32 tag;
   u64 value;
   u64 extra;
 } ObjImageRaw;
 
 typedef struct ObjImage ObjImage; /* defined in obj.c */
 
 /* Accessor — NULL on relocatable inputs. */
 const ObjImage* obj_image(const ObjBuilder*);
 /* Lazily create (and return) the builder's image with the given kind.
  * Readers call this once they know the input is EXEC/DYN. Idempotent;
  * a second call updates the kind and returns the existing image. */
 ObjImage* obj_image_ensure(ObjBuilder*, ObjKind);
 
 /* Image scalar setters (readers). */
 void obj_image_set_entry(ObjImage*, u64 entry);
 void obj_image_set_base(ObjImage*, u64 image_base);
 void obj_image_set_interp(ObjImage*, Sym interp);
 void obj_image_set_soname(ObjImage*, Sym soname);
 
 /* Image table appenders (readers). Each copies its argument by value into a
  * builder-heap-owned vector. obj_image_add_dep additionally deep-copies the
  * ObjImageDep.imports[] name array into image-heap memory, so the reader may
  * pass a transient (scratch) array; the Sym values themselves must still be
  * interned in the compiler's global pool. */
 void obj_image_add_segment(ObjImage*, const ObjSegment*);
 void obj_image_add_dep(ObjImage*, const ObjImageDep*);
 void obj_image_add_rpath(ObjImage*, Sym rpath);
 void obj_image_add_dynsym(ObjImage*, const ObjImageSym*);
 void obj_image_add_dynreloc(ObjImage*, const ObjImageReloc*);
 /* Raw format-specific image fields (see ObjImageRaw). Copied by value. */
 void obj_image_add_raw(ObjImage*, const ObjImageRaw*);
 /* Undefined symbol names a DSO references (interned). The linker's
  * --gc-sections pass roots executable definitions of these so a shared
  * library's back-references (e.g. libc.so.7 → `environ` / `__progname`)
  * survive section GC. */
 void obj_image_add_undef(ObjImage*, Sym name);
 
 /* Image read-side queries (object_file.c glue, objdump). */
 ObjKind obj_image_kind(const ObjImage*);
 u64 obj_image_entry(const ObjImage*);
 u64 obj_image_base(const ObjImage*);
 Sym obj_image_interp(const ObjImage*);
 Sym obj_image_soname(const ObjImage*);
 u32 obj_image_nsegments(const ObjImage*);
 const ObjSegment* obj_image_segment(const ObjImage*, u32 idx);
 u32 obj_image_ndeps(const ObjImage*);
 const ObjImageDep* obj_image_dep(const ObjImage*, u32 idx);
 u32 obj_image_nrpaths(const ObjImage*);
 Sym obj_image_rpath(const ObjImage*, u32 idx);
 u32 obj_image_ndynsyms(const ObjImage*);
 const ObjImageSym* obj_image_dynsym(const ObjImage*, u32 idx);
 u32 obj_image_ndynrelocs(const ObjImage*);
 const ObjImageReloc* obj_image_dynreloc(const ObjImage*, u32 idx);
 u32 obj_image_nundefs(const ObjImage*);
 Sym obj_image_undef(const ObjImage*, u32 idx);
 u32 obj_image_nraws(const ObjImage*);
 const ObjImageRaw* obj_image_raw(const ObjImage*, u32 idx);
 
 /* ---- file format emitters ---- */
 void emit_elf(Compiler*, ObjBuilder*, Writer*);
 void emit_coff(Compiler*, ObjBuilder*, Writer*);
 void emit_macho(Compiler*, ObjBuilder*, Writer*);
 void emit_wasm(Compiler*, ObjBuilder*, Writer*);
 
 /* ---- file format readers (for ld and objdump) ---- */
 ObjBuilder* read_elf(Compiler*, const char* name, const u8* data, size_t len);
 /* ELF ET_DYN reader. Produces an ObjBuilder containing only the DSO's
  * exported (dynsym) symbols. Defined dynsym entries land as ObjSyms
  * with their original SymBind/SymKind so the linker's symbol-resolution
  * pass can match them by name. The DSO's sections, relocations, and
  * groups are all skipped — DSOs contribute no bytes to the output.
  *
  * If `soname_out` is non-NULL, *soname_out receives the DT_SONAME
  * interned into the compiler's global Sym pool, or 0 if the DSO has
  * no SONAME. */
 ObjBuilder* read_elf_dso(Compiler*, const char* name, const u8* data,
                          size_t len, Sym* soname_out);
 ObjBuilder* read_coff(Compiler*, const char* name, const u8* data, size_t len);
 /* PE32+ DLL reader.  Walks the IMAGE_DIRECTORY_ENTRY_EXPORT data
  * directory and produces an ObjBuilder containing one defined symbol
  * (OBJ_SEC_NONE, SB_GLOBAL, SK_FUNC) per name in the Export Name
  * Table — the peer of read_elf_dso / read_macho_dso.  The DLL's
  * own Name string (the analogue of DT_SONAME / LC_ID_DYLIB) is
  * interned and returned via *soname_out, or 0 if missing.
  *
  * Scope: PE32+ images with IMAGE_FILE_DLL set, machine AMD64 or
  * ARM64.  Ordinal-only exports (in the EAT but not the ENT) are not
  * synthesized in v1 — almost all real-world imports are by name. */
 ObjBuilder* read_coff_dso(Compiler*, const char* name, const u8* data,
                           size_t len, Sym* soname_out);
 /* PE32+ linked-image reader (peer of read_elf_image / read_macho_image).
  * Handles both executables (IMAGE_FILE_DLL clear -> OBJ_KIND_EXEC) and
  * DLLs (set -> OBJ_KIND_DYN), populating the neutral ObjImage: one
  * segment per PE section, exports -> dynsyms + soname, imports -> deps +
  * undefined dynsyms, base relocs -> RELATIVE dynrelocs, plus a full
  * section/symbol view via the ObjBuilder Section table, and the raw
  * data-directory / subsystem / dllchars escape-hatch entries.  Lenient:
  * malformed sub-tables are skipped; truncated core headers panic.
  * Dispatched from read_coff on the DOS 'MZ' magic. */
 ObjBuilder* read_coff_image(Compiler*, const char* name, const u8* data,
                             size_t len);
 ObjBuilder* read_macho(Compiler*, const char* name, const u8* data, size_t len);
 /* Mach-O MH_DYLIB reader. Produces an ObjBuilder containing only the
  * dylib's exported symbols (as defined OBJ_SEC_NONE entries — the
  * peer of read_elf_dso). LC_ID_DYLIB's install-name is interned and
  * returned via *install_name_out (the Mach-O analogue of DT_SONAME).
  *
  * arm64-only for v1; other cputypes panic. */
 ObjBuilder* read_macho_dso(Compiler*, const char* name, const u8* data,
                            size_t len, Sym* install_name_out);
 /* Apple `.tbd` (text-based stub) reader.  Parses the YAML-shaped TAPI
  * format produced by Apple's SDKs (see /usr/lib/lib*.tbd in
  * `xcrun --show-sdk-path`).  Extracts the umbrella install-name and the
  * union of every exported / re-exported symbol whose `targets:` block
  * names the active arch (e.g. arm64-macos).  Symbols are emitted into
  * the ObjBuilder verbatim (they already include the leading `_` Apple
  * uses for C symbols), so resolve_undefs matches them against the
  * Mach-O on-disk symbol names directly.
  *
  * The arch string ("arm64" or "x86_64") comes from Compiler.target. */
 ObjBuilder* read_tbd(Compiler*, const char* name, const u8* data, size_t len,
                      Sym* install_name_out);
 
 /* ---- shared string-table builder (ELF / COFF / Mach-O symtab strtabs) ----
  *
  * Each object writer builds a string table: a leading prefix byte(s) followed
  * by NUL-terminated names, with each name's byte offset recorded in its symbol
  * record. Names repeat (a symbol defined and referenced; many `.rela.<sec>`
  * section names), so the table dedupes identical strings — purely a size
  * optimization (any valid offset to the right bytes is conformant), which is
  * why the policy can be identical across all three formats.
  *
  * The bytes live in one contiguous, growable buffer; dedup is an open-addressed
  * hash of {hash,off,len} that verifies a candidate by reading `data+off` (so it
  * retains no external pointers and needs no per-add flatten). This replaced a
  * per-add buf_flatten + linear substring scan that was O(n^2) in the symbol
  * count -- 31% of all instructions when compiling sqlite to ELF. The dedup is
  * exact-match (not the old suffix/tail-merge), so the table is marginally
  * larger than binutils' where a name is a suffix of another, but still minimal
  * and valid. */
 typedef struct ObjStrtabEnt {
   u32 hash;
   u32 off;
   u32 len; /* 0 marks an empty slot (len-0 strings are never stored) */
 } ObjStrtabEnt;
 
 typedef struct ObjStrtab {
   u8* data; /* contiguous table bytes (mutable: a caller may patch a prefix) */
   u32 len;
   u32 cap;
   ObjStrtabEnt* slots; /* dedup index; NULL/empty when !dedup */
   u32 scap;            /* power-of-two slot capacity */
   u32 sused;
   Heap* heap;
   u8 dedup;
 } ObjStrtab;
 
 void obj_strtab_init(ObjStrtab*, Heap*, int dedup);
 /* Append prefix bytes that belong to the table but are never a dedup target
  * (a leading NUL, a COFF 4-byte size-field placeholder). */
 void obj_strtab_put_raw(ObjStrtab*, const void* bytes, u32 n);
 /* Add a name; return its byte offset. With dedup an exact duplicate returns the
  * prior offset (O(1) amortized). len 0 -> offset 0 (the empty string). */
 u32 obj_strtab_add(ObjStrtab*, const char* s, u32 len);
 u32 obj_strtab_size(const ObjStrtab*);
 u8* obj_strtab_data(ObjStrtab*);
 void obj_strtab_fini(ObjStrtab*);
 
 #endif