kit

link.c (50334B)

---

 /* Public link API entries.
  *
  * Thin orchestrators over the Linker primitives in link.c / link_resolve.c /
  * link_layout.c / link_jit.c. Each entry:
  *   - allocates a Linker against the caller's Compiler,
  *   - feeds in the KitLinkInputs,
  *   - configures lane-specific flags (pie, shared, jit),
  *   - calls link_resolve,
  *   - dispatches to the emit (writer) or JIT-map (kit_jit_from_image) tail.
  *
  * The driver's job ends at populating KitLinkInputs; everything below this
  * line is libkit-internal. */
 
 #include "link/link.h"
 
 #include <kit/core.h>
 #include <kit/jit.h>
 #include <kit/link.h>
 #include <kit/target.h>
 #include <setjmp.h>
 #include <stdarg.h>
 #include <stdio.h>
 #include <string.h>
 
 #include "cg/internal.h"
 #include "cg/ir_recorder.h"
 #include "core/core.h"
 #include "core/diag.h"
 #include "link/link_internal.h"
 
 KitJit* kit_jit_from_image(LinkImage*);
 
 static KitStatus link_session_guard(KitLinkSession* s,
                                     void (*fn)(KitLinkSession*, void*),
                                     void* arg) {
   PanicFrame panic;
   if (!s || !s->c || !s->linker || !fn) return KIT_INVALID;
   compiler_panic_push(s->c, &panic);
   if (setjmp(panic.env)) {
     compiler_run_cleanups(s->c);
     s->linker = NULL;
     s->image = NULL;
     compiler_panic_pop(s->c, &panic);
     return KIT_ERR;
   }
   fn(s, arg);
   compiler_panic_pop(s->c, &panic);
   return KIT_OK;
 }
 
 static KitStatus link_session_remember_publish_obj(KitLinkSession* s,
                                                    KitObjBuilder* ob) {
   Heap* h;
   KitObjBuilder** nb;
   u32 new_cap;
   if (!s || !ob) return KIT_INVALID;
   if (s->npublish_objs < s->publish_objs_cap) {
     s->publish_objs[s->npublish_objs++] = ob;
     return KIT_OK;
   }
   h = s->c->ctx->heap;
   new_cap = s->publish_objs_cap ? s->publish_objs_cap * 2u : 8u;
   nb = (KitObjBuilder**)h->realloc(
       h, s->publish_objs, sizeof(*s->publish_objs) * s->publish_objs_cap,
       sizeof(*s->publish_objs) * new_cap, _Alignof(KitObjBuilder*));
   if (!nb) return KIT_NOMEM;
   s->publish_objs = nb;
   s->publish_objs_cap = new_cap;
   s->publish_objs[s->npublish_objs++] = ob;
   return KIT_OK;
 }
 
 /* These KitLinkSessionOptions fields have no plumbing into the Linker yet:
  * the shared-library DT_* knobs (soname/rpaths/runpaths/exports) and the
  * build-id selector (build_id_mode/bytes/len; the
  * ELF writer currently emits a fixed image-hash note regardless of mode).
  * Until they are wired through, warn rather than silently honor the default
  * instead of the caller's request. */
 static void link_warn_ignored_opt(Compiler* c, const char* name) {
   DiagSink* diag = (c && c->ctx) ? c->ctx->diag : NULL;
   if (!diag) return;
   diag_emit(diag, DIAG_WARN, SRCLOC_NONE,
             "link: option '%s' is not yet supported and is ignored", name);
 }
 
 /* -l<name> suffix search order. libkit owns only this policy table + walk
  * order; the host probe does all path composition and filesystem access. */
 typedef struct LibVariant {
   const char* prefix;
   const char* suffix;
   uint8_t kind; /* KitLibResolveKind */
 } LibVariant;
 
 bool kit_lib_resolve(uint8_t os, uint8_t mode, const char* name,
                      const char* const* search_dirs, uint32_t nsearch_dirs,
                      KitLibResolveProbe probe, void* user) {
   /* POSIX dynamic: Apple .tbd/.dylib first (the macOS SDK ships .tbd stubs),
    * then .so, then the .a fallback. DYNAMIC_ONLY drops the trailing .a. */
   static const LibVariant posix_dyn[] = {
       {"lib", ".tbd", KIT_LIB_RESOLVE_KIND_TBD},
       {"lib", ".dylib", KIT_LIB_RESOLVE_KIND_SHARED},
       {"lib", ".so", KIT_LIB_RESOLVE_KIND_SHARED},
       {"lib", ".a", KIT_LIB_RESOLVE_KIND_ARCHIVE},
   };
   static const LibVariant posix_static[] = {
       {"lib", ".a", KIT_LIB_RESOLVE_KIND_ARCHIVE},
   };
   /* Windows / mingw: mingw-canonical names first (lib<n>.dll.a, lib<n>.a),
    * then the MSVC <n>.lib / <n>.dll.a variants. Every match feeds the linker
    * as an archive input (short-form import libs are AR archives). */
   static const LibVariant win_variants[] = {
       {"lib", ".dll.a", KIT_LIB_RESOLVE_KIND_ARCHIVE},
       {"lib", ".a", KIT_LIB_RESOLVE_KIND_ARCHIVE},
       {"", ".lib", KIT_LIB_RESOLVE_KIND_ARCHIVE},
       {"", ".dll.a", KIT_LIB_RESOLVE_KIND_ARCHIVE},
   };
   const LibVariant* variants;
   uint32_t nvariants, vi, di;
 
   if (!name || !probe) return false;
 
   if (os == KIT_LIB_RESOLVE_OS_WINDOWS) {
     variants = win_variants;
     nvariants = (uint32_t)(sizeof win_variants / sizeof win_variants[0]);
   } else if (mode == KIT_LIB_RESOLVE_STATIC_ONLY) {
     variants = posix_static;
     nvariants = (uint32_t)(sizeof posix_static / sizeof posix_static[0]);
   } else {
     variants = posix_dyn;
     nvariants = (uint32_t)(sizeof posix_dyn / sizeof posix_dyn[0]);
     if (mode == KIT_LIB_RESOLVE_DYNAMIC_ONLY) nvariants -= 1u; /* drop .a */
   }
 
   for (vi = 0; vi < nvariants; ++vi) {
     for (di = 0; di < nsearch_dirs; ++di) {
       if (probe(user, search_dirs[di], variants[vi].prefix, name,
                 variants[vi].suffix, variants[vi].kind))
         return true;
     }
   }
   return false;
 }
 
 KitStatus kit_link_session_new(KitCompiler* c,
                                const KitLinkSessionOptions* opts,
                                KitLinkSession** out) {
   Heap* h;
   KitLinkSession* s;
   Linker* l;
   if (!out) return KIT_INVALID;
   *out = NULL;
   if (!c || !opts) return KIT_INVALID;
   h = c->ctx->heap;
   l = link_new(c);
   if (!l) return KIT_NOMEM;
   s = (KitLinkSession*)h->alloc(h, sizeof(*s), _Alignof(KitLinkSession));
   if (!s) {
     link_free(l);
     return KIT_NOMEM;
   }
   memset(s, 0, sizeof(*s));
   s->c = (Compiler*)c;
   s->linker = l;
   s->opts = *opts;
   if (opts->output_kind > KIT_LINK_OUTPUT_JIT) {
     h->free(h, s, sizeof(*s));
     link_free(l);
     return KIT_INVALID;
   }
   if (opts->pe_subsystem != KIT_PE_SUBSYSTEM_DEFAULT &&
       opts->pe_subsystem != KIT_PE_SUBSYSTEM_WINDOWS_GUI &&
       opts->pe_subsystem != KIT_PE_SUBSYSTEM_WINDOWS_CUI) {
     h->free(h, s, sizeof(*s));
     link_free(l);
     return KIT_INVALID;
   }
   link_set_pe_subsystem(l, opts->pe_subsystem);
 
   switch ((KitLinkOutputKind)opts->output_kind) {
     case KIT_LINK_OUTPUT_EXE:
       link_set_emit_static_exe(l, 1);
       link_set_gc_sections(l, opts->gc_sections);
       link_set_strip_debug(l, opts->strip_debug);
       link_set_allow_undefined(l, opts->allow_undefined);
       link_set_pie(l, opts->pie);
       link_set_interp_path(l, opts->interp_path);
       break;
     case KIT_LINK_OUTPUT_SHARED:
       link_set_gc_sections(l, opts->gc_sections);
       link_set_strip_debug(l, opts->strip_debug);
       link_set_allow_undefined(l, 0);
       link_set_shared(l, 1);
       link_set_pie(l, 0);
       if (opts->exports && opts->nexports)
         link_warn_ignored_opt(s->c, "--export-symbol");
       break;
     case KIT_LINK_OUTPUT_RELOCATABLE:
       break;
     case KIT_LINK_OUTPUT_JIT:
       if (!opts->jit_host) {
         h->free(h, s, sizeof(*s));
         link_free(l);
         return KIT_INVALID;
       }
       link_set_jit_host(l, opts->jit_host);
       link_set_jit_mode(l, 1);
       link_set_gc_sections(l, opts->gc_sections);
       if (!opts->entry.s || opts->entry.len == 0) link_clear_entry(l);
       if (opts->extern_resolver) {
         link_set_extern_resolver(l, opts->extern_resolver,
                                  opts->extern_resolver_user);
       }
       break;
   }
   if (opts->linker_script) link_set_script(l, opts->linker_script);
   if (opts->text_base_set) link_set_text_base(l, opts->text_base);
   /* Linker-flags/policy plumbing (kernel-C work). The Linker struct lives in
    * link_internal.h; these fields have no dedicated setter, so the public API
    * composition layer assigns them directly. The arrays are borrowed from the
    * caller (the driver keeps them alive for the session's lifetime). */
   l->defsyms = opts->defsyms;
   l->ndefsyms = opts->ndefsyms;
   l->section_starts = opts->section_starts;
   l->nsection_starts = opts->nsection_starts;
   l->soname = opts->soname;
   l->rpaths = opts->rpaths;
   l->nrpaths = opts->nrpaths;
   l->runpaths = opts->runpaths;
   l->nrunpaths = opts->nrunpaths;
   l->orphan_handling = opts->orphan_handling;
   l->fatal_warnings = opts->fatal_warnings ? 1 : 0;
   l->freestanding_strict = opts->freestanding_strict ? 1 : 0;
   if (opts->entry.s && opts->entry.len) {
     link_set_entry(l, opts->entry);
   } else if (opts->pe_subsystem == KIT_PE_SUBSYSTEM_WINDOWS_GUI &&
              !(opts->linker_script && opts->linker_script->entry.s &&
                opts->linker_script->entry.len)) {
     link_set_entry(l, KIT_SLICE_LIT("WinMainCRTStartup"));
   }
   /* TODO(build-id): the ELF writer (src/obj/elf/link.c) emits a fixed
    * image-hash build-id note unconditionally for non-scripted layouts; the
    * caller's mode selection is not threaded through, so a note is emitted
    * even for KIT_BUILDID_NONE and uuid/user-bytes modes get the default hash.
    * Honoring the mode means carrying it into LinkImage + the ELF/Mach-O
    * writers (and is a no-op for the common default), so it is left as a known
    * gap rather than warned about on the default path. */
   (void)opts->build_id_mode;
   (void)opts->build_id_bytes;
   (void)opts->build_id_len;
   *out = s;
   return KIT_OK;
 }
 
 typedef struct LinkAddObjArg {
   KitObjBuilder* ob;
 } LinkAddObjArg;
 
 static void link_session_add_obj_inner(KitLinkSession* s, void* arg) {
   LinkAddObjArg* a = (LinkAddObjArg*)arg;
   link_add_obj(s->linker, (ObjBuilder*)a->ob);
 }
 
 KitStatus kit_link_session_add_obj(KitLinkSession* s, KitObjBuilder* ob) {
   LinkAddObjArg arg;
   KitStatus st;
   if (!s || !ob || s->resolved) return KIT_INVALID;
   arg.ob = ob;
   st = link_session_guard(s, link_session_add_obj_inner, &arg);
   if (st != KIT_OK) return st;
   return link_session_remember_publish_obj(s, ob);
 }
 
 typedef struct LinkAddBytesArg {
   KitSlice name;
   const KitSlice* bytes;
   const KitLinkArchiveInput* archive;
 } LinkAddBytesArg;
 
 static void link_session_add_obj_bytes_inner(KitLinkSession* s, void* arg) {
   LinkAddBytesArg* a = (LinkAddBytesArg*)arg;
   link_add_obj_bytes(s->linker, a->name.s, a->bytes->data, a->bytes->len);
 }
 
 KitStatus kit_link_session_add_obj_bytes(KitLinkSession* s, KitSlice name,
                                          const KitSlice* bytes) {
   LinkAddBytesArg arg;
   if (!s || !bytes || s->resolved) return KIT_INVALID;
   arg.name = name;
   arg.bytes = bytes;
   arg.archive = NULL;
   s->non_obj_inputs++;
   return link_session_guard(s, link_session_add_obj_bytes_inner, &arg);
 }
 
 static void link_session_add_archive_bytes_inner(KitLinkSession* s, void* arg) {
   const KitLinkArchiveInput* a = ((LinkAddBytesArg*)arg)->archive;
   link_add_archive_bytes(s->linker, a->name.s, a->bytes.data, a->bytes.len,
                          a->whole_archive, a->link_mode, a->group_id);
 }
 
 KitStatus kit_link_session_add_archive_bytes(
     KitLinkSession* s, const KitLinkArchiveInput* archive) {
   LinkAddBytesArg arg;
   if (!s || !archive || s->resolved) return KIT_INVALID;
   arg.bytes = NULL;
   arg.archive = archive;
   s->non_obj_inputs++;
   return link_session_guard(s, link_session_add_archive_bytes_inner, &arg);
 }
 
 static void link_session_add_dso_bytes_inner(KitLinkSession* s, void* arg) {
   LinkAddBytesArg* a = (LinkAddBytesArg*)arg;
   link_add_dso_bytes(s->linker, a->name.s, a->bytes->data, a->bytes->len);
 }
 
 KitStatus kit_link_session_add_dso_bytes(KitLinkSession* s, KitSlice name,
                                          const KitSlice* bytes) {
   LinkAddBytesArg arg;
   if (!s || !bytes || s->resolved) return KIT_INVALID;
   arg.name = name;
   arg.bytes = bytes;
   arg.archive = NULL;
   s->non_obj_inputs++;
   return link_session_guard(s, link_session_add_dso_bytes_inner, &arg);
 }
 
 typedef struct LinkLtoPreserveArg {
   KitObjBuilder* lto_obj;
   KitCg* lto_cg;
   KitLinkLtoPreservedCallback cb;
   void* user;
 } LinkLtoPreserveArg;
 
 typedef struct LinkLtoRefMark {
   ObjSymId sym;
   u8 referenced;
   u8 pad[3];
 } LinkLtoRefMark;
 
 typedef struct LinkLtoRefMarks {
   Compiler* c;
   ObjBuilder* ob;
   LinkLtoRefMark* marks;
   u32 nmarks;
   u32 cap;
 } LinkLtoRefMarks;
 
 static int link_lto_sym_is_logical_undef(const ObjSym* s) {
   return s && s->section_id == OBJ_SEC_NONE && s->kind != SK_ABS &&
          s->kind != SK_COMMON;
 }
 
 static int link_lto_sym_is_preservable_def(const ObjSym* s) {
   return s && !s->removed && s->name != 0 && s->bind != SB_LOCAL &&
          link_sym_is_def(s);
 }
 
 static void link_lto_preserve_name(LinkLtoPreserveArg* a, Sym name) {
   ObjSymIter* it;
   ObjSymEntry e;
   if (!a || !name) return;
   it = obj_symiter_new((ObjBuilder*)a->lto_obj);
   while (it && obj_symiter_next(it, &e)) {
     const ObjSym* s = e.sym;
     if (!s || s->name != name) continue;
     if (link_lto_sym_is_preservable_def(s)) a->cb(a->user, (KitCgSym)e.id);
   }
   if (it) obj_symiter_free(it);
 }
 
 static int link_lto_sym_in_preserved_section(ObjBuilder* ob, ObjSymId sym,
                                              const ObjSym* s) {
   const Section* sec;
   const ObjAtom* atom;
   ObjAtomId aid;
   if (!ob || !s) return 0;
   if (s->section_id == OBJ_SEC_NONE) return 0;
   sec = obj_section_get(ob, s->section_id);
   if (sec && ((sec->flags & SF_RETAIN) || sec->sem == SSEM_INIT_ARRAY ||
               sec->sem == SSEM_FINI_ARRAY || sec->sem == SSEM_PREINIT_ARRAY))
     return 1;
   aid = obj_atom_find_symbol(ob, sym);
   atom = obj_atom_get(ob, aid);
   return atom && (atom->flags & OBJ_ATOM_RETAIN);
 }
 
 static void link_lto_refmarks_add(LinkLtoRefMarks* marks, ObjSymId sym,
                                   const ObjSym* s) {
   Heap* h;
   LinkLtoRefMark* nm;
   u32 ncap;
   if (!marks || sym == OBJ_SYM_NONE || !s) return;
   for (u32 i = 0; i < marks->nmarks; ++i)
     if (marks->marks[i].sym == sym) return;
   if (marks->nmarks == marks->cap) {
     h = marks->c->ctx->heap;
     ncap = marks->cap ? marks->cap * 2u : 32u;
     nm = (LinkLtoRefMark*)h->realloc(
         h, marks->marks, sizeof(*marks->marks) * marks->cap,
         sizeof(*marks->marks) * ncap, _Alignof(LinkLtoRefMark));
     if (!nm)
       compiler_panic(marks->c, SRCLOC_NONE,
                      "link: oom on LTO semantic-ref marks");
     marks->marks = nm;
     marks->cap = ncap;
   }
   marks->marks[marks->nmarks].sym = sym;
   marks->marks[marks->nmarks].referenced = s->referenced ? 1u : 0u;
   marks->nmarks++;
 }
 
 static void link_lto_mark_refset(ObjBuilder* ob, const ObjSymSet* refs,
                                  LinkLtoRefMarks* marks) {
   if (!ob || !refs || !refs->cap) return;
   for (u32 i = 0; i < refs->cap; ++i) {
     ObjSymId sym = refs->slots[i].k;
     const ObjSym* s;
     if (sym == OBJ_SYM_NONE) continue;
     s = obj_symbol_get(ob, sym);
     if (link_lto_sym_is_logical_undef(s)) {
       link_lto_refmarks_add(marks, sym, s);
       obj_sym_mark_referenced(ob, sym);
     }
   }
 }
 
 static int link_lto_module_has_asm(const CgIrModule* module) {
   if (!module) return 0;
   if (module->nfile_scope_asms) return 1;
   for (u32 i = 0; i < module->nfuncs; ++i) {
     const CgIrFunc* f = module->funcs[i];
     if (!f || f->removed) continue;
     for (u32 k = 0; k < f->ninsts; ++k)
       if (f->insts[k].op == CG_IR_ASM_BLOCK) return 1;
   }
   return 0;
 }
 
 static void link_lto_mark_semantic_refs(LinkLtoPreserveArg* a,
                                         LinkLtoRefMarks* marks) {
   ObjBuilder* ob = (ObjBuilder*)a->lto_obj;
   const CgIrModule* module;
   if (!a->lto_cg || !a->lto_cg->target) return;
   module = cg_ir_recorder_module(a->lto_cg->target);
   if (!module) return;
   for (u32 i = 0; i < module->nfuncs; ++i) {
     const CgIrFunc* f = module->funcs[i];
     if (!f || f->removed) continue;
     link_lto_mark_refset(ob, &f->call_refs, marks);
     link_lto_mark_refset(ob, &f->global_refs, marks);
   }
 }
 
 static void link_lto_refmarks_restore(LinkLtoRefMarks* marks) {
   if (!marks || !marks->ob) return;
   for (u32 i = 0; i < marks->nmarks; ++i) {
     obj_sym_set_referenced(marks->ob, marks->marks[i].sym,
                            marks->marks[i].referenced);
   }
 }
 
 static void link_lto_refmarks_fini(LinkLtoRefMarks* marks) {
   Heap* h;
   if (!marks || !marks->marks) return;
   h = marks->c->ctx->heap;
   h->free(h, marks->marks, sizeof(*marks->marks) * marks->cap);
   memset(marks, 0, sizeof(*marks));
 }
 
 static void link_lto_preserve_intrinsic_roots(KitLinkSession* s,
                                               LinkLtoPreserveArg* a) {
   ObjBuilder* ob = (ObjBuilder*)a->lto_obj;
   const CgIrModule* module = NULL;
   int preserve_all_nonlocal = 0;
   ObjSymIter* it;
   ObjSymEntry e;
 
   if (a->lto_cg && a->lto_cg->target)
     module = cg_ir_recorder_module(a->lto_cg->target);
 
   preserve_all_nonlocal = s->opts.output_kind != KIT_LINK_OUTPUT_EXE ||
                           link_lto_module_has_asm(module);
   if (s->opts.output_kind == KIT_LINK_OUTPUT_SHARED) preserve_all_nonlocal = 1;
 
   it = obj_symiter_new(ob);
   while (it && obj_symiter_next(it, &e)) {
     const ObjSym* os = e.sym;
     if (!link_lto_sym_is_preservable_def(os)) continue;
     if (preserve_all_nonlocal || os->bind == SB_WEAK || os->kind == SK_IFUNC ||
         (os->flags & KIT_CG_SYM_USED) ||
         link_lto_sym_in_preserved_section(ob, e.id, os)) {
       a->cb(a->user, (KitCgSym)e.id);
     }
   }
   if (it) obj_symiter_free(it);
 
   if (s->linker->entry_name) link_lto_preserve_name(a, s->linker->entry_name);
   for (u32 i = 0; i < s->opts.nexports; ++i) {
     const KitSlice* ex = &s->opts.exports[i];
     if (ex->s && ex->len)
       link_lto_preserve_name(
           a,
           pool_intern_slice(s->c->global, (Slice){.s = ex->s, .len = ex->len}));
   }
 }
 
 static void link_lto_preserve_opaque_undef_refs(KitLinkSession* s,
                                                 LinkLtoPreserveArg* a) {
   u32 ninputs = LinkInputs_count(&s->linker->inputs);
   for (u32 ii = 0; ii < ninputs; ++ii) {
     LinkInput* in = LinkInputs_at(&s->linker->inputs, ii);
     ObjSymIter* it;
     ObjSymEntry e;
     if (!in || !in->obj || in->obj == (ObjBuilder*)a->lto_obj) continue;
     it = obj_symiter_new(in->obj);
     while (it && obj_symiter_next(it, &e)) {
       const ObjSym* os = e.sym;
       if (!os || os->name == 0 || os->bind == SB_LOCAL) continue;
       if (link_sym_is_spurious_undef(os)) continue;
       if (!link_lto_sym_is_logical_undef(os)) continue;
       link_lto_preserve_name(a, os->name);
     }
     if (it) obj_symiter_free(it);
   }
 }
 
 static void link_session_visit_lto_preserved_inner(KitLinkSession* s,
                                                    void* arg) {
   LinkLtoPreserveArg* a = (LinkLtoPreserveArg*)arg;
   LinkLtoRefMarks marks;
   memset(&marks, 0, sizeof marks);
   marks.c = s->c;
   marks.ob = (ObjBuilder*)a->lto_obj;
   if (s->opts.output_kind != KIT_LINK_OUTPUT_RELOCATABLE) {
     /* Archive selection needs pre-finish semantic refs, but those refs may
      * disappear after LTO internalization/DCE. Borrow ObjSym::referenced only
      * for archive ingestion, then restore it before CG finish. */
     link_lto_mark_semantic_refs(a, &marks);
     link_ingest_archives(s->linker);
     link_lto_refmarks_restore(&marks);
     link_lto_refmarks_fini(&marks);
   }
   link_lto_preserve_intrinsic_roots(s, a);
   link_lto_preserve_opaque_undef_refs(s, a);
 }
 
 KitStatus kit_link_session_visit_lto_preserved(KitLinkSession* s,
                                                KitObjBuilder* lto_obj,
                                                KitCg* lto_cg,
                                                KitLinkLtoPreservedCallback cb,
                                                void* user) {
   LinkLtoPreserveArg arg;
   if (!s || !lto_obj || !lto_cg || !cb || s->resolved) return KIT_INVALID;
   memset(&arg, 0, sizeof arg);
   arg.lto_obj = lto_obj;
   arg.lto_cg = lto_cg;
   arg.cb = cb;
   arg.user = user;
   return link_session_guard(s, link_session_visit_lto_preserved_inner, &arg);
 }
 
 static void link_session_resolve_inner(KitLinkSession* s, void* arg) {
   (void)arg;
   if ((KitLinkOutputKind)s->opts.output_kind == KIT_LINK_OUTPUT_RELOCATABLE) {
     s->resolved = 1;
     return;
   }
   s->image = link_resolve(s->linker);
   s->resolved = 1;
 }
 
 KitStatus kit_link_session_resolve(KitLinkSession* s) {
   if (!s || s->resolved) return KIT_INVALID;
   return link_session_guard(s, link_session_resolve_inner, NULL);
 }
 
 static KitStatus link_report_write(KitWriter* out, const char* s, size_t n) {
   return n ? kit_writer_write(out, s, n) : KIT_OK;
 }
 
 static KitStatus link_report_cstr(KitWriter* out, const char* s) {
   return link_report_write(out, s, s ? strlen(s) : 0);
 }
 
 static KitStatus link_report_slice(KitWriter* out, KitSlice s) {
   return link_report_write(out, s.s, s.s ? s.len : 0);
 }
 
 static KitStatus link_reportf(KitWriter* out, const char* fmt, ...) {
   char buf[512];
   va_list ap;
   int n;
   va_start(ap, fmt);
   n = vsnprintf(buf, sizeof(buf), fmt, ap);
   va_end(ap);
   if (n < 0) return KIT_ERR;
   if ((size_t)n >= sizeof(buf)) return KIT_UNSUPPORTED;
   return link_report_write(out, buf, (size_t)n);
 }
 
 static const char* link_report_output_kind(uint8_t kind) {
   switch ((KitLinkOutputKind)kind) {
     case KIT_LINK_OUTPUT_EXE:
       return "exe";
     case KIT_LINK_OUTPUT_SHARED:
       return "shared";
     case KIT_LINK_OUTPUT_RELOCATABLE:
       return "relocatable";
     case KIT_LINK_OUTPUT_JIT:
       return "jit";
   }
   return "unknown";
 }
 
 static KitSlice link_report_sym_name(LinkImage* img, Sym name) {
   return name ? pool_slice(img->c->global, name) : KIT_SLICE_NULL;
 }
 
 static int link_report_slice_cmp(KitSlice a, KitSlice b) {
   size_t n = a.len < b.len ? a.len : b.len;
   int c = n ? memcmp(a.s, b.s, n) : 0;
   if (c) return c;
   if (a.len < b.len) return -1;
   if (a.len > b.len) return 1;
   return 0;
 }
 
 static int link_report_symbol_include(const LinkImage* img,
                                       const LinkSymbol* s) {
   if (!s || !s->name || !s->defined || s->imported) return 0;
   if (s->kind == SK_FILE || s->kind == SK_SECTION) return 0;
   if (s->bind != SB_LOCAL && !link_symbol_is_canonical_global(img, s)) return 0;
   return 1;
 }
 
 typedef struct LinkReportSymbols {
   LinkSymId* ids;
   u32 n;
   u32 cap;
 } LinkReportSymbols;
 
 static int link_report_symbol_cmp(LinkImage* img, LinkSymId a, LinkSymId b) {
   const LinkSymbol* sa = LinkSyms_at(&img->syms, a - 1u);
   const LinkSymbol* sb = LinkSyms_at(&img->syms, b - 1u);
   KitSlice na;
   KitSlice nb;
   if (sa->vaddr < sb->vaddr) return -1;
   if (sa->vaddr > sb->vaddr) return 1;
   na = link_report_sym_name(img, sa->name);
   nb = link_report_sym_name(img, sb->name);
   return link_report_slice_cmp(na, nb);
 }
 
 static KitStatus link_report_collect_symbols(LinkImage* img,
                                              LinkReportSymbols* out) {
   Heap* h = img->heap;
   u32 i;
   memset(out, 0, sizeof(*out));
   out->cap = LinkSyms_count(&img->syms);
   if (!out->cap) return KIT_OK;
   out->ids =
       (LinkSymId*)h->alloc(h, sizeof(*out->ids) * out->cap, _Alignof(LinkSymId));
   if (!out->ids) return KIT_NOMEM;
   for (i = 0; i < out->cap; ++i) {
     const LinkSymbol* s = LinkSyms_at(&img->syms, i);
     if (link_report_symbol_include(img, s)) out->ids[out->n++] = s->id;
   }
   for (i = 1; i < out->n; ++i) {
     LinkSymId key = out->ids[i];
     u32 j = i;
     while (j > 0 && link_report_symbol_cmp(img, key, out->ids[j - 1u]) < 0) {
       out->ids[j] = out->ids[j - 1u];
       --j;
     }
     out->ids[j] = key;
   }
   return KIT_OK;
 }
 
 static void link_report_free_symbols(LinkImage* img, LinkReportSymbols* syms) {
   if (syms->ids)
     img->heap->free(img->heap, syms->ids,
                     sizeof(*syms->ids) * syms->cap);
   memset(syms, 0, sizeof(*syms));
 }
 
 static char link_report_symbol_type(const LinkImage* img,
                                     const LinkSymbol* s) {
   char t = 'N';
   const LinkSection* sec = NULL;
   if (!s->defined) {
     t = 'U';
   } else if (s->kind == SK_ABS) {
     t = 'A';
   } else if (s->kind == SK_COMMON) {
     t = 'C';
   } else if (s->kind == SK_FUNC || s->kind == SK_IFUNC) {
     t = 'T';
   } else {
     if (s->section_id != LINK_SEC_NONE && s->section_id <= img->nsections)
       sec = &img->sections[s->section_id - 1u];
     if (s->kind == SK_TLS) {
       t = 'D';
     } else if (sec && sec->sem == SSEM_NOBITS) {
       t = 'B';
     } else if (sec && (sec->flags & SF_EXEC)) {
       t = 'T';
     } else if (sec && (sec->flags & SF_WRITE)) {
       t = 'D';
     } else if (sec && (sec->flags & SF_ALLOC)) {
       t = 'R';
     }
   }
   if (s->bind == SB_WEAK) {
     if (t == 'D' || t == 'B' || t == 'R')
       t = 'V';
     else if (t != 'U')
       t = 'W';
   } else if (s->bind == SB_LOCAL && t >= 'A' && t <= 'Z') {
     t = (char)(t - 'A' + 'a');
   }
   return t;
 }
 
 /* Final runtime address of a symbol, mirroring the ELF emitter's st_value
  * rule: SK_FILE / undefined carry 0; SK_ABS carries its own value verbatim;
  * every other defined symbol is image-relative and gets img->load_base added
  * (0 for PIE/scripted, the static base or -Ttext override otherwise). Keeps
  * the side-files consistent with the produced binary's symbol table. */
 static u64 link_report_final_addr(const LinkImage* img, const LinkSymbol* s) {
   if (s->kind == SK_FILE || !s->defined) return 0;
   if (s->kind == SK_ABS) return s->vaddr;
   return img->load_base + s->vaddr;
 }
 
 static KitStatus link_report_write_symbol_line(LinkImage* img, KitWriter* out,
                                                const LinkSymbol* s) {
   KitSlice name = link_report_sym_name(img, s->name);
   KitStatus st = link_reportf(out, "%016llx %c ",
                               (unsigned long long)link_report_final_addr(img, s),
                               link_report_symbol_type(img, s));
   if (st != KIT_OK) return st;
   st = link_report_slice(out, name);
   if (st != KIT_OK) return st;
   return link_report_cstr(out, "\n");
 }
 
 static KitStatus link_report_write_symbols_nm(LinkImage* img, KitWriter* out) {
   LinkReportSymbols syms;
   KitStatus st;
   u32 i;
   st = link_report_collect_symbols(img, &syms);
   if (st != KIT_OK) return st;
   for (i = 0; i < syms.n; ++i) {
     const LinkSymbol* s = LinkSyms_at(&img->syms, syms.ids[i] - 1u);
     st = link_report_write_symbol_line(img, out, s);
     if (st != KIT_OK) break;
   }
   link_report_free_symbols(img, &syms);
   return st == KIT_OK ? kit_writer_status(out) : st;
 }
 
 /* Normalize a (possibly absolute) input path to its basename so map/side files
  * stay byte-identical regardless of where the inputs live on disk (an absolute
  * host path would leak the build directory and break determinism). */
 static KitSlice link_report_normalize_path(KitSlice raw) {
   size_t i;
   size_t base = 0;
   if (!raw.s || raw.len == 0) return raw;
   for (i = 0; i < raw.len; ++i)
     if (raw.s[i] == '/' || raw.s[i] == '\\') base = i + 1u;
   if (base >= raw.len) return raw; /* trailing separator: keep as-is */
   raw.s += base;
   raw.len -= base;
   return raw;
 }
 
 static KitSlice link_report_input_name(LinkImage* img, LinkInputId id) {
   LinkInput* in;
   KitSlice raw;
   if (!img || !img->linker || id == LINK_INPUT_NONE ||
       id > LinkInputs_count(&img->linker->inputs))
     return KIT_SLICE_NULL;
   in = LinkInputs_at(&img->linker->inputs, id - 1u);
   if (!in || !in->name) return KIT_SLICE_NULL;
   raw = pool_slice(img->c->global, in->name);
   return link_report_normalize_path(raw);
 }
 
 /* Discarded sections: input sections that are layout candidates
  * (link_section_kept) but did not land in the final image — dropped by
  * --gc-sections, retired as a COMDAT duplicate, or otherwise unplaced. Walks
  * the per-input maps in input/section order for determinism, and reports the
  * normalized input name so no absolute host path leaks. */
 static KitStatus link_report_write_discarded(LinkImage* img, KitWriter* out) {
   KitStatus st;
   u32 ii;
   if (!img || !img->linker) return KIT_OK;
   st = link_report_cstr(out, "\ndiscarded\n");
   if (st != KIT_OK) return st;
   for (ii = 0; ii < LinkInputs_count(&img->linker->inputs); ++ii) {
     LinkInput* in = LinkInputs_at(&img->linker->inputs, ii);
     InputMap* m = (ii < img->ninput_maps) ? &img->input_maps[ii] : NULL;
     ObjBuilder* ob = in ? in->obj : NULL;
     KitSlice input;
     u32 j, n;
     if (!ob || !m) continue;
     if (in->kind == LINK_INPUT_DSO_BYTES) continue;
     input = link_report_input_name(img, in->id);
     n = obj_section_count(ob);
     for (j = 1; j < n; ++j) {
       const Section* sec = obj_section_get(ob, j);
       int dropped;
       if (!sec || sec->removed || !link_section_kept(sec)) continue;
       dropped = (m->comdat_discarded && j < m->nsection && m->comdat_discarded[j]) ||
                 (m->section && j < m->nsection && m->section[j] == LINK_SEC_NONE);
       if (!dropped) continue;
       st = link_report_cstr(out, "  ");
       if (st != KIT_OK) return st;
       {
         KitSlice nm = sec->name ? link_report_sym_name(img, sec->name)
                                 : KIT_SLICE_NULL;
         st = nm.s ? link_report_slice(out, nm) : link_report_cstr(out, "-");
         if (st != KIT_OK) return st;
       }
       if (input.s && input.len) {
         st = link_report_cstr(out, " input=");
         if (st != KIT_OK) return st;
         st = link_report_slice(out, input);
         if (st != KIT_OK) return st;
       }
       st = link_report_cstr(out, "\n");
       if (st != KIT_OK) return st;
     }
   }
   return KIT_OK;
 }
 
 /* Unresolved symbols: image symbols that remain undefined and unimported
  * after resolution (only reachable when the link is permissive, e.g.
  * --allow-undefined; a strict link panics instead). Sorted by name for a
  * deterministic listing. */
 static KitStatus link_report_write_unresolved(LinkImage* img, KitWriter* out) {
   KitStatus st;
   Heap* h = img->heap;
   LinkSymId* ids = NULL;
   u32 n = 0, cap, i;
   if (!img) return KIT_OK;
   st = link_report_cstr(out, "\nunresolved\n");
   if (st != KIT_OK) return st;
   cap = LinkSyms_count(&img->syms);
   if (!cap) return KIT_OK;
   ids = (LinkSymId*)h->alloc(h, sizeof(*ids) * cap, _Alignof(LinkSymId));
   if (!ids) return KIT_NOMEM;
   for (i = 0; i < cap; ++i) {
     const LinkSymbol* s = LinkSyms_at(&img->syms, i);
     if (!s || s->name == 0) continue;
     if (s->defined || s->imported) continue;
     if (s->kind == SK_FILE || s->kind == SK_SECTION) continue;
     ids[n++] = s->id;
   }
   /* Insertion sort by name (small lists; deterministic). */
   for (i = 1; i < n; ++i) {
     LinkSymId key = ids[i];
     KitSlice kn = link_report_sym_name(
         img, LinkSyms_at(&img->syms, key - 1u)->name);
     u32 j = i;
     while (j > 0) {
       KitSlice pn = link_report_sym_name(
           img, LinkSyms_at(&img->syms, ids[j - 1u] - 1u)->name);
       if (link_report_slice_cmp(pn, kn) <= 0) break;
       ids[j] = ids[j - 1u];
       --j;
     }
     ids[j] = key;
   }
   for (i = 0; i < n; ++i) {
     const LinkSymbol* s = LinkSyms_at(&img->syms, ids[i] - 1u);
     KitSlice nm = link_report_sym_name(img, s->name);
     st = link_report_cstr(out, "  ");
     if (st == KIT_OK) st = link_report_slice(out, nm);
     if (st == KIT_OK) st = link_report_cstr(out, "\n");
     if (st != KIT_OK) break;
   }
   h->free(h, ids, sizeof(*ids) * cap);
   return st;
 }
 
 static KitStatus link_report_write_map_image(KitLinkSession* s,
                                              KitWriter* out) {
   LinkImage* img = s->image;
   char triple[96];
   KitStatus st;
   u32 i;
   if (!img) return KIT_INVALID;
   if (!kit_target_to_triple(img->c->target, triple, sizeof(triple)))
     strcpy(triple, "unknown");
   st = link_reportf(out,
                     "target %s\n"
                     "output %s\n",
                     triple, link_report_output_kind(s->opts.output_kind));
   if (st != KIT_OK) return st;
   if (img->entry_sym != LINK_SYM_NONE) {
     const LinkSymbol* es = LinkSyms_at(&img->syms, img->entry_sym - 1u);
     KitSlice name = link_report_sym_name(img, es->name);
     st = link_report_cstr(out, "entry ");
     if (st != KIT_OK) return st;
     st = link_report_slice(out, name);
     if (st != KIT_OK) return st;
     st = link_reportf(out, " 0x%llx\n",
                       (unsigned long long)link_report_final_addr(img, es));
     if (st != KIT_OK) return st;
   } else {
     st = link_report_cstr(out, "entry -\n");
     if (st != KIT_OK) return st;
   }
 
   st = link_report_cstr(out, "\nsegments\n");
   if (st != KIT_OK) return st;
   /* The synthesized read-only headers load segment (ehdr+phdrs) maps at the
    * image base ahead of the content segments; the format emitter records it
    * so the map shows where the image actually loads (e.g. a -Ttext base). */
   if (img->headers_present) {
     st = link_reportf(out,
                       "  [0] r-- off=0x0 vaddr=0x%llx "
                       "filesz=0x%llx memsz=0x%llx align=0x%x\n",
                       (unsigned long long)img->load_base,
                       (unsigned long long)img->headers_filesz,
                       (unsigned long long)img->headers_memsz,
                       img->headers_align);
     if (st != KIT_OK) return st;
   }
   for (i = 0; i < img->nsegments; ++i) {
     const LinkSegment* seg = &img->segments[i];
     char w = (seg->flags & SF_WRITE) ? 'w' : '-';
     char x = (seg->flags & SF_EXEC) ? 'x' : '-';
     st = link_reportf(out,
                       "  [%u] r%c%c off=0x%llx vaddr=0x%llx "
                       "filesz=0x%llx memsz=0x%llx align=0x%x\n",
                       seg->id, w, x, (unsigned long long)seg->file_offset,
                       (unsigned long long)(img->load_base + seg->vaddr),
                       (unsigned long long)seg->file_size,
                       (unsigned long long)seg->mem_size, seg->align);
     if (st != KIT_OK) return st;
   }
 
   st = link_report_cstr(out, "\nsections\n");
   if (st != KIT_OK) return st;
   for (i = 0; i < img->nsections; ++i) {
     const LinkSection* sec = &img->sections[i];
     KitSlice name = link_report_sym_name(img, sec->name);
     KitSlice input = link_report_input_name(img, sec->input_id);
     int loaded = !(sec->file_only || sec->segment_id == LINK_SEG_NONE);
     /* Loaded sections report their final runtime address; file-only debug
      * sections aren't mapped (sh_addr 0), so leave their image-relative
      * bookkeeping vaddr untouched rather than biasing it by the load base. */
     u64 sec_vaddr = loaded ? img->load_base + sec->vaddr : sec->vaddr;
     /* LMA (load-memory address): where the section's initialized bytes load.
      * Equals the VMA for the common case; differs only when the section's
      * segment declares a distinct load region (a script `AT>` clause, which
      * sets the segment paddr apart from its vaddr). */
     u64 sec_lma = sec_vaddr;
     if (loaded && sec->segment_id <= img->nsegments) {
       const LinkSegment* seg = &img->segments[sec->segment_id - 1u];
       if (seg->paddr != seg->vaddr)
         sec_lma = img->load_base + seg->paddr + (sec->vaddr - seg->vaddr);
     }
     st = link_reportf(out,
                       "  [%u] ", sec->id);
     if (st != KIT_OK) return st;
     st = name.s ? link_report_slice(out, name) : link_report_cstr(out, "-");
     if (st != KIT_OK) return st;
     st = link_reportf(out,
                       " seg=%u off=0x%llx vaddr=0x%llx lma=0x%llx size=0x%llx "
                       "align=0x%x",
                       sec->segment_id, (unsigned long long)sec->file_offset,
                       (unsigned long long)sec_vaddr,
                       (unsigned long long)sec_lma,
                       (unsigned long long)sec->size, sec->align);
     if (st != KIT_OK) return st;
     if (input.s && input.len) {
       st = link_report_cstr(out, " input=");
       if (st != KIT_OK) return st;
       st = link_report_slice(out, input);
       if (st != KIT_OK) return st;
     }
     st = link_report_cstr(out, "\n");
     if (st != KIT_OK) return st;
   }
 
   st = link_report_write_discarded(img, out);
   if (st != KIT_OK) return st;
   st = link_report_write_unresolved(img, out);
   if (st != KIT_OK) return st;
 
   st = link_report_cstr(out, "\nsymbols\n");
   if (st != KIT_OK) return st;
   return link_report_write_symbols_nm(img, out);
 }
 
 /* --cref predicate: a symbol participates in the cross-reference table when it
  * is a named non-FILE/non-SECTION global that is either locally defined OR
  * imported from a DSO. Imported (DSO-resolved) externals are exactly the
  * cross-references a cref table exists to show, so — unlike the nm-style
  * "symbols" listing's link_report_symbol_include — they are NOT dropped. */
 static int link_report_cref_include(const LinkSymbol* s) {
   if (!s || !s->name) return 0;
   if (s->kind == SK_FILE || s->kind == SK_SECTION) return 0;
   return (s->defined && !s->imported) || s->imported;
 }
 
 /* --cref: cross-reference table. For each defined-or-imported global/weak
  * symbol (deduped by name, sorted by name for determinism) emit the defining
  * file — the providing DSO basename for an imported symbol, the defining object
  * otherwise — then the set of distinct input files that reference it via a
  * relocation. Input names are normalized to basenames. The symbol set is built
  * INDEPENDENTLY of the nm-style "symbols" listing so imports are included. */
 static KitStatus link_report_write_cref_image(KitLinkSession* s,
                                               KitWriter* out) {
   LinkImage* img = s->image;
   Heap* h;
   LinkSymId* ids = NULL;
   u32 n = 0, cap, i;
   KitStatus st;
   if (!img) return KIT_INVALID;
   h = img->heap;
   st = link_report_cstr(out, "cross reference table\n");
   if (st != KIT_OK) return st;
   cap = LinkSyms_count(&img->syms);
   if (!cap) return kit_writer_status(out);
   ids = (LinkSymId*)h->alloc(h, sizeof(*ids) * cap, _Alignof(LinkSymId));
   if (!ids) return KIT_NOMEM;
   /* Collect one canonical slot per qualifying name, deduped by Sym (the
    * interned name handle): a name's first qualifying slot wins. Prefer a
    * locally-defined slot over an imported one when both exist (so a symbol that
    * is both defined and referenced through a DSO reports its real def). */
   for (i = 0; i < cap; ++i) {
     const LinkSymbol* sy = LinkSyms_at(&img->syms, i);
     u32 k;
     int seen = 0;
     if (!link_report_cref_include(sy)) continue;
     for (k = 0; k < n; ++k) {
       LinkSymbol* prev = LinkSyms_at(&img->syms, ids[k] - 1u);
       if (prev->name != sy->name) continue;
       seen = 1;
       /* Upgrade a previously-recorded imported slot to a real definition. */
       if (sy->defined && !sy->imported && (!prev->defined || prev->imported))
         ids[k] = sy->id;
       break;
     }
     if (!seen) ids[n++] = sy->id;
   }
   /* Insertion sort by name (small lists; deterministic). */
   for (i = 1; i < n; ++i) {
     LinkSymId key = ids[i];
     KitSlice kn =
         link_report_sym_name(img, LinkSyms_at(&img->syms, key - 1u)->name);
     u32 j = i;
     while (j > 0) {
       KitSlice pn = link_report_sym_name(
           img, LinkSyms_at(&img->syms, ids[j - 1u] - 1u)->name);
       if (link_report_slice_cmp(pn, kn) <= 0) break;
       ids[j] = ids[j - 1u];
       --j;
     }
     ids[j] = key;
   }
   for (i = 0; i < n; ++i) {
     const LinkSymbol* sym = LinkSyms_at(&img->syms, ids[i] - 1u);
     KitSlice name = link_report_sym_name(img, sym->name);
     KitSlice deffile;
     LinkInputId defining_input = LINK_INPUT_NONE;
     u32 r, k;
     LinkInputId last = LINK_INPUT_NONE;
     if (sym->imported) {
       /* Imported symbol: the "definition" is the providing DSO input. */
       defining_input = sym->dso_input_id;
     } else {
       /* Find the defining file: the canonical global slot (img->globals) is the
        * real definition; resolution copies its value into per-input reference
        * slots, so scanning slots by `defined` alone would mis-attribute. Fall
        * back to any defined same-name slot for locals (never in globals). */
       LinkSymId canon = symhash_get(&img->globals, sym->name);
       if (canon != LINK_SYM_NONE) {
         const LinkSymbol* c = LinkSyms_at(&img->syms, canon - 1u);
         if (c->defined && !c->imported) defining_input = c->input_id;
       }
       if (defining_input == LINK_INPUT_NONE) {
         for (k = 0; k < cap; ++k) {
           const LinkSymbol* c = LinkSyms_at(&img->syms, k);
           if (c->name != sym->name) continue;
           if (c->defined && !c->imported && c->input_id != LINK_INPUT_NONE) {
             defining_input = c->input_id;
             break;
           }
         }
       }
     }
     deffile = link_report_input_name(img, defining_input);
     st = link_report_slice(out, name);
     if (st == KIT_OK) st = link_report_cstr(out, "\n");
     if (st != KIT_OK) break;
     /* Defining file. */
     st = link_report_cstr(out, "  def ");
     if (st == KIT_OK)
       st = (deffile.s && deffile.len) ? link_report_slice(out, deffile)
                                       : link_report_cstr(out, "-");
     if (st == KIT_OK) st = link_report_cstr(out, "\n");
     if (st != KIT_OK) break;
     /* Referencing files: scan relocs targeting any same-name slot. The reloc
      * list is already in a deterministic input/section/offset order, so
      * consecutive dedup of input ids gives a stable per-symbol reference set. */
     for (r = 0; r < LinkRelocs_count(&img->relocs); ++r) {
       const LinkRelocApply* ra = LinkRelocs_at(&img->relocs, r);
       const LinkSymbol* tsym;
       KitSlice reffile;
       if (!ra || ra->target == LINK_SYM_NONE) continue;
       tsym = LinkSyms_at(&img->syms, ra->target - 1u);
       if (!tsym || tsym->name != sym->name) continue;
       if (ra->input_id == last) continue;
       last = ra->input_id;
       reffile = link_report_input_name(img, ra->input_id);
       st = link_report_cstr(out, "  ref ");
       if (st == KIT_OK)
         st = (reffile.s && reffile.len) ? link_report_slice(out, reffile)
                                         : link_report_cstr(out, "-");
       if (st == KIT_OK) st = link_report_cstr(out, "\n");
       if (st != KIT_OK) break;
     }
     if (st != KIT_OK) break;
   }
   h->free(h, ids, sizeof(*ids) * cap);
   return st == KIT_OK ? kit_writer_status(out) : st;
 }
 
 /* --print-memory-usage: GNU-ld-style per-MEMORY-region used/free/total. The
  * regions come from the linker script; usage is the total size of placed
  * sections (and BSS zero-fill) whose runtime address falls inside a region's
  * [origin, origin+length) window. */
 static KitStatus link_report_write_memory_usage_image(KitLinkSession* s,
                                                       KitWriter* out) {
   LinkImage* img = s->image;
   const KitLinkScript* script = s->opts.linker_script;
   KitStatus st;
   u32 ri;
   if (!img) return KIT_INVALID;
   st = link_report_cstr(out, "Memory region         Used Size  Region Size  "
                              "%age Used\n");
   if (st != KIT_OK) return st;
   if (!script || script->nregions == 0) return kit_writer_status(out);
   for (ri = 0; ri < script->nregions; ++ri) {
     const KitLinkRegion* rg = &script->regions[ri];
     u64 used = 0;
     u64 free_bytes;
     unsigned pct_int = 0, pct_frac = 0;
     u32 j;
     for (j = 0; j < img->nsegments; ++j) {
       const LinkSegment* seg = &img->segments[j];
       u64 base = img->load_base + seg->vaddr;
       /* Alias / program-header-only segments (nsections==0) describe the SAME
        * bytes as a primary segment under an additional :phdr; charging them
        * would double-count a section placed into multiple PT_LOADs. Real
        * primaries (incl. BSS/COMMON zero-fill) carry nsections>=1, so genuine
        * mem_size stays counted exactly once. */
       if (seg->nsections == 0) continue;
       /* A segment belongs to a region when its load address sits within the
        * [origin, origin+length) window. Count memsz (covers BSS). The end of
        * the window is computed overflow-safe via a subtract — a region that
        * touches the top of the address space (origin+length wraps to 0) would
        * otherwise mis-test `base < 0` and attribute nothing. */
       if (base >= rg->origin &&
           (rg->length == 0 ? 0 : base - rg->origin < rg->length))
         used += seg->mem_size;
     }
     free_bytes = (rg->length > used) ? rg->length - used : 0;
     if (rg->length) {
       /* Two-decimal percentage without floating point: used*10000/length. */
       u64 scaled = (used * 10000ull) / rg->length;
       pct_int = (unsigned)(scaled / 100ull);
       pct_frac = (unsigned)(scaled % 100ull);
     }
     st = link_report_slice(out,
                            rg->name.s ? rg->name : KIT_SLICE_LIT("<unnamed>"));
     if (st == KIT_OK)
       st = link_reportf(out, "  used=0x%llx free=0x%llx total=0x%llx %u.%02u%%\n",
                         (unsigned long long)used,
                         (unsigned long long)free_bytes,
                         (unsigned long long)rg->length, pct_int, pct_frac);
     if (st != KIT_OK) return st;
   }
   return kit_writer_status(out);
 }
 
 typedef struct LinkReportArg {
   KitWriter* out;
   uint8_t format;
   KitStatus st;
 } LinkReportArg;
 
 static void link_session_map_inner(KitLinkSession* s, void* arg) {
   LinkReportArg* a = (LinkReportArg*)arg;
   a->st = link_report_write_map_image(s, a->out);
 }
 
 static void link_session_symbols_inner(KitLinkSession* s, void* arg) {
   LinkReportArg* a = (LinkReportArg*)arg;
   if (a->format != KIT_LINK_SYMBOLS_NM) {
     a->st = KIT_UNSUPPORTED;
     return;
   }
   a->st = link_report_write_symbols_nm(s->image, a->out);
 }
 
 KitStatus kit_link_session_write_map(KitLinkSession* s, KitWriter* out) {
   LinkReportArg arg;
   KitStatus st;
   if (!s || !out) return KIT_INVALID;
   if ((KitLinkOutputKind)s->opts.output_kind == KIT_LINK_OUTPUT_RELOCATABLE ||
       (KitLinkOutputKind)s->opts.output_kind == KIT_LINK_OUTPUT_JIT)
     return KIT_INVALID;
   if (!s->resolved) {
     st = kit_link_session_resolve(s);
     if (st != KIT_OK) return st;
   }
   arg.out = out;
   arg.format = KIT_LINK_SYMBOLS_NM;
   arg.st = KIT_OK;
   st = link_session_guard(s, link_session_map_inner, &arg);
   if (st != KIT_OK) return st;
   return arg.st == KIT_OK ? kit_writer_status(out) : arg.st;
 }
 
 KitStatus kit_link_session_write_symbols(KitLinkSession* s, uint8_t format,
                                          KitWriter* out) {
   LinkReportArg arg;
   KitStatus st;
   if (!s || !out) return KIT_INVALID;
   if ((KitLinkOutputKind)s->opts.output_kind == KIT_LINK_OUTPUT_RELOCATABLE ||
       (KitLinkOutputKind)s->opts.output_kind == KIT_LINK_OUTPUT_JIT)
     return KIT_INVALID;
   if (!s->resolved) {
     st = kit_link_session_resolve(s);
     if (st != KIT_OK) return st;
   }
   arg.out = out;
   arg.format = format;
   arg.st = KIT_OK;
   st = link_session_guard(s, link_session_symbols_inner, &arg);
   if (st != KIT_OK) return st;
   return arg.st == KIT_OK ? kit_writer_status(out) : arg.st;
 }
 
 static void link_session_cref_inner(KitLinkSession* s, void* arg) {
   LinkReportArg* a = (LinkReportArg*)arg;
   a->st = link_report_write_cref_image(s, a->out);
 }
 
 static void link_session_memusage_inner(KitLinkSession* s, void* arg) {
   LinkReportArg* a = (LinkReportArg*)arg;
   a->st = link_report_write_memory_usage_image(s, a->out);
 }
 
 KitStatus kit_link_session_write_cref(KitLinkSession* s, KitWriter* out) {
   LinkReportArg arg;
   KitStatus st;
   if (!s || !out) return KIT_INVALID;
   if ((KitLinkOutputKind)s->opts.output_kind == KIT_LINK_OUTPUT_RELOCATABLE ||
       (KitLinkOutputKind)s->opts.output_kind == KIT_LINK_OUTPUT_JIT)
     return KIT_INVALID;
   if (!s->resolved) {
     st = kit_link_session_resolve(s);
     if (st != KIT_OK) return st;
   }
   arg.out = out;
   arg.format = KIT_LINK_SYMBOLS_NM;
   arg.st = KIT_OK;
   st = link_session_guard(s, link_session_cref_inner, &arg);
   if (st != KIT_OK) return st;
   return arg.st == KIT_OK ? kit_writer_status(out) : arg.st;
 }
 
 KitStatus kit_link_session_write_memory_usage(KitLinkSession* s,
                                               KitWriter* out) {
   LinkReportArg arg;
   KitStatus st;
   if (!s || !out) return KIT_INVALID;
   if ((KitLinkOutputKind)s->opts.output_kind == KIT_LINK_OUTPUT_RELOCATABLE ||
       (KitLinkOutputKind)s->opts.output_kind == KIT_LINK_OUTPUT_JIT)
     return KIT_INVALID;
   if (!s->resolved) {
     st = kit_link_session_resolve(s);
     if (st != KIT_OK) return st;
   }
   arg.out = out;
   arg.format = KIT_LINK_SYMBOLS_NM;
   arg.st = KIT_OK;
   st = link_session_guard(s, link_session_memusage_inner, &arg);
   if (st != KIT_OK) return st;
   return arg.st == KIT_OK ? kit_writer_status(out) : arg.st;
 }
 
 typedef struct LinkEmitArg {
   KitWriter* out;
 } LinkEmitArg;
 
 static void link_session_emit_inner(KitLinkSession* s, void* arg) {
   KitWriter* out = ((LinkEmitArg*)arg)->out;
   if ((KitLinkOutputKind)s->opts.output_kind == KIT_LINK_OUTPUT_RELOCATABLE) {
     link_emit_relocatable_writer(s->linker, out);
   } else {
     link_emit_image_writer(s->image, out);
   }
 }
 
 KitStatus kit_link_session_emit(KitLinkSession* s, KitWriter* out) {
   LinkEmitArg arg;
   KitStatus st;
   if (!s || !out) return KIT_INVALID;
   if (!s->resolved) {
     st = kit_link_session_resolve(s);
     if (st != KIT_OK) return st;
   }
   if ((KitLinkOutputKind)s->opts.output_kind == KIT_LINK_OUTPUT_JIT)
     return KIT_INVALID;
   arg.out = out;
   return link_session_guard(s, link_session_emit_inner, &arg);
 }
 
 typedef struct LinkJitArg {
   KitJit* jit;
 } LinkJitArg;
 
 static void link_session_jit_inner(KitLinkSession* s, void* arg) {
   LinkJitArg* a = (LinkJitArg*)arg;
   a->jit = kit_jit_from_image(s->image);
   if (a->jit) {
     s->image = NULL;
     s->linker_transferred = 1;
     s->linker = NULL;
   }
 }
 
 KitStatus kit_link_session_jit(KitLinkSession* s, KitJit** out_jit) {
   LinkJitArg arg;
   KitStatus st;
   if (!out_jit) return KIT_INVALID;
   *out_jit = NULL;
   if (!s || (KitLinkOutputKind)s->opts.output_kind != KIT_LINK_OUTPUT_JIT)
     return KIT_INVALID;
   if (!s->resolved) {
     st = kit_link_session_resolve(s);
     if (st != KIT_OK) return st;
   }
   arg.jit = NULL;
   st = link_session_guard(s, link_session_jit_inner, &arg);
   if (st != KIT_OK) return st;
   if (!arg.jit) return KIT_ERR;
   *out_jit = arg.jit;
   return KIT_OK;
 }
 
 void kit_link_session_free(KitLinkSession* s) {
   Heap* h;
   if (!s) return;
   h = s->c->ctx->heap;
   if (s->image) link_image_free(s->image);
   if (s->linker) link_free(s->linker);
   if (s->publish_objs) {
     h->free(h, s->publish_objs, sizeof(*s->publish_objs) * s->publish_objs_cap);
   }
   h->free(h, s, sizeof(*s));
 }