kit

compile.c (32809B)

---

 /* libkit's top-level compile entry points. Status-returning shapes
  * that drive the C, asm, and registered-frontend paths. */
 
 #include <kit/cg.h>
 #include <kit/compile.h>
 #include <kit/core.h>
 #include <stdint.h>
 #include <string.h>
 
 #include "api/lang_registry.h"
 #include "arch/arch.h"
 #include "asm/asm.h"
 #include "core/core.h"
 #include "core/heap.h"
 #include "core/metrics.h"
 #include "core/pool.h"
 #include "core/slice.h"
 #include "obj/obj.h"
 
 typedef struct AsmFrontend {
   Compiler* c;
 } AsmFrontend;
 
 struct KitFrontend {
   KitCompiler* c;
   KitLanguage lang;
   const KitFrontendVTable* vtable;
   KitFrontendState* state;
 };
 
 struct KitCompileSession {
   KitCompiler* c;
   KitLanguage lang;
   KitFrontend* frontend;
   KitFrontendCompileOptions opts;
 };
 
 struct KitFrontendRegistry {
   const KitContext* ctx;
   const KitFrontendVTable** frontends;
   uint32_t nfrontends;
   uint32_t cap;
 };
 
 static KitFrontendState* asm_frontend_new(KitCompiler* c);
 static KitStatus asm_frontend_compile(KitFrontendState* fe,
                                       const KitFrontendCompileOptions* opts,
                                       const KitSourceInput* input,
                                       KitObjBuilder* out);
 static void asm_frontend_free(KitFrontendState* fe);
 
 static const KitSlice asm_extensions[] = {KIT_SLICE_LIT("s")};
 /* Canonical `-x` name plus alias; mirrors the driver's "asm"/"s" spellings. */
 static const KitSlice asm_names[] = {KIT_SLICE_LIT("asm"), KIT_SLICE_LIT("s")};
 
 const KitFrontendVTable kit_asm_frontend_vtable = {
     .new_frontend = asm_frontend_new,
     .compile_cg = NULL, /* asm participates in LTO as an opaque object */
     .compile_obj = asm_frontend_compile,
     .free_frontend = asm_frontend_free,
     .extensions = asm_extensions,
     .nextensions = (uint32_t)(sizeof asm_extensions / sizeof asm_extensions[0]),
     .extension_kinds = NULL,
     .names = asm_names,
     .nnames = (uint32_t)(sizeof asm_names / sizeof asm_names[0]),
     .commit = NULL,
     .abort = NULL,
     .caps = {false, KIT_FRONTEND_LTO_OPAQUE, false},
     .parse_options = NULL,
     .free_options = NULL,
 };
 
 static _Noreturn void panic_bad_options(Compiler* c, const char* msg) {
   compiler_panic(c, SRCLOC_NONE, "bad kit options: %.*s",
                  SLICE_ARG(slice_from_cstr(msg)));
 }
 
 /* Compare `ext` to `pat` letter-for-letter, lowercasing ASCII A-Z in
  * the path side so `.S` matches asm's `"s"` entry. `ext` is a borrowed
  * slice over the path tail; `pat` is the frontend's extension slice.
  * Returns nonzero on full match. */
 static int ext_eq_ci(KitSlice ext, KitSlice pat) {
   size_t i;
   if (ext.len != pat.len) return 0;
   for (i = 0; i < ext.len; ++i) {
     char a = ext.s[i];
     char b = pat.s[i];
     if (a >= 'A' && a <= 'Z') a = (char)(a - 'A' + 'a');
     if (a != b) return 0;
   }
   return 1;
 }
 
 static KitStatus validate_frontend_vtable(const KitFrontendVTable* vtable) {
   if (vtable) {
     uint8_t mode = vtable->caps.lto_mode;
     uint32_t i;
     if (!vtable->new_frontend || !vtable->free_frontend ||
         mode > KIT_FRONTEND_LTO_OPAQUE) {
       return KIT_INVALID;
     }
     if (mode == KIT_FRONTEND_LTO_CG) {
       if (!vtable->compile_cg) return KIT_INVALID;
     } else if (!vtable->compile_obj) {
       return KIT_INVALID;
     }
     if (vtable->extension_kinds && vtable->nextensions && !vtable->extensions)
       return KIT_INVALID;
     for (i = 0; vtable->extension_kinds && i < vtable->nextensions; ++i) {
       uint8_t k = vtable->extension_kinds[i];
       if (k != KIT_FRONTEND_PATH_SOURCE && k != KIT_FRONTEND_PATH_HEADER)
         return KIT_INVALID;
     }
   }
   return KIT_OK;
 }
 
 static KitFrontendPathKind vtable_extension_kind(
     const KitFrontendVTable* v, uint32_t index) {
   if (!v || index >= v->nextensions) return KIT_FRONTEND_PATH_UNKNOWN;
   if (!v->extension_kinds) return KIT_FRONTEND_PATH_SOURCE;
   return (KitFrontendPathKind)v->extension_kinds[index];
 }
 
 static KitStatus registry_reserve(KitFrontendRegistry* r, uint32_t want) {
   KitHeap* h;
   const KitFrontendVTable** nv;
   uint32_t ncap;
   uint32_t i;
   if (!r || !r->ctx || !r->ctx->heap) return KIT_INVALID;
   if (want <= r->cap) return KIT_OK;
   h = r->ctx->heap;
   ncap = r->cap ? r->cap : 8u;
   while (ncap < want) {
     if (ncap > UINT32_MAX / 2u) {
       ncap = want;
       break;
     }
     ncap *= 2u;
   }
   if ((size_t)ncap > SIZE_MAX / sizeof(*r->frontends)) return KIT_NOMEM;
   if (r->frontends) {
     nv = (const KitFrontendVTable**)h->realloc(
         h, (void*)r->frontends, r->cap * sizeof(*r->frontends),
         ncap * sizeof(*r->frontends), _Alignof(const KitFrontendVTable*));
   } else {
     nv = (const KitFrontendVTable**)h->alloc(
         h, ncap * sizeof(*r->frontends), _Alignof(const KitFrontendVTable*));
   }
   if (!nv) return KIT_NOMEM;
   for (i = r->cap; i < ncap; ++i) nv[i] = NULL;
   r->frontends = nv;
   r->cap = ncap;
   return KIT_OK;
 }
 
 static KitStatus compiler_frontends_reserve(Compiler* c, uint32_t want) {
   Heap* h;
   const KitFrontendVTable** nv;
   uint32_t ncap;
   uint32_t i;
   if (!c || !c->ctx || !c->ctx->heap) return KIT_INVALID;
   if (want <= c->frontends_cap) return KIT_OK;
   h = (Heap*)c->ctx->heap;
   ncap = c->frontends_cap ? c->frontends_cap : 8u;
   while (ncap < want) {
     if (ncap > UINT32_MAX / 2u) {
       ncap = want;
       break;
     }
     ncap *= 2u;
   }
   if ((size_t)ncap > SIZE_MAX / sizeof(*c->frontends)) return KIT_NOMEM;
   if (c->frontends) {
     nv = (const KitFrontendVTable**)h->realloc(
         h, (void*)c->frontends, c->frontends_cap * sizeof(*c->frontends),
         ncap * sizeof(*c->frontends), _Alignof(const KitFrontendVTable*));
   } else {
     nv = (const KitFrontendVTable**)h->alloc(
         h, ncap * sizeof(*c->frontends), _Alignof(const KitFrontendVTable*));
   }
   if (!nv) return KIT_NOMEM;
   for (i = c->frontends_cap; i < ncap; ++i) nv[i] = NULL;
   c->frontends = nv;
   c->frontends_cap = ncap;
   return KIT_OK;
 }
 
 static KitStatus compiler_register_frontend(Compiler* c, KitLanguage lang,
                                             const KitFrontendVTable* vtable) {
   KitStatus st;
   if (!c || lang == KIT_LANG_UNKNOWN || lang == KIT_LANG_AUTO)
     return KIT_INVALID;
   st = validate_frontend_vtable(vtable);
   if (st != KIT_OK) return st;
   st = compiler_frontends_reserve(c, lang + 1u);
   if (st != KIT_OK) return st;
   c->frontends[lang] = vtable;
   if (c->nfrontends < lang + 1u) c->nfrontends = lang + 1u;
   return KIT_OK;
 }
 
 /* Resolve `lang`'s frontend vtable: from the compiler's per-instance table
  * when a compiler is supplied, else from the compile-time default registry so
  * the language resolvers work with c==NULL (e.g. at CLI arg-parse time, before
  * a KitCompiler exists). Out-of-range `lang` yields NULL via lang_registry. */
 static const KitFrontendVTable* frontend_for(KitCompiler* c, unsigned lang) {
   if (c) {
     if (lang >= ((Compiler*)c)->nfrontends) return NULL;
     return ((Compiler*)c)->frontends[lang];
   }
   return lang_registry_vtable((KitLanguage)lang);
 }
 
 static const KitFrontendVTable* registry_frontend_for(
     const KitFrontendRegistry* r, KitLanguage lang) {
   if (!r || lang >= r->nfrontends) return NULL;
   return r->frontends[lang];
 }
 
 static uint32_t frontend_count_for(KitCompiler* c) {
   if (c) return ((Compiler*)c)->nfrontends;
   return KIT_LANG_BUILTIN_COUNT;
 }
 
 static KitFrontendPathKind language_path_kind_common(
     KitCompiler* c, const KitFrontendRegistry* r, const char* path,
     KitLanguage* out_lang) {
   size_t len;
   size_t i;
   KitSlice ext = SLICE_NULL;
   int have_ext = 0;
   uint32_t lang;
   uint32_t nlangs;
 
   if (out_lang) *out_lang = KIT_LANG_UNKNOWN;
   if (!path) return KIT_FRONTEND_PATH_UNKNOWN;
   for (len = 0; path[len]; ++len) {
   }
   i = len;
   while (i > 0) {
     --i;
     if (path[i] == '/') break;
     if (path[i] == '.') {
       ext.s = path + i + 1;
       ext.len = len - (i + 1);
       have_ext = 1;
       break;
     }
   }
   if (!have_ext) return KIT_FRONTEND_PATH_UNKNOWN;
 
   nlangs = r ? r->nfrontends : frontend_count_for(c);
   for (lang = 0; lang < nlangs; ++lang) {
     const KitFrontendVTable* v =
         r ? registry_frontend_for(r, lang) : frontend_for(c, lang);
     uint32_t e;
     if (!v || !v->extensions) continue;
     for (e = 0; e < v->nextensions; ++e) {
       if (ext_eq_ci(ext, v->extensions[e])) {
         if (out_lang) *out_lang = (KitLanguage)lang;
         return vtable_extension_kind(v, e);
       }
     }
   }
   return KIT_FRONTEND_PATH_UNKNOWN;
 }
 
 KitLanguage kit_language_for_path(KitCompiler* c, const char* path) {
   KitLanguage lang = KIT_LANG_UNKNOWN;
   (void)language_path_kind_common(c, NULL, path, &lang);
   return lang;
 }
 
 KitFrontendPathKind kit_language_path_kind(KitCompiler* c, const char* path,
                                            KitLanguage* out_lang) {
   return language_path_kind_common(c, NULL, path, out_lang);
 }
 
 /* Case-sensitive trailing-substring match (mirrors the driver's exact suffix
  * test for object/archive/dso paths). */
 static int path_has_suffix(const char* s, const char* suffix) {
   size_t ls = 0, lf = 0;
   while (s[ls]) ++ls;
   while (suffix[lf]) ++lf;
   return ls >= lf && memcmp(s + ls - lf, suffix, lf) == 0;
 }
 
 KitInputKind kit_input_kind_for_path(KitCompiler* c, const char* path) {
   if (!path) return KIT_INPUT_UNKNOWN;
   /* A registered frontend's compilable-source extension wins first
    * (case-insensitive registry). Header/interface extensions are owned by a
    * language but are not standalone translation units. */
   if (kit_language_path_kind(c, path, NULL) == KIT_FRONTEND_PATH_SOURCE)
     return KIT_INPUT_SOURCE;
   if (path_has_suffix(path, ".o") || path_has_suffix(path, ".obj"))
     return KIT_INPUT_OBJECT;
   if (path_has_suffix(path, ".a")) return KIT_INPUT_ARCHIVE;
   if (path_has_suffix(path, ".so") || path_has_suffix(path, ".dylib") ||
       path_has_suffix(path, ".tbd"))
     return KIT_INPUT_DSO;
   return KIT_INPUT_UNKNOWN;
 }
 
 /* Compare a NUL-terminated name to a frontend's name slice, byte-for-byte
  * (case-sensitive, mirroring the driver's exact `-x` spellings). Returns
  * nonzero on a full match. */
 static int name_eq(const char* name, KitSlice pat) {
   size_t i;
   for (i = 0; i < pat.len; ++i) {
     if (name[i] == '\0' || name[i] != pat.s[i]) return 0;
   }
   return name[pat.len] == '\0';
 }
 
 KitLanguage kit_language_for_name(KitCompiler* c, const char* name) {
   uint32_t lang;
   uint32_t nlangs;
   if (!name) return KIT_LANG_UNKNOWN;
   nlangs = frontend_count_for(c);
   for (lang = 0; lang < nlangs; ++lang) {
     const KitFrontendVTable* v = frontend_for(c, lang);
     uint32_t n;
     if (!v || !v->names) continue;
     for (n = 0; n < v->nnames; ++n) {
       if (name_eq(name, v->names[n])) return (KitLanguage)lang;
     }
   }
   return KIT_LANG_UNKNOWN;
 }
 
 const char* kit_language_name(KitCompiler* c, KitLanguage lang) {
   const KitFrontendVTable* v;
   if (lang == KIT_LANG_UNKNOWN || lang == KIT_LANG_AUTO) return NULL;
   v = frontend_for(c, (unsigned)lang);
   if (!v || !v->names || v->nnames == 0) return NULL;
   /* The first name is the canonical one. Name tables are KIT_SLICE_LIT over
    * string literals, so the slice's bytes are NUL-terminated just past .len. */
   return v->names[0].s;
 }
 
 const char* kit_language_default_extension(KitCompiler* c, KitLanguage lang) {
   const KitFrontendVTable* v;
   if (lang == KIT_LANG_UNKNOWN || lang == KIT_LANG_AUTO) return NULL;
   v = frontend_for(c, (unsigned)lang);
   if (!v || !v->extensions || v->nextensions == 0) return NULL;
   /* The first extension is the canonical one. Extension tables are
    * KIT_SLICE_LIT over string literals, so the slice's bytes are
    * NUL-terminated just past .len. */
   return v->extensions[0].s;
 }
 
 KitStatus kit_register_frontend(KitCompiler* c, KitLanguage lang,
                                 const KitFrontendVTable* vtable) {
   return compiler_register_frontend((Compiler*)c, lang, vtable);
 }
 
 KitStatus kit_frontend_caps(KitCompiler* c, KitLanguage lang,
                             KitFrontendCaps* out) {
   const KitFrontendVTable* v;
   if (!c || !out || lang == KIT_LANG_UNKNOWN || lang == KIT_LANG_AUTO)
     return KIT_INVALID;
   v = frontend_for(c, lang);
   if (!v) return KIT_INVALID;
   *out = v->caps;
   return KIT_OK;
 }
 
 KitStatus kit_frontend_parse_options(KitCompiler* c, KitLanguage lang, int argc,
                                      char** argv, void** out_opts) {
   const KitFrontendVTable* v;
   if (out_opts) *out_opts = NULL;
   if (!c || !out_opts || lang == KIT_LANG_UNKNOWN || lang == KIT_LANG_AUTO)
     return KIT_INVALID;
   v = frontend_for(c, lang);
   if (!v || !v->parse_options) return KIT_INVALID;
   return v->parse_options(c, argc, argv, out_opts);
 }
 
 void kit_frontend_free_options(KitCompiler* c, KitLanguage lang, void* opts) {
   const KitFrontendVTable* v;
   if (!c || !opts || lang == KIT_LANG_UNKNOWN || lang == KIT_LANG_AUTO) return;
   v = frontend_for(c, lang);
   if (v && v->free_options) v->free_options(c, opts);
 }
 
 KitStatus kit_frontend_registry_new(const KitContext* ctx,
                                     KitFrontendRegistry** out) {
   KitHeap* h;
   KitFrontendRegistry* r;
   if (!out) return KIT_INVALID;
   *out = NULL;
   if (!ctx || !ctx->heap) return KIT_INVALID;
   h = ctx->heap;
   r = (KitFrontendRegistry*)h->alloc(h, sizeof(*r),
                                      _Alignof(KitFrontendRegistry));
   if (!r) return KIT_NOMEM;
   memset(r, 0, sizeof(*r));
   r->ctx = ctx;
   *out = r;
   return KIT_OK;
 }
 
 void kit_frontend_registry_free(KitFrontendRegistry* r) {
   KitHeap* h;
   if (!r || !r->ctx || !r->ctx->heap) return;
   h = r->ctx->heap;
   if (r->frontends)
     h->free(h, (void*)r->frontends, r->cap * sizeof(*r->frontends));
   h->free(h, r, sizeof(*r));
 }
 
 KitStatus kit_frontend_registry_add_builtin(KitFrontendRegistry* r) {
   KitStatus st;
   KitLanguage lang;
   if (!r) return KIT_INVALID;
   st = registry_reserve(r, KIT_LANG_BUILTIN_COUNT);
   if (st != KIT_OK) return st;
   for (lang = 0; lang < KIT_LANG_BUILTIN_COUNT; ++lang)
     r->frontends[lang] = lang_registry_vtable(lang);
   if (r->nfrontends < KIT_LANG_BUILTIN_COUNT)
     r->nfrontends = KIT_LANG_BUILTIN_COUNT;
   return KIT_OK;
 }
 
 KitStatus kit_frontend_registry_add(KitFrontendRegistry* r,
                                     const KitFrontendVTable* vtable,
                                     KitLanguage* out_lang) {
   KitStatus st;
   KitLanguage lang;
   if (out_lang) *out_lang = KIT_LANG_UNKNOWN;
   if (!r || !vtable) return KIT_INVALID;
   st = validate_frontend_vtable(vtable);
   if (st != KIT_OK) return st;
   lang = r->nfrontends;
   st = registry_reserve(r, lang + 1u);
   if (st != KIT_OK) return st;
   r->frontends[lang] = vtable;
   r->nfrontends = lang + 1u;
   if (out_lang) *out_lang = lang;
   return KIT_OK;
 }
 
 KitLanguage kit_frontend_registry_language_for_path(
     const KitFrontendRegistry* r, const char* path) {
   KitLanguage lang = KIT_LANG_UNKNOWN;
   (void)language_path_kind_common(NULL, r, path, &lang);
   return lang;
 }
 
 KitLanguage kit_frontend_registry_language_for_name(
     const KitFrontendRegistry* r, const char* name) {
   uint32_t lang;
   if (!r || !name) return KIT_LANG_UNKNOWN;
   for (lang = 0; lang < r->nfrontends; ++lang) {
     const KitFrontendVTable* v = registry_frontend_for(r, lang);
     uint32_t n;
     if (!v || !v->names) continue;
     for (n = 0; n < v->nnames; ++n) {
       if (name_eq(name, v->names[n])) return (KitLanguage)lang;
     }
   }
   return KIT_LANG_UNKNOWN;
 }
 
 KitFrontendPathKind kit_frontend_registry_path_kind(
     const KitFrontendRegistry* r, const char* path, KitLanguage* out_lang) {
   return language_path_kind_common(NULL, r, path, out_lang);
 }
 
 KitStatus kit_compiler_install_frontend_registry(
     KitCompiler* c, const KitFrontendRegistry* r) {
   Compiler* cc = (Compiler*)c;
   KitStatus st;
   uint32_t i;
   if (!cc || !r) return KIT_INVALID;
   st = compiler_frontends_reserve(cc, r->nfrontends);
   if (st != KIT_OK) return st;
   for (i = 0; i < r->nfrontends; ++i) cc->frontends[i] = r->frontends[i];
   for (i = r->nfrontends; i < cc->nfrontends; ++i) cc->frontends[i] = NULL;
   cc->nfrontends = r->nfrontends;
   return KIT_OK;
 }
 
 uint32_t kit_compiler_arch_predefines(KitCompiler* c,
                                       const KitPredefinedMacro** out) {
   const ArchImpl* arch;
   if (out) *out = NULL;
   if (!c) return 0;
   arch = arch_for_compiler((Compiler*)c);
   if (!arch || !arch->predefined_macros || arch->npredefined_macros == 0)
     return 0;
   if (out) *out = arch->predefined_macros;
   return arch->npredefined_macros;
 }
 
 uint32_t kit_compiler_arch_float_predefines(KitCompiler* c,
                                             const KitPredefinedMacro** out) {
   const ArchImpl* arch;
   KitTargetSpec spec;
   if (out) *out = NULL;
   if (!c) return 0;
   arch = arch_for_compiler((Compiler*)c);
   spec = kit_compiler_target_spec(c);
   return arch_float_predefines(arch, &spec, out);
 }
 
 uint32_t kit_compiler_arch_feature_predefines(KitCompiler* c,
                                               const KitPredefinedMacro** out) {
   const ArchImpl* arch;
   const KitTarget* tgt;
   KitTargetSpec spec;
   if (out) *out = NULL;
   if (!c) return 0;
   arch = arch_for_compiler((Compiler*)c);
   tgt = ((Compiler*)c)->target_ref;
   spec = kit_compiler_target_spec(c);
   return arch_feature_predefines(arch, &spec,
                                  tgt ? tgt->feature_words : NULL,
                                  tgt ? tgt->nfeature_words : 0, out);
 }
 
 static void validate_bytes(Compiler* c, const KitSourceInput* in) {
   if (!in->name.s) panic_bad_options(c, "input name is NULL");
   if (!in->bytes.data && in->bytes.len != 0) {
     panic_bad_options(c, "input data is NULL but len > 0");
   }
 }
 
 static const KitFrontendVTable* frontend_for_language(Compiler* c,
                                                       KitLanguage lang) {
   if (!c || lang == KIT_LANG_UNKNOWN || lang == KIT_LANG_AUTO ||
       lang >= c->nfrontends)
     return NULL;
   return c->frontends[lang];
 }
 
 static KitStatus compile_obj_finalize(Compiler* c, ObjBuilder* ob);
 static KitStatus compile_frontend_state_obj_into(
     Compiler* c, const KitFrontendVTable* vtable, KitFrontendState* frontend,
     const KitFrontendCompileOptions* opts, const KitSourceInput* input,
     ObjBuilder* ob);
 
 static KitStatus kit_frontend_new(KitCompiler* c, KitLanguage lang,
                                   KitFrontend** out) {
   const KitFrontendVTable* vtable;
   KitFrontendState* state;
   KitFrontend* frontend;
   Heap* h;
 
   if (!out) return KIT_INVALID;
   *out = NULL;
   if (!c || lang == KIT_LANG_UNKNOWN || lang == KIT_LANG_AUTO)
     return KIT_INVALID;
   vtable = frontend_for_language((Compiler*)c, lang);
   if (!vtable) return KIT_UNSUPPORTED;
   state = vtable->new_frontend(c);
   if (!state) return KIT_NOMEM;
   h = (Heap*)c->ctx->heap;
   frontend =
       (KitFrontend*)h->alloc(h, sizeof(*frontend), _Alignof(KitFrontend));
   if (!frontend) {
     vtable->free_frontend(state);
     return KIT_NOMEM;
   }
   frontend->c = c;
   frontend->lang = lang;
   frontend->vtable = vtable;
   frontend->state = state;
   *out = frontend;
   return KIT_OK;
 }
 
 static void kit_frontend_commit(KitFrontend* frontend) {
   if (frontend && frontend->vtable && frontend->vtable->commit) {
     frontend->vtable->commit(frontend->state);
   }
 }
 
 static void kit_frontend_abort(KitFrontend* frontend) {
   if (frontend && frontend->vtable && frontend->vtable->abort) {
     frontend->vtable->abort(frontend->state);
   }
 }
 
 static KitStatus kit_frontend_compile_obj(KitFrontend* frontend,
                                           const KitFrontendCompileOptions* opts,
                                           const KitSourceInput* input,
                                           KitObjBuilder* out) {
   Compiler* c;
   PanicFrame panic;
   KitStatus st;
 
   if (!frontend || !frontend->c || !frontend->vtable || !frontend->state ||
       !opts || !input || !out) {
     return KIT_INVALID;
   }
   if (input->lang != frontend->lang) return KIT_INVALID;
   if (!frontend->vtable->compile_obj) return KIT_UNSUPPORTED;
   c = (Compiler*)frontend->c;
   compiler_panic_push(c, &panic);
   if (setjmp(panic.env)) {
     /* A genuine internal panic (CG/backend) longjmp'd here. Run cleanups, then
      * roll back any durable frontend state staged during this compile, and
      * propagate as a soft error. Ordinary diagnostic failures do NOT take this
      * path: the frontend returns KIT_ERR below without panicking. */
     compiler_run_cleanups(c);
     kit_frontend_abort(frontend);
     compiler_panic_pop(c, &panic);
     return KIT_ERR;
   }
   validate_bytes(c, input);
   metrics_scope_begin(c, "compile.tu");
   metrics_count(c, "compile.input_bytes", (u64)input->bytes.len);
   st = compile_frontend_state_obj_into(c, frontend->vtable, frontend->state,
                                        opts, input, (ObjBuilder*)out);
   metrics_scope_end(c, "compile.tu");
   /* On a soft diagnostic failure, roll back the staged transaction here so the
    * frontend is left exactly as it was before this compile. On success the
    * transaction is left open for the caller to commit or abort. */
   if (st != KIT_OK) kit_frontend_abort(frontend);
   compiler_panic_pop(c, &panic);
   return st;
 }
 
 static KitStatus kit_frontend_compile_cg(KitFrontend* frontend,
                                          const KitFrontendCompileOptions* opts,
                                          const KitSourceInput* input,
                                          KitCg* cg) {
   Compiler* c;
   PanicFrame panic;
   KitStatus st;
 
   if (!frontend || !frontend->c || !frontend->vtable || !frontend->state ||
       !opts || !input || !cg) {
     return KIT_INVALID;
   }
   if (input->lang != frontend->lang) return KIT_INVALID;
   if (frontend->vtable->caps.lto_mode != KIT_FRONTEND_LTO_CG ||
       !frontend->vtable->compile_cg) {
     return KIT_UNSUPPORTED;
   }
   c = (Compiler*)frontend->c;
   compiler_panic_push(c, &panic);
   if (setjmp(panic.env)) {
     compiler_run_cleanups(c);
     kit_frontend_abort(frontend);
     compiler_panic_pop(c, &panic);
     return KIT_ERR;
   }
   validate_bytes(c, input);
   metrics_scope_begin(c, "compile.tu");
   metrics_count(c, "compile.input_bytes", (u64)input->bytes.len);
   metrics_scope_begin(c, "compile.frontend");
   st = frontend->vtable->compile_cg(frontend->state, opts, input, cg);
   metrics_scope_end(c, "compile.frontend");
   metrics_scope_end(c, "compile.tu");
   if (st != KIT_OK) kit_frontend_abort(frontend);
   compiler_panic_pop(c, &panic);
   return st;
 }
 
 static void kit_frontend_free(KitFrontend* frontend) {
   Heap* h;
   if (!frontend) return;
   if (frontend->vtable && frontend->state) {
     frontend->vtable->free_frontend(frontend->state);
   }
   h = (Heap*)frontend->c->ctx->heap;
   h->free(h, frontend, sizeof(*frontend));
 }
 
 KitStatus kit_compile_session_new(KitCompiler* c,
                                   const KitCompileSessionOptions* opts,
                                   KitCompileSession** out) {
   KitCompileSession* s;
   KitFrontend* frontend = NULL;
   KitStatus st;
   Heap* h;
 
   if (!out) return KIT_INVALID;
   *out = NULL;
   if (!c || !opts || opts->lang == KIT_LANG_UNKNOWN ||
       opts->lang == KIT_LANG_AUTO)
     return KIT_INVALID;
   st = kit_frontend_new(c, opts->lang, &frontend);
   if (st != KIT_OK) return st;
   h = (Heap*)c->ctx->heap;
   s = (KitCompileSession*)h->alloc(h, sizeof(*s), _Alignof(KitCompileSession));
   if (!s) {
     kit_frontend_free(frontend);
     return KIT_NOMEM;
   }
   memset(s, 0, sizeof(*s));
   s->c = c;
   s->lang = opts->lang;
   s->frontend = frontend;
   s->opts = opts->compile;
   *out = s;
   return KIT_OK;
 }
 
 /* Shared object-producing compile path. Opaque frontends compile directly into
  * the object builder; semantic frontends use the same borrowed KitCg lifecycle
  * as LTO with a single source unit. On failure the frontend transaction is
  * rolled back and *out is NULL. On success, when commit_on_success is set (the
  * batch path), the transaction is committed before returning; otherwise it is
  * left open for the caller to resolve. */
 static KitStatus compile_session_run(KitCompileSession* s,
                                      const KitSourceInput* input,
                                      KitObjBuilder** out,
                                      int commit_on_success) {
   ObjBuilder* ob;
   KitFrontendCompileOptions opts;
   KitStatus st;
 
   if (!out) return KIT_INVALID;
   *out = NULL;
   if (!s || !s->c || !s->frontend || !input) return KIT_INVALID;
   if (input->lang != s->lang) return KIT_INVALID;
   ob = obj_new((Compiler*)s->c);
   if (!ob) return KIT_NOMEM;
   opts = s->opts;
   opts.input_kind = input->input_kind;
   opts.repl_entry_name = input->repl_entry_name;
   if (s->frontend->vtable->caps.lto_mode == KIT_FRONTEND_LTO_CG) {
     KitCg* cg = NULL;
     KitCgUnitOptions uopts;
     st = kit_cg_new(s->c, &cg);
     if (st == KIT_OK) st = kit_cg_begin(cg, (KitObjBuilder*)ob, &opts.code);
     memset(&uopts, 0, sizeof uopts);
     uopts.source_name = input->name;
     if (st == KIT_OK) st = kit_cg_begin_unit(cg, &uopts);
     if (st == KIT_OK)
       st = kit_frontend_compile_cg(s->frontend, &opts, input, cg);
     if (st == KIT_OK) st = kit_cg_end_unit(cg);
     if (st == KIT_OK) st = kit_cg_finish(cg, NULL);
     if (st == KIT_OK) st = kit_cg_detach(cg);
     kit_cg_free(cg);
     if (st == KIT_OK) st = compile_obj_finalize((Compiler*)s->c, ob);
   } else {
     st =
         kit_frontend_compile_obj(s->frontend, &opts, input, (KitObjBuilder*)ob);
   }
   if (st != KIT_OK) {
     kit_frontend_abort(s->frontend);
     obj_free(ob);
     return st;
   }
   if (commit_on_success) kit_frontend_commit(s->frontend);
   *out = (KitObjBuilder*)ob;
   return KIT_OK;
 }
 
 KitStatus kit_compile_session_compile(KitCompileSession* s,
                                       const KitSourceInput* input,
                                       KitObjBuilder** out) {
   return compile_session_run(s, input, out, /*commit_on_success=*/1);
 }
 
 KitStatus kit_compile_session_compile_cg(KitCompileSession* s,
                                          const KitSourceInput* input,
                                          KitCg* cg) {
   KitFrontendCompileOptions opts;
   KitStatus st;
   int unit_open = 0;
 
   if (!s || !s->c || !s->frontend || !input || !cg) return KIT_INVALID;
   if (input->lang != s->lang) return KIT_INVALID;
   opts = s->opts;
   opts.input_kind = input->input_kind;
   opts.repl_entry_name = input->repl_entry_name;
   {
     KitCgUnitOptions uopts;
     memset(&uopts, 0, sizeof uopts);
     uopts.source_name = input->name;
     st = kit_cg_begin_unit(cg, &uopts);
   }
   if (st == KIT_OK) unit_open = 1;
   if (st == KIT_OK) st = kit_frontend_compile_cg(s->frontend, &opts, input, cg);
   if (st == KIT_OK) st = kit_cg_end_unit(cg);
   if (st == KIT_OK) {
     unit_open = 0;
     kit_frontend_commit(s->frontend);
   } else if (unit_open) {
     (void)kit_cg_detach(cg);
   }
   return st;
 }
 
 KitStatus kit_compile_session_stage(KitCompileSession* s,
                                     const KitSourceInput* input,
                                     KitObjBuilder** out) {
   return compile_session_run(s, input, out, /*commit_on_success=*/0);
 }
 
 void kit_compile_session_commit(KitCompileSession* s) {
   if (s && s->frontend) kit_frontend_commit(s->frontend);
 }
 
 void kit_compile_session_abort(KitCompileSession* s) {
   if (s && s->frontend) kit_frontend_abort(s->frontend);
 }
 
 void kit_compile_session_free(KitCompileSession* s) {
   Heap* h;
   if (!s) return;
   h = (Heap*)s->c->ctx->heap;
   kit_frontend_free(s->frontend);
   h->free(h, s, sizeof(*s));
 }
 
 static KitStatus compile_obj_finalize(Compiler* c, ObjBuilder* ob) {
   metrics_scope_begin(c, "compile.obj_finalize");
   obj_finalize(ob);
   metrics_scope_end(c, "compile.obj_finalize");
   metrics_count(c, "compile.obj_sections", obj_section_count(ob));
   metrics_count(c, "compile.obj_relocs", obj_reloc_total(ob));
   return KIT_OK;
 }
 
 static KitStatus compile_frontend_state_obj_into(
     Compiler* c, const KitFrontendVTable* vtable, KitFrontendState* frontend,
     const KitFrontendCompileOptions* opts, const KitSourceInput* input,
     ObjBuilder* ob) {
   KitStatus st;
 
   metrics_scope_begin(c, "compile.frontend");
   st = vtable->compile_obj(frontend, opts, input, ob);
   metrics_scope_end(c, "compile.frontend");
   /* Ordinary diagnostic failure: fail softly with the status the frontend
    * already reported. No synthetic fatal, and do not finalize a half-built
    * object. Genuine internal failures panic from inside compile_obj and
    * never reach here. */
   if (st != KIT_OK) return st;
   return compile_obj_finalize(c, ob);
 }
 
 /* ============================================================
  * Asm
  * ============================================================ */
 
 static KitFrontendState* asm_frontend_new(KitCompiler* c) {
   Heap* h;
   AsmFrontend* fe;
   if (!c) return NULL;
   h = (Heap*)c->ctx->heap;
   fe = (AsmFrontend*)h->alloc(h, sizeof(*fe), _Alignof(AsmFrontend));
   if (!fe) return NULL;
   fe->c = c;
   return (KitFrontendState*)fe;
 }
 
 static KitStatus asm_frontend_compile(KitFrontendState* frontend,
                                       const KitFrontendCompileOptions* opts,
                                       const KitSourceInput* input,
                                       KitObjBuilder* out) {
   AsmFrontend* fe = (AsmFrontend*)frontend;
   Compiler* c;
   AsmLexer* lex;
   MCEmitter* mc;
   KitDiagSink* diag;
   u32 errors0;
   (void)opts;
   if (!fe || !fe->c || !input || !out) return KIT_INVALID;
   c = fe->c;
   diag = c->ctx ? c->ctx->diag : NULL;
   errors0 = diag ? diag->errors : 0;
   metrics_scope_begin(c, "compile.asm.lex_open");
   lex = asm_lex_open_mem(c, input->name.s, input->bytes.s, input->bytes.len);
   metrics_scope_end(c, "compile.asm.lex_open");
   metrics_scope_begin(c, "compile.asm.mc_new");
   mc = mc_new(c, (ObjBuilder*)out);
   metrics_scope_end(c, "compile.asm.mc_new");
   if (!lex || !mc) {
     /* Allocation failed before we could parse anything. Release whichever
      * half we did get and report out-of-memory rather than a silent KIT_OK. */
     mc_free(mc);
     asm_lex_close(lex);
     return KIT_NOMEM;
   }
   metrics_scope_begin(c, "compile.asm.parse");
   asm_parse(c, lex, mc);
   metrics_scope_end(c, "compile.asm.parse");
   metrics_scope_begin(c, "compile.asm.mc_free");
   mc_free(mc);
   asm_lex_close(lex);
   metrics_scope_end(c, "compile.asm.mc_free");
   /* asm_parse reports hard errors via panic (longjmp to the compile-obj
    * setjmp frame, which yields KIT_ERR), so reaching here means the parse
    * completed; but propagate any soft diagnostics the sink recorded instead
    * of unconditionally claiming success. */
   if (diag && diag->errors > errors0) return KIT_ERR;
   return KIT_OK;
 }
 
 static void asm_frontend_free(KitFrontendState* frontend) {
   AsmFrontend* fe = (AsmFrontend*)frontend;
   Heap* h;
   if (!fe) return;
   h = fe->c->ctx->heap;
   h->free(h, fe, sizeof(*fe));
 }
 
 struct KitDepIter {
   Compiler* c;
   SourceDepIter* inner;
 };
 
 KitStatus kit_dep_iter_new(KitCompiler* c, KitDepIter** out) {
   Heap* h;
   KitDepIter* it;
   if (!out) return KIT_INVALID;
   if (!c || !c->sources) return KIT_INVALID;
   h = c->ctx->heap;
   it = (KitDepIter*)h->alloc(h, sizeof(*it), _Alignof(KitDepIter));
   if (!it) return KIT_NOMEM;
   it->c = c;
   it->inner = source_depiter_new(c->sources);
   if (!it->inner) {
     h->free(h, it, sizeof(*it));
     return KIT_NOMEM;
   }
   *out = it;
   return KIT_OK;
 }
 
 KitIterResult kit_dep_iter_next(KitDepIter* it, KitDepEdge* out) {
   const SourceInclude* edge;
   const SourceFile* includer;
   const SourceFile* included;
   if (!it || !out) return KIT_ITER_ERROR;
   edge = source_depiter_next(it->inner);
   if (!edge) return KIT_ITER_END;
   includer = source_file(it->c->sources, edge->includer_file_id);
   included = source_file(it->c->sources, edge->included_file_id);
   out->includer_name =
       includer ? pool_slice(it->c->global, includer->name) : KIT_SLICE_NULL;
   out->included_name =
       included ? pool_slice(it->c->global, included->name) : KIT_SLICE_NULL;
   out->include_loc = edge->include_loc;
   /* `bracketed` is the spelling form (<...> vs "..."); `from_system_path` is
    * the resolved-dir system flag (whether an -isystem dir satisfied the
    * header), threaded from find_and_open_include through
    * SourceInclude.resolved_system. They differ when a <...> include is resolved
    * via a plain -I dir. */
   out->bracketed = (uint8_t)(edge->system ? 1 : 0);
   out->from_system_path = (uint8_t)(edge->resolved_system ? 1 : 0);
   out->pad[0] = 0;
   out->pad[1] = 0;
   return KIT_ITER_ITEM;
 }
 
 void kit_dep_iter_free(KitDepIter* it) {
   Heap* h;
   if (!it) return;
   h = it->c->ctx->heap;
   if (it->inner) source_depiter_free(it->inner);
   h->free(h, it, sizeof(*it));
 }