kit

object_file.c (29612B)

---

 /* Public KitObjFile reader. Wraps the internal read_/obj_ surface
  * and exposes format-neutral object inspection. */
 
 #include <kit/object.h>
 #include <setjmp.h>
 #include <string.h>
 
 #include "core/buf.h"
 #include "core/core.h"
 #include "core/heap.h"
 #include "core/pool.h"
 #include "core/slice.h"
 #include "core/vec.h"
 #include "obj/format.h"
 #include "obj/obj.h"
 
 struct KitObjFile {
   Compiler compiler;
   const KitContext* ctx;
   KitTarget* resolved_target;
   ObjBuilder* ob;
   ObjFmt fmt;
   KitTargetSpec target;
   const u8** sec_data_cache;
   u32* sec_data_size;
   u32 sec_data_n;
 };
 
 KitStatus kit_obj_open(const KitContext* ctx, KitSlice name,
                        const KitSlice* input, KitObjFile** out) {
   Heap* h;
   KitObjFile* f;
   const ObjFormatImpl* impl;
   KitTargetSpec target;
   KitStatus st;
 
   if (!out) return KIT_INVALID;
   *out = NULL;
   if (!ctx || !ctx->heap || !input) return KIT_INVALID;
   if (!input->data && input->len > 0) return KIT_INVALID;
 
   st = kit_detect_target(input->data, input->len, &target);
   if (st != KIT_OK) return st;
   impl = obj_format_lookup(target.obj);
   if (!impl || !impl->read) return KIT_UNSUPPORTED;
 
   h = ctx->heap;
   f = (KitObjFile*)h->alloc(h, sizeof(*f), _Alignof(KitObjFile));
   if (!f) return KIT_NOMEM;
   memset(f, 0, sizeof(*f));
   f->ctx = ctx;
   f->fmt = target.obj;
   f->target = target;
 
   {
     KitTargetOptions topts;
     memset(&topts, 0, sizeof topts);
     topts.spec = target;
     st = kit_target_new(ctx, &topts, &f->resolved_target);
     if (st != KIT_OK) {
       h->free(h, f, sizeof(*f));
       return st;
     }
   }
   st = compiler_init(&f->compiler, f->resolved_target, ctx);
   if (st != KIT_OK) {
     kit_target_free(f->resolved_target);
     h->free(h, f, sizeof(*f));
     return st;
   }
   {
     PanicFrame panic;
     compiler_panic_push(&f->compiler, &panic);
     if (setjmp(panic.env)) {
       compiler_run_cleanups(&f->compiler);
       compiler_panic_pop(&f->compiler, &panic);
       compiler_fini(&f->compiler);
       kit_target_free(f->resolved_target);
       h->free(h, f, sizeof(*f));
       return KIT_MALFORMED;
     }
     f->ob = impl->read(&f->compiler, name.s, input->data, input->len);
     compiler_panic_pop(&f->compiler, &panic);
   }
   if (!f->ob) {
     compiler_fini(&f->compiler);
     kit_target_free(f->resolved_target);
     h->free(h, f, sizeof(*f));
     return KIT_MALFORMED;
   }
   *out = f;
   return KIT_OK;
 }
 
 void kit_obj_free(KitObjFile* f) {
   Heap* h;
   if (!f) return;
   h = f->ctx->heap;
   if (f->sec_data_cache) {
     u32 i;
     for (i = 0; i < f->sec_data_n; ++i) {
       if (f->sec_data_cache[i]) {
         h->free(h, (void*)f->sec_data_cache[i], f->sec_data_size[i]);
       }
     }
     h->free(h, f->sec_data_cache, sizeof(*f->sec_data_cache) * f->sec_data_n);
     h->free(h, f->sec_data_size, sizeof(*f->sec_data_size) * f->sec_data_n);
   }
   if (f->ob) obj_free(f->ob);
   compiler_fini(&f->compiler);
   kit_target_free(f->resolved_target);
   h->free(h, f, sizeof(*f));
 }
 
 KitObjFmt kit_obj_fmt(const KitObjFile* f) { return f->fmt; }
 
 /* Public object-format name <-> KitObjFmt mapping (objcopy/objdump bfdname
  * spellings). Thin wrappers over the internal obj_format name registry. */
 KitStatus kit_obj_fmt_from_name(const char* name, KitObjFmt* out) {
   return obj_format_fmt_from_name(name, out) ? KIT_OK : KIT_NOT_FOUND;
 }
 
 const char* kit_obj_fmt_name(KitObjFmt fmt) { return obj_format_fmt_name(fmt); }
 
 KitTargetSpec kit_obj_target(const KitObjFile* f) { return f->target; }
 
 uint32_t kit_obj_nsections(const KitObjFile* f) {
   return obj_section_count(f->ob);
 }
 
 KitStatus kit_obj_section(const KitObjFile* f, KitObjSection idx,
                           KitObjSecInfo* out) {
   const Section* sec;
   if (!f || !out) return KIT_INVALID;
   if (idx >= obj_section_count(f->ob)) return KIT_NOT_FOUND;
   sec = obj_section_get(f->ob, (ObjSecId)(idx + 1));
   if (!sec) return KIT_NOT_FOUND;
   out->name =
       sec->name ? pool_slice(f->compiler.global, sec->name) : SLICE_LIT("");
   out->kind = (KitSecKind)sec->kind;
   out->flags = (uint32_t)sec->flags;
   out->size = sec->bss_size ? sec->bss_size : sec->bytes.total;
   out->addr = sec->addr;
   out->align = sec->align > 1u ? sec->align : 1u;
   out->entsize = sec->entsize;
   return KIT_OK;
 }
 
 KitStatus kit_obj_section_data(const KitObjFile* cf, KitObjSection idx,
                                const uint8_t** data_out, size_t* len_out) {
   KitObjFile* f = (KitObjFile*)cf;
   const Section* sec;
   Heap* h;
   u32 n;
   u8* buf;
 
   if (!f || !data_out || !len_out) return KIT_INVALID;
   *data_out = NULL;
   *len_out = 0;
 
   n = obj_section_count(f->ob);
   if (idx >= n) return KIT_NOT_FOUND;
 
   sec = obj_section_get(f->ob, (ObjSecId)(idx + 1));
   if (!sec) return KIT_NOT_FOUND;
   if (sec->bss_size || sec->bytes.total == 0) return KIT_OK;
 
   h = f->ctx->heap;
 
   if (!f->sec_data_cache) {
     f->sec_data_cache = (const u8**)h->alloc(h, sizeof(*f->sec_data_cache) * n,
                                              _Alignof(const u8*));
     if (!f->sec_data_cache) return KIT_NOMEM;
     f->sec_data_size =
         (u32*)h->alloc(h, sizeof(*f->sec_data_size) * n, _Alignof(u32));
     if (!f->sec_data_size) {
       h->free(h, f->sec_data_cache, sizeof(*f->sec_data_cache) * n);
       f->sec_data_cache = NULL;
       return KIT_NOMEM;
     }
     {
       u32 i;
       for (i = 0; i < n; ++i) {
         f->sec_data_cache[i] = NULL;
         f->sec_data_size[i] = 0;
       }
     }
     f->sec_data_n = n;
   }
 
   if (f->sec_data_cache[idx]) {
     *data_out = f->sec_data_cache[idx];
     *len_out = f->sec_data_size[idx];
     return KIT_OK;
   }
 
   buf = (u8*)h->alloc(h, sec->bytes.total, 1);
   if (!buf) return KIT_NOMEM;
   buf_flatten(&sec->bytes, buf);
   f->sec_data_cache[idx] = buf;
   f->sec_data_size[idx] = sec->bytes.total;
   *data_out = buf;
   *len_out = sec->bytes.total;
   return KIT_OK;
 }
 
 KitStatus kit_obj_section_format_flags(const KitObjFile* f, KitObjSection idx,
                                        uint32_t* raw_type_out,
                                        uint32_t* raw_flags_out) {
   const Section* sec;
   if (!f) return KIT_INVALID;
   if (idx >= obj_section_count(f->ob)) return KIT_NOT_FOUND;
   sec = obj_section_get(f->ob, (ObjSecId)(idx + 1));
   if (!sec) return KIT_NOT_FOUND;
   if (raw_type_out) *raw_type_out = sec->ext_type;
   if (raw_flags_out) *raw_flags_out = sec->ext_flags;
   return KIT_OK;
 }
 
 KitStatus kit_obj_section_by_name(const KitObjFile* f, KitSlice name,
                                   KitObjSection* out) {
   u32 n, i;
   if (!f || !out) return KIT_INVALID;
   n = obj_section_count(f->ob);
   for (i = 0; i < n; ++i) {
     const Section* sec = obj_section_get(f->ob, (ObjSecId)(i + 1));
     if (!sec || !sec->name) continue;
     if (slice_eq(pool_slice(f->compiler.global, sec->name), name)) {
       *out = i;
       return KIT_OK;
     }
   }
   return KIT_NOT_FOUND;
 }
 
 int kit_obj_section_size_class(const KitObjSecInfo* sec) {
   int exec, write;
   if (!sec) return KIT_SEC_SIZE_NONE;
   exec = (sec->flags & KIT_SF_EXEC) != 0;
   write = (sec->flags & KIT_SF_WRITE) != 0;
   if (!(sec->flags & KIT_SF_ALLOC)) return KIT_SEC_SIZE_NONE;
   if (sec->kind == KIT_SEC_DEBUG) return KIT_SEC_SIZE_NONE;
   if (sec->kind == KIT_SEC_TEXT || exec) return KIT_SEC_SIZE_TEXT;
   if (sec->kind == KIT_SEC_BSS) return KIT_SEC_SIZE_BSS;
   if (sec->kind == KIT_SEC_RODATA) return KIT_SEC_SIZE_DATA;
   if (sec->kind == KIT_SEC_DATA || write) return KIT_SEC_SIZE_DATA;
   return KIT_SEC_SIZE_DATA;
 }
 
 KitStatus kit_obj_size_totals(KitObjFile* f, bool include_common,
                               KitObjSizeTotals* out) {
   u32 ns, i;
   if (!f || !out) return KIT_INVALID;
   out->text = 0;
   out->data = 0;
   out->bss = 0;
   out->total = 0;
   ns = obj_section_count(f->ob);
   for (i = 0; i < ns; ++i) {
     KitObjSecInfo sec;
     if (kit_obj_section(f, i, &sec) != KIT_OK) continue;
     switch (kit_obj_section_size_class(&sec)) {
       case KIT_SEC_SIZE_TEXT:
         out->text += sec.size;
         break;
       case KIT_SEC_SIZE_DATA:
         out->data += sec.size;
         break;
       case KIT_SEC_SIZE_BSS:
         out->bss += sec.size;
         break;
       default:
         break;
     }
   }
   if (include_common) {
     KitObjSymIter* it = NULL;
     if (kit_obj_symiter_new(f, &it) == KIT_OK) {
       KitObjSymInfo si;
       while (kit_obj_symiter_next(it, &si) == KIT_ITER_ITEM) {
         if (si.kind == KIT_SK_COMMON) out->bss += si.size;
       }
       kit_obj_symiter_free(it);
     }
   }
   out->total = out->text + out->data + out->bss;
   return KIT_OK;
 }
 
 static void fill_syminfo(const KitObjFile* f, ObjSymId id, const ObjSym* sym,
                          KitObjSymInfo* out) {
   out->name =
       sym->name ? pool_slice(f->compiler.global, sym->name) : SLICE_LIT("");
   out->id = (id != OBJ_SYM_NONE) ? (KitObjSymbol)id : KIT_OBJ_SYMBOL_NONE;
   out->bind = (KitSymBind)sym->bind;
   out->kind = (KitSymKind)sym->kind;
   out->section = sym->section_id != OBJ_SEC_NONE
                      ? (KitObjSection)(sym->section_id - 1)
                      : KIT_SECTION_NONE;
   out->value = sym->value;
   out->size = sym->size;
 }
 
 KitStatus kit_obj_symbol_by_name(const KitObjFile* f, KitSlice name,
                                  KitObjSymInfo* out) {
   ObjSymIter* it;
   ObjSymEntry e;
   if (!f || !out) return KIT_INVALID;
   it = obj_symiter_new(f->ob);
   if (!it) return KIT_NOMEM;
   while (obj_symiter_next(it, &e)) {
     if (!e.sym || !e.sym->name) continue;
     if (slice_eq(pool_slice(f->compiler.global, e.sym->name), name)) {
       fill_syminfo(f, e.id, e.sym, out);
       obj_symiter_free(it);
       return KIT_OK;
     }
   }
   obj_symiter_free(it);
   return KIT_NOT_FOUND;
 }
 
 struct KitObjSymIter {
   const KitObjFile* file;
   ObjSymIter* inner; /* .symtab walk; NULL when iterating the dynamic table */
   u32 dyn_idx;       /* next index into obj_image dynsyms (dynamic mode) */
   int dynamic;
 };
 
 /* Shared by kit_obj_symiter_new (.symtab) and kit_obj_dynsymiter_new
  * (.dynsym). When dynamic, the inner ObjSymIter is unused and we walk the
  * image's dynamic symbol table by index. */
 static KitStatus symiter_make(const KitObjFile* f, int dynamic,
                               KitObjSymIter** out) {
   Heap* h;
   KitObjSymIter* it;
   if (!f || !out) return KIT_INVALID;
   h = f->ctx->heap;
   it = (KitObjSymIter*)h->alloc(h, sizeof(*it), _Alignof(KitObjSymIter));
   if (!it) return KIT_NOMEM;
   it->file = f;
   it->inner = NULL;
   it->dyn_idx = 0;
   it->dynamic = dynamic;
   if (!dynamic) {
     it->inner = obj_symiter_new(f->ob);
     if (!it->inner) {
       h->free(h, it, sizeof(*it));
       return KIT_NOMEM;
     }
   }
   *out = it;
   return KIT_OK;
 }
 
 KitStatus kit_obj_symiter_new(const KitObjFile* f, KitObjSymIter** out) {
   return symiter_make(f, 0, out);
 }
 
 KitStatus kit_obj_dynsymiter_new(const KitObjFile* f, KitObjSymIter** out) {
   return symiter_make(f, 1, out);
 }
 
 KitIterResult kit_obj_symiter_next(KitObjSymIter* it, KitObjSymInfo* out) {
   ObjSymEntry entry;
   if (!it || !out) return KIT_ITER_ERROR;
   if (it->dynamic) {
     const ObjImage* im = obj_image(it->file->ob);
     const ObjImageSym* s;
     if (it->dyn_idx >= obj_image_ndynsyms(im)) return KIT_ITER_END;
     s = obj_image_dynsym(im, it->dyn_idx++);
     out->name = pool_slice(it->file->compiler.global, s->name);
     out->id = KIT_OBJ_SYMBOL_NONE;
     out->bind = (KitSymBind)s->bind;
     out->kind = (KitSymKind)s->kind;
     out->section = s->section != OBJ_SEC_NONE ? (KitObjSection)(s->section - 1)
                                               : KIT_SECTION_NONE;
     out->value = s->value;
     out->size = s->size;
     return KIT_ITER_ITEM;
   }
   if (!obj_symiter_next(it->inner, &entry)) return KIT_ITER_END;
   fill_syminfo(it->file, entry.id, entry.sym, out);
   return KIT_ITER_ITEM;
 }
 
 void kit_obj_symiter_free(KitObjSymIter* it) {
   Heap* h;
   if (!it) return;
   if (it->inner) obj_symiter_free(it->inner);
   h = it->file->ctx->heap;
   h->free(h, it, sizeof(*it));
 }
 
 struct KitObjRelocIter {
   KitObjFile* file;
   u32 idx;
   u32 total;
   int dynamic; /* iterate obj_image dynamic relocs instead of section relocs */
 };
 
 static KitStatus reliter_make(KitObjFile* f, int dynamic,
                               KitObjRelocIter** out) {
   Heap* h;
   KitObjRelocIter* it;
   if (!f || !out) return KIT_INVALID;
   h = f->ctx->heap;
   it = (KitObjRelocIter*)h->alloc(h, sizeof(*it), _Alignof(KitObjRelocIter));
   if (!it) return KIT_NOMEM;
   it->file = f;
   it->idx = 0;
   it->dynamic = dynamic;
   it->total =
       dynamic ? obj_image_ndynrelocs(obj_image(f->ob)) : obj_reloc_total(f->ob);
   *out = it;
   return KIT_OK;
 }
 
 KitStatus kit_obj_reliter_new(KitObjFile* f, KitObjRelocIter** out) {
   return reliter_make(f, 0, out);
 }
 
 KitStatus kit_obj_dynreliter_new(KitObjFile* f, KitObjRelocIter** out) {
   return reliter_make(f, 1, out);
 }
 
 /* Format-specific canonical spelling of a reloc kind (e.g. "R_X86_64_PLT32",
  * "R_AARCH64_CALL26", "R_RISCV_CALL"), or NULL when the format has no per-arch
  * name table (callers fall back to the arch-neutral reloc_kind_name).
  *
  * Consulted for every ELF arch whose ObjElfArchOps carries a reloc_name table
  * (x86_64 / aarch64 / riscv): the kit-canonical RelocKind is lowered to its
  * ELF wire type via reloc_to, then named — matching binutils objdump's
  * spelling. The Mach-O / COFF formats have no reloc_name table yet and keep
  * the arch-neutral spelling. reloc_to maps unsupported kinds to wire type 0;
  * only R_NONE legitimately names that slot, so anything else falling through
  * to 0 is reported as "no per-arch name" (NULL) rather than the format's NONE
  * spelling. */
 static const char* kit_obj_reloc_kind_name(KitArchKind arch, KitObjFmt fmt,
                                            u32 kind) {
   const ObjFormatImpl* impl;
   const ObjElfArchOps* ops;
   u32 wire;
   if (fmt != KIT_OBJ_ELF) return NULL;
   impl = obj_format_lookup(fmt);
   if (!impl || !impl->elf_arch) return NULL;
   ops = impl->elf_arch(arch);
   if (!ops || !ops->reloc_to || !ops->reloc_name) return NULL;
   wire = ops->reloc_to(kind);
   if (wire == 0u && (RelocKind)kind != R_NONE) return NULL;
   return ops->reloc_name(wire);
 }
 
 KitIterResult kit_obj_reliter_next(KitObjRelocIter* it, KitObjReloc* out) {
   const Reloc* r;
   const ObjSym* sym;
   if (!it || !out) return KIT_ITER_ERROR;
   if (it->idx >= it->total) return KIT_ITER_END;
 
   if (it->dynamic) {
     const ObjImageReloc* dr =
         obj_image_dynreloc(obj_image(it->file->ob), it->idx++);
     const char* kn;
     out->section =
         dr->section ? (KitObjSection)(dr->section - 1) : KIT_SECTION_NONE;
     out->offset = dr->offset;
     out->addend = dr->addend;
     out->kind.arch = it->file->target.arch;
     out->kind.obj_fmt = it->file->fmt;
     out->kind.code = (uint32_t)dr->kind;
     kn =
         kit_obj_reloc_kind_name(it->file->target.arch, it->file->fmt, dr->kind);
     if (!kn) kn = reloc_kind_name(dr->kind);
     out->kind_name = kn ? slice_from_cstr(kn) : SLICE_NULL;
     out->sym = KIT_OBJ_SYMBOL_NONE;
     out->sym_name = pool_slice(it->file->compiler.global, dr->sym_name);
     return KIT_ITER_ITEM;
   }
 
   r = obj_reloc_at(it->file->ob, it->idx++);
   out->section =
       r->section_id ? (KitObjSection)(r->section_id - 1) : KIT_SECTION_NONE;
   out->offset = r->offset;
   out->addend = r->addend;
   out->kind.arch = it->file->target.arch;
   out->kind.obj_fmt = it->file->fmt;
   out->kind.code = (uint32_t)r->kind;
   {
     /* Prefer the format-specific canonical spelling (e.g. "R_X86_64_PLT32");
      * fall back to the arch-neutral diagnostic spelling ("RV_CALL"). */
     const char* kn =
         kit_obj_reloc_kind_name(it->file->target.arch, it->file->fmt, r->kind);
     if (!kn) kn = reloc_kind_name(r->kind);
     out->kind_name = kn ? slice_from_cstr(kn) : SLICE_NULL;
   }
 
   if (r->sym == OBJ_SYM_NONE) {
     out->sym = KIT_OBJ_SYMBOL_NONE;
     out->sym_name = SLICE_LIT("");
   } else {
     out->sym = (KitObjSymbol)r->sym;
     sym = obj_symbol_get(it->file->ob, r->sym);
     out->sym_name = (sym && sym->name)
                         ? pool_slice(it->file->compiler.global, sym->name)
                         : SLICE_LIT("");
   }
   return KIT_ITER_ITEM;
 }
 
 void kit_obj_reliter_free(KitObjRelocIter* it) {
   Heap* h;
   if (!it) return;
   h = it->file->ctx->heap;
   h->free(h, it, sizeof(*it));
 }
 
 static int reloc_live_id_in_set(KitObjSymbol id, const KitObjSymbol* arr,
                                 u32 n) {
   u32 i;
   for (i = 0; i < n; ++i)
     if (arr[i] == id) return 1;
   return 0;
 }
 
 KitStatus kit_obj_reloc_live_symbols(const KitContext* ctx, KitObjFile* f,
                                      KitObjSymbol** out, uint32_t* n_out) {
   Heap* h;
   KitObjRelocIter* rit = NULL;
   KitObjSymbol* arr = NULL;
   u32 n = 0, cap = 0;
   KitStatus st;
 
   if (!out || !n_out) return KIT_INVALID;
   *out = NULL;
   *n_out = 0;
   if (!ctx || !ctx->heap || !f) return KIT_INVALID;
   h = ctx->heap;
 
   st = kit_obj_reliter_new(f, &rit);
   if (st != KIT_OK) return st;
   for (;;) {
     KitObjReloc r;
     KitIterResult ir = kit_obj_reliter_next(rit, &r);
     if (ir != KIT_ITER_ITEM) break;
     if (r.sym == KIT_OBJ_SYMBOL_NONE) continue;
     /* Skip relocs hosted in a debug section -- that section is being dropped,
      * so its relocs don't actually keep their targets alive. */
     if (r.section != KIT_SECTION_NONE) {
       KitObjSecInfo hi;
       if (kit_obj_section(f, r.section, &hi) == KIT_OK &&
           hi.kind == KIT_SEC_DEBUG)
         continue;
     }
     if (reloc_live_id_in_set(r.sym, arr, n)) continue;
     if (n >= cap) {
       u32 newcap = cap ? cap * 2u : 32u;
       KitObjSymbol* nb =
           (KitObjSymbol*)h->alloc(h, (size_t)newcap * sizeof(*nb),
                                   _Alignof(KitObjSymbol));
       if (!nb) {
         kit_obj_reliter_free(rit);
         if (arr) h->free(h, arr, (size_t)cap * sizeof(*arr));
         return KIT_NOMEM;
       }
       if (arr) {
         memcpy(nb, arr, (size_t)n * sizeof(*arr));
         h->free(h, arr, (size_t)cap * sizeof(*arr));
       }
       arr = nb;
       cap = newcap;
     }
     arr[n++] = r.sym;
   }
   kit_obj_reliter_free(rit);
 
   /* Hand back an exactly-sized array so the caller frees with n_out, not a
    * private capacity. */
   if (n == 0) {
     if (arr) h->free(h, arr, (size_t)cap * sizeof(*arr));
     return KIT_OK;
   }
   if (n != cap) {
     KitObjSymbol* shrunk =
         (KitObjSymbol*)h->alloc(h, (size_t)n * sizeof(*shrunk),
                                 _Alignof(KitObjSymbol));
     if (!shrunk) {
       /* Keep the over-sized buffer rather than fail; but the caller frees with
        * n, which would mismatch. Safer to report NOMEM and release. */
       h->free(h, arr, (size_t)cap * sizeof(*arr));
       return KIT_NOMEM;
     }
     memcpy(shrunk, arr, (size_t)n * sizeof(*shrunk));
     h->free(h, arr, (size_t)cap * sizeof(*arr));
     arr = shrunk;
   }
   *out = arr;
   *n_out = n;
   return KIT_OK;
 }
 
 struct KitObjGroupIter {
   KitObjFile* file;
   ObjGroupIter* inner;
   /* Translation scratch for the borrowed `sections` slice handed back to
    * the caller. Lazily grown to the largest group's nsections. */
   KitObjSection* secbuf;
   u32 seccap;
 };
 
 KitStatus kit_obj_groupiter_new(KitObjFile* f, KitObjGroupIter** out) {
   Heap* h;
   KitObjGroupIter* it;
   if (!f || !out) return KIT_INVALID;
   h = f->ctx->heap;
   it = (KitObjGroupIter*)h->alloc(h, sizeof(*it), _Alignof(KitObjGroupIter));
   if (!it) return KIT_NOMEM;
   memset(it, 0, sizeof(*it));
   it->file = f;
   it->inner = obj_groupiter_new(f->ob);
   if (!it->inner) {
     h->free(h, it, sizeof(*it));
     return KIT_NOMEM;
   }
   *out = it;
   return KIT_OK;
 }
 
 KitIterResult kit_obj_groupiter_next(KitObjGroupIter* it,
                                      KitObjGroupInfo* out) {
   ObjGroupEntry entry;
   Heap* h;
   u32 i;
   if (!it || !out) return KIT_ITER_ERROR;
   if (!obj_groupiter_next(it->inner, &entry)) return KIT_ITER_END;
   h = it->file->ctx->heap;
   if (entry.group->nsections > it->seccap) {
     KitObjSection* nb;
     nb = (KitObjSection*)h->alloc(h, sizeof(*nb) * entry.group->nsections,
                                   _Alignof(KitObjSection));
     if (!nb) return KIT_ITER_ERROR;
     if (it->secbuf) h->free(h, it->secbuf, sizeof(*it->secbuf) * it->seccap);
     it->secbuf = nb;
     it->seccap = entry.group->nsections;
   }
   for (i = 0; i < entry.group->nsections; ++i) {
     ObjSecId sid = entry.group->sections[i];
     it->secbuf[i] =
         (sid != OBJ_SEC_NONE) ? (KitObjSection)(sid - 1) : KIT_SECTION_NONE;
   }
   out->name = entry.group->name
                   ? pool_slice(it->file->compiler.global, entry.group->name)
                   : KIT_SLICE_NULL;
   out->signature = (entry.group->signature != OBJ_SYM_NONE)
                        ? (KitObjSymbol)entry.group->signature
                        : KIT_OBJ_SYMBOL_NONE;
   out->flags = entry.group->flags;
   out->nsections = entry.group->nsections;
   out->sections = it->secbuf;
   return KIT_ITER_ITEM;
 }
 
 void kit_obj_groupiter_free(KitObjGroupIter* it) {
   Heap* h;
   if (!it) return;
   h = it->file->ctx->heap;
   if (it->secbuf) h->free(h, it->secbuf, sizeof(*it->secbuf) * it->seccap);
   obj_groupiter_free(it->inner);
   h->free(h, it, sizeof(*it));
 }
 
 /* Accessor for disasm/jit to access the underlying ObjBuilder when both
  * are inside libkit. Internal name kept stable for existing callers
  * (src/link/link_jit.c, src/api/disasm.c). */
 ObjBuilder* kit_objfile_builder(const KitObjFile* f) {
   return f ? f->ob : NULL;
 }
 
 /* Public alias of kit_objfile_builder. Promoted to the public API so the
  * driver (and other libkit consumers) can take an opened object and feed
  * it into kit_obj_builder_emit for a byte-equivalent roundtrip without
  * re-implementing the read-then-replay loop. */
 KitObjBuilder* kit_obj_file_builder(const KitObjFile* f) {
   return kit_objfile_builder(f);
 }
 
 /* Allocate an empty KitObjFile wrapping a private Compiler and a fresh
  * ObjBuilder. Used by the JIT debug-view builder (src/link/link_jit.c)
  * to assemble a synthetic object file from merged input debug sections.
  * The handle is freed via kit_objfile_internal_free below — the public
  * kit_obj_free path is keyed off obj_read_bytes, so the view path uses
  * its own teardown that does not depend on the cached section data
  * tables. */
 KitObjFile* kit_objfile_internal_new(const KitContext* ctx,
                                      KitTargetSpec target, KitObjFmt fmt) {
   Heap* h;
   KitObjFile* f;
   if (!ctx || !ctx->heap) return NULL;
   h = ctx->heap;
   f = (KitObjFile*)h->alloc(h, sizeof(*f), _Alignof(KitObjFile));
   if (!f) return NULL;
   memset(f, 0, sizeof(*f));
   f->ctx = ctx;
   f->fmt = fmt;
   f->target = target;
   {
     KitTargetOptions topts;
     KitStatus st;
     memset(&topts, 0, sizeof topts);
     topts.spec = target;
     st = kit_target_new(ctx, &topts, &f->resolved_target);
     if (st != KIT_OK) {
       h->free(h, f, sizeof(*f));
       return NULL;
     }
     st = compiler_init(&f->compiler, f->resolved_target, ctx);
     if (st != KIT_OK) {
       kit_target_free(f->resolved_target);
       h->free(h, f, sizeof(*f));
       return NULL;
     }
   }
   {
     PanicFrame panic;
     compiler_panic_push(&f->compiler, &panic);
     if (setjmp(panic.env)) {
       compiler_run_cleanups(&f->compiler);
       compiler_panic_pop(&f->compiler, &panic);
       compiler_fini(&f->compiler);
       kit_target_free(f->resolved_target);
       h->free(h, f, sizeof(*f));
       return NULL;
     }
     f->ob = obj_new(&f->compiler);
     compiler_panic_pop(&f->compiler, &panic);
   }
   if (!f->ob) {
     compiler_fini(&f->compiler);
     kit_target_free(f->resolved_target);
     h->free(h, f, sizeof(*f));
     return NULL;
   }
   return f;
 }
 
 void kit_objfile_internal_free(KitObjFile* f) {
   /* Same teardown contract as kit_obj_free: caller may have cached
    * section data, so we route through the same path. */
   kit_obj_free(f);
 }
 
 /* ============================================================
  * Linked-image view
  * ============================================================ */
 
 KitObjKind kit_obj_kind(const KitObjFile* f) {
   const ObjImage* im;
   if (!f) return KIT_OBJ_KIND_REL;
   im = obj_image(f->ob);
   if (!im) return KIT_OBJ_KIND_REL;
   switch (obj_image_kind(im)) {
     case OBJ_KIND_EXEC:
       return KIT_OBJ_KIND_EXEC;
     case OBJ_KIND_DYN:
       return KIT_OBJ_KIND_DYN;
     case OBJ_KIND_CORE:
       return KIT_OBJ_KIND_CORE;
     case OBJ_KIND_REL:
     default:
       return KIT_OBJ_KIND_REL;
   }
 }
 
 KitStatus kit_obj_image_info(const KitObjFile* f, KitObjImageInfo* out) {
   const ObjImage* im;
   if (!f || !out) return KIT_INVALID;
   im = obj_image(f->ob);
   if (!im) return KIT_NOT_FOUND;
   out->entry = obj_image_entry(im);
   out->image_base = obj_image_base(im);
   out->interp = pool_slice(f->compiler.global, obj_image_interp(im));
   out->soname = pool_slice(f->compiler.global, obj_image_soname(im));
   return KIT_OK;
 }
 
 struct KitObjSegIter {
   KitObjFile* file;
   u32 idx;
 };
 
 KitStatus kit_obj_segiter_new(KitObjFile* f, KitObjSegIter** out) {
   Heap* h;
   KitObjSegIter* it;
   if (!f || !out) return KIT_INVALID;
   h = f->ctx->heap;
   it = (KitObjSegIter*)h->alloc(h, sizeof(*it), _Alignof(KitObjSegIter));
   if (!it) return KIT_NOMEM;
   it->file = f;
   it->idx = 0;
   *out = it;
   return KIT_OK;
 }
 
 KitIterResult kit_obj_segiter_next(KitObjSegIter* it, KitObjSegInfo* out) {
   const ObjImage* im;
   const ObjSegment* s;
   if (!it || !out) return KIT_ITER_ERROR;
   im = obj_image(it->file->ob);
   if (it->idx >= obj_image_nsegments(im)) return KIT_ITER_END;
   s = obj_image_segment(im, it->idx++);
   out->name = pool_slice(it->file->compiler.global, s->name);
   out->vaddr = s->vaddr;
   out->paddr = s->paddr;
   out->vsize = s->vsize;
   out->file_off = s->file_off;
   out->file_size = s->file_size;
   out->perms = s->perms; /* OBJ_SEG_* and KIT_SEG_* share bit values */
   out->align = s->align;
   return KIT_ITER_ITEM;
 }
 
 void kit_obj_segiter_free(KitObjSegIter* it) {
   Heap* h;
   if (!it) return;
   h = it->file->ctx->heap;
   h->free(h, it, sizeof(*it));
 }
 
 struct KitObjDepIter {
   KitObjFile* file;
   u32 idx;
   KitSlice* import_buf; /* scratch for the current dep's import names */
   u32 import_cap;
 };
 
 KitStatus kit_obj_depiter_new(KitObjFile* f, KitObjDepIter** out) {
   Heap* h;
   KitObjDepIter* it;
   if (!f || !out) return KIT_INVALID;
   h = f->ctx->heap;
   it = (KitObjDepIter*)h->alloc(h, sizeof(*it), _Alignof(KitObjDepIter));
   if (!it) return KIT_NOMEM;
   it->file = f;
   it->idx = 0;
   it->import_buf = NULL;
   it->import_cap = 0;
   *out = it;
   return KIT_OK;
 }
 
 KitIterResult kit_obj_depiter_next(KitObjDepIter* it, KitObjDepInfo* out) {
   const ObjImage* im;
   const ObjImageDep* d;
   Heap* h;
   u32 i;
   if (!it || !out) return KIT_ITER_ERROR;
   im = obj_image(it->file->ob);
   if (it->idx >= obj_image_ndeps(im)) return KIT_ITER_END;
   d = obj_image_dep(im, it->idx++);
   out->name = pool_slice(it->file->compiler.global, d->name);
   out->imports = NULL;
   out->nimports = d->nimports;
   if (d->nimports) {
     h = it->file->ctx->heap;
     if (it->import_cap < d->nimports) {
       if (VEC_GROW(h, it->import_buf, it->import_cap, d->nimports))
         return KIT_ITER_ERROR;
     }
     for (i = 0; i < d->nimports; ++i)
       it->import_buf[i] = pool_slice(it->file->compiler.global, d->imports[i]);
     out->imports = it->import_buf;
   }
   return KIT_ITER_ITEM;
 }
 
 void kit_obj_depiter_free(KitObjDepIter* it) {
   Heap* h;
   if (!it) return;
   h = it->file->ctx->heap;
   if (it->import_buf)
     h->free(h, it->import_buf, sizeof(*it->import_buf) * it->import_cap);
   h->free(h, it, sizeof(*it));
 }
 
 struct KitObjRpathIter {
   KitObjFile* file;
   u32 idx;
 };
 
 KitStatus kit_obj_rpathiter_new(KitObjFile* f, KitObjRpathIter** out) {
   Heap* h;
   KitObjRpathIter* it;
   if (!f || !out) return KIT_INVALID;
   h = f->ctx->heap;
   it = (KitObjRpathIter*)h->alloc(h, sizeof(*it), _Alignof(KitObjRpathIter));
   if (!it) return KIT_NOMEM;
   it->file = f;
   it->idx = 0;
   *out = it;
   return KIT_OK;
 }
 
 KitIterResult kit_obj_rpathiter_next(KitObjRpathIter* it, KitSlice* out) {
   const ObjImage* im;
   if (!it || !out) return KIT_ITER_ERROR;
   im = obj_image(it->file->ob);
   if (it->idx >= obj_image_nrpaths(im)) return KIT_ITER_END;
   *out = pool_slice(it->file->compiler.global, obj_image_rpath(im, it->idx++));
   return KIT_ITER_ITEM;
 }
 
 void kit_obj_rpathiter_free(KitObjRpathIter* it) {
   Heap* h;
   if (!it) return;
   h = it->file->ctx->heap;
   h->free(h, it, sizeof(*it));
 }
 
 struct KitObjImageRawIter {
   KitObjFile* file;
   u32 idx;
 };
 
 KitStatus kit_obj_image_rawiter_new(KitObjFile* f, KitObjImageRawIter** out) {
   Heap* h;
   KitObjImageRawIter* it;
   if (!f || !out) return KIT_INVALID;
   if (!obj_image(f->ob)) return KIT_NOT_FOUND; /* relocatable: no image */
   h = f->ctx->heap;
   it = (KitObjImageRawIter*)h->alloc(h, sizeof(*it),
                                      _Alignof(KitObjImageRawIter));
   if (!it) return KIT_NOMEM;
   it->file = f;
   it->idx = 0;
   *out = it;
   return KIT_OK;
 }
 
 KitIterResult kit_obj_image_rawiter_next(KitObjImageRawIter* it,
                                          KitObjImageRaw* out) {
   const ObjImage* im;
   const ObjImageRaw* r;
   if (!it || !out) return KIT_ITER_ERROR;
   im = obj_image(it->file->ob);
   if (it->idx >= obj_image_nraws(im)) return KIT_ITER_END;
   r = obj_image_raw(im, it->idx++);
   out->tag = r->tag;
   out->value = r->value;
   out->extra = r->extra;
   return KIT_ITER_ITEM;
 }
 
 void kit_obj_image_rawiter_free(KitObjImageRawIter* it) {
   Heap* h;
   if (!it) return;
   h = it->file->ctx->heap;
   h->free(h, it, sizeof(*it));
 }