kit

cg.h (76535B)

---

 #ifndef KIT_PUBLIC_CG_H
 #define KIT_PUBLIC_CG_H
 
 #include <kit/core.h>
 #include <kit/object.h>
 #include <kit/asm_constraints.h>
 
 /* ============================================================
  * Handles
  * ============================================================ */
 
 typedef struct KitCg KitCg;
 
 typedef uint32_t KitCgLabel;
 typedef uint32_t KitCgLocal;
 typedef uint32_t KitCgScope;
 typedef uint32_t KitCgSym;
 typedef uint32_t KitCgTypeId;
 typedef uint32_t KitCgDebugType;
 
 #define KIT_CG_LABEL_NONE 0u
 #define KIT_CG_LOCAL_NONE 0u
 #define KIT_CG_SCOPE_NONE 0u
 #define KIT_CG_SYM_NONE 0u
 /* Invalid or absent type sentinel. Void is represented by the real void
  * builtin type id, never by KIT_CG_TYPE_NONE. */
 #define KIT_CG_TYPE_NONE 0u
 /* Optional debug type sentinel. Declaration sites that pass NONE derive a
  * default debug type from the operational KitCgTypeId. */
 #define KIT_CG_DEBUG_TYPE_NONE 0u
 
 /* ============================================================
  * Lifecycle and Source Locations
  * ============================================================ */
 
 KIT_API KitStatus kit_cg_new(KitCompiler*, KitCg** cg_out);
 
 typedef struct KitCgUnitOptions {
   KitSlice source_name; /* diagnostic/provenance label; may be empty */
   uint32_t source_id;   /* 0 means "unspecified" */
   uint32_t flags;       /* reserved; must be 0 */
 } KitCgUnitOptions;
 
 typedef enum KitCgOutputKind {
   KIT_CG_OUTPUT_RELOCATABLE = 0,
   KIT_CG_OUTPUT_EXECUTABLE = 1,
   KIT_CG_OUTPUT_SHARED = 2,
   KIT_CG_OUTPUT_ARCHIVE_MEMBER = 3,
 } KitCgOutputKind;
 
 typedef enum KitCgInterpositionPolicy {
   KIT_CG_INTERPOSITION_DEFAULT = 0,
   KIT_CG_INTERPOSITION_NONE = 1,
   KIT_CG_INTERPOSITION_DEFAULT_VISIBILITY = 2,
 } KitCgInterpositionPolicy;
 
 typedef struct KitCgFinishOptions {
   uint8_t output_kind;          /* KitCgOutputKind */
   uint8_t interposition_policy; /* KitCgInterpositionPolicy */
   uint8_t pad[2];
   const KitCgSym* preserved_symbols;
   uint32_t npreserved_symbols;
 } KitCgFinishOptions;
 
 KIT_API KitStatus kit_cg_begin(KitCg*, KitObjBuilder* out,
                                const KitCodeOptions*);
 KIT_API KitStatus kit_cg_begin_unit(KitCg*, const KitCgUnitOptions*);
 KIT_API KitStatus kit_cg_end_unit(KitCg*);
 KIT_API KitStatus kit_cg_finish(KitCg*, const KitCgFinishOptions*);
 /* Release the session, abandoning any in-progress object/unit state. Used on
  * both the success-detach and error-abort paths. */
 KIT_API KitStatus kit_cg_detach(KitCg*);
 KIT_API void kit_cg_free(KitCg*);
 
 /* Sticky source location. Function, scope, local, param, instruction, and
  * data-definition debug records use the current location. */
 KIT_API void kit_cg_set_loc(KitCg*, KitSrcLoc);
 
 /* ============================================================
  * ABI Descriptors
  * ============================================================ */
 
 /* Source-selectable calling convention: the convention axis a frontend can vary
  * *within one compilation*, not the target's ABI identity (that is fixed by the
  * triple). KIT_CG_CC_TARGET_C selects the target's own C ABI — whichever of
  * SysV / Win64 / AAPCS64 / wasm the triple implies — and is the only convention
  * kit lowers today. A real variant that repartitions the call (e.g. an x86
  * vectorcall/regparm, preserve_most) would be added here and gated by
  * kit_cg_target_supports_call_conv. Definition-side conventions that change the
  * prologue but not the call ABI (naked, interrupt) are function attributes —
  * KIT_CG_FUNC_NAKED / KIT_CG_FUNC_INTERRUPT — not values here. */
 typedef enum KitCgCallConv {
   KIT_CG_CC_TARGET_C,
 } KitCgCallConv;
 
 typedef enum KitCgAbiAttrFlag {
   KIT_CG_ABI_NONE = 0,
   KIT_CG_ABI_SIGNEXT = 1u << 0,
   KIT_CG_ABI_ZEROEXT = 1u << 1,
   KIT_CG_ABI_SRET = 1u << 2,
   KIT_CG_ABI_BYVAL = 1u << 3,
   KIT_CG_ABI_BYREF = 1u << 4,
   KIT_CG_ABI_INREG = 1u << 5,
   KIT_CG_ABI_NOALIAS = 1u << 6,
   KIT_CG_ABI_READONLY = 1u << 7,
   KIT_CG_ABI_WRITEONLY = 1u << 8,
   KIT_CG_ABI_NONNULL = 1u << 9,
   KIT_CG_ABI_NEST = 1u << 10,
 } KitCgAbiAttrFlag;
 
 typedef struct KitCgAbiAttrs {
   uint32_t flags; /* KitCgAbiAttrFlag */
   uint32_t align; /* 0 = ABI default */
   uint64_t dereferenceable_size;
 } KitCgAbiAttrs;
 
 typedef struct KitCgFuncParam {
   KitCgTypeId type;
   KitCgAbiAttrs attrs;
 } KitCgFuncParam;
 
 /* A function result is described exactly like a parameter: a type plus ABI
  * attrs. The legal attribute subsets differ (SRET on results; BYVAL/NEST on
  * params), but the descriptor shape is identical, so KitCgFuncResult is an
  * alias of KitCgFuncParam. result.type is always a valid type id; use
  * kit_cg_type_builtin(c, KIT_CG_BUILTIN_VOID) for a function that returns no
  * value. */
 typedef KitCgFuncParam KitCgFuncResult;
 
 typedef struct KitCgFuncSig {
   KitCgFuncResult result; /* void builtin means no value */
   const KitCgFuncParam* params;
   uint32_t nparams;
   KitCgCallConv call_conv;
   bool abi_variadic;
 } KitCgFuncSig;
 
 /* Capability queries answer whether the selected target/API can lower the
  * requested feature correctly, not whether it is fast. These are target
  * facts, not knobs: frontends use them to choose a legal lowering or to emit
  * an unsupported-feature diagnostic before asking CG to produce output. */
 KIT_API int kit_cg_target_supports_call_conv(KitCompiler*, KitCgCallConv);
 
 /* ============================================================
  * Type System
  * ============================================================ */
 
 typedef enum KitCgBuiltinType {
   KIT_CG_BUILTIN_VOID,
   KIT_CG_BUILTIN_BOOL, /* i1: compare result and branch condition */
   KIT_CG_BUILTIN_I8,
   KIT_CG_BUILTIN_I16,
   KIT_CG_BUILTIN_I32,
   KIT_CG_BUILTIN_I64,
   KIT_CG_BUILTIN_I128,
   KIT_CG_BUILTIN_F32,
   KIT_CG_BUILTIN_F64,
   KIT_CG_BUILTIN_F128,
   KIT_CG_BUILTIN_VARARG_STATE,
   KIT_CG_BUILTIN_COUNT,
 } KitCgBuiltinType;
 
 typedef enum KitCgTypeKind {
   KIT_CG_TYPE_VOID,
   KIT_CG_TYPE_BOOL,
   KIT_CG_TYPE_INT,
   KIT_CG_TYPE_FLOAT,
   KIT_CG_TYPE_PTR,
   KIT_CG_TYPE_ARRAY,
   KIT_CG_TYPE_FUNC,
   KIT_CG_TYPE_RECORD,
   KIT_CG_TYPE_ENUM,
   KIT_CG_TYPE_VARARG_STATE,
 } KitCgTypeKind;
 
 /* Field descriptor for record completion (INPUT). Carries the field's source
  * shape and layout *policy* — alignment knobs and bit-field width — never its
  * position: CG computes byte/bit offsets from these and the target ABI. Query
  * the results back with kit_cg_type_record_layout after completion. */
 typedef struct KitCgFieldDesc {
   KitSym name; /* 0 for anonymous fields/tuple elements */
   KitCgTypeId type;
   uint32_t align_override; /* 0 = natural, 1 = packed, >1 explicit align */
   uint32_t max_align;      /* 0 = natural, otherwise cap field alignment */
   uint32_t flags;          /* KitCgFieldFlag */
   uint16_t bit_width;      /* bit-field width; 0 w/ BITFIELD = layout barrier */
   int bit_signed;          /* signed extraction for bit-field loads */
 } KitCgFieldDesc;
 
 typedef enum KitCgFieldFlag {
   KIT_CG_FIELD_BITFIELD = 1u << 0,
 } KitCgFieldFlag;
 
 /* Computed layout of one record field (OUTPUT; borrowed via the record-layout
  * view, never an input to completion). For a bit-field, `offset` is the byte
  * offset of the storage unit and the bit_* members carry the geometry; for an
  * ordinary field bit_width == 0 and the bit_* members are 0. */
 typedef struct KitCgFieldLayout {
   KitSym name;
   KitCgTypeId type;
   uint64_t offset; /* byte offset of the field (or its storage unit) */
   uint32_t flags;  /* KitCgFieldFlag */
   uint32_t bit_storage_size; /* storage-unit bytes for a bit-field, else 0 */
   uint16_t bit_offset;       /* bit position within the storage unit */
   uint16_t bit_width;        /* 0 for a non-bit-field */
   int bit_signed;            /* signed extraction for bit-field loads */
 } KitCgFieldLayout;
 
 /* Immutable, CG-owned record layout, borrowed via kit_cg_type_record_layout.
  * The pointer and its fields array stay valid and unchanged for the compiler's
  * lifetime once the record is complete, so frontends cache this pointer instead
  * of copying offsets into a parallel layout table. */
 typedef struct KitCgRecordLayout {
   uint64_t size;
   uint32_t align;
   uint32_t nfields;
   const KitCgFieldLayout* fields;
 } KitCgRecordLayout;
 
 typedef struct KitCgEnumValue {
   KitSym name;
   uint64_t value; /* bit pattern interpreted using the enum's integer base */
 } KitCgEnumValue;
 
 typedef struct KitCgRecordDesc {
   KitSym tag;
   const KitCgFieldDesc* fields;
   uint32_t nfields;
   int is_union;
   uint32_t align_override; /* 0 = natural, >0 explicit record alignment */
 } KitCgRecordDesc;
 
 typedef enum KitCgTypeFlag {
   KIT_CG_TYPEF_COMPLETE = 1u << 0,
   KIT_CG_TYPEF_SIZED = 1u << 1,
   KIT_CG_TYPEF_BUILTIN = 1u << 2,
   KIT_CG_TYPEF_NOMINAL = 1u << 3,
 } KitCgTypeFlag;
 
 typedef enum KitCgStorageKind {
   KIT_CG_STORAGE_VOID,
   KIT_CG_STORAGE_BOOL,
   KIT_CG_STORAGE_INT,
   KIT_CG_STORAGE_FLOAT,
   KIT_CG_STORAGE_PTR,
   KIT_CG_STORAGE_AGGREGATE,
 } KitCgStorageKind;
 
 typedef struct KitCgTypeLayout {
   uint64_t size;
   uint32_t align;
   uint16_t scalar_width; /* bit width for scalar int/float/bool, else 0 */
   uint8_t storage_kind;  /* KitCgStorageKind */
   uint8_t valid;         /* 0 for invalid, incomplete, or unsized types */
 } KitCgTypeLayout;
 
 typedef struct KitCgTypeInfo {
   KitCgTypeId id;
   KitCgTypeId storage_id; /* storage identity; always equal to id */
   KitCgTypeKind kind;     /* exact kind */
   uint32_t flags;         /* KitCgTypeFlag */
   KitCgTypeLayout layout; /* ABI/storage layout; valid only when sized */
 } KitCgTypeInfo;
 
 /* Type ids are stable only within one compiler. Pointer, array, and function
  * constructors return a stable id for the same exact shape within one compiler;
  * aliases, records, and enums allocate fresh user-facing identities. Void is a
  * builtin type id; KIT_CG_TYPE_NONE is invalid/absent only.
  *
  * Integer types are width-only storage types. Signedness is carried by
  * operations, comparisons, conversions, and ABI extension attributes. */
 KIT_API KitCgTypeId kit_cg_type_builtin(KitCompiler*, KitCgBuiltinType which);
 
 /* Interned structural types. Address space 0 is the normal target data
  * address space. Function signatures must use the void builtin type id as the
  * result type for a no-value return. */
 KIT_API KitCgTypeId kit_cg_type_func(KitCompiler*, KitCgFuncSig sig);
 KIT_API KitCgTypeId kit_cg_type_ptr(KitCompiler*, KitCgTypeId pointee,
                                     uint32_t address_space);
 KIT_API KitCgTypeId kit_cg_type_array(KitCompiler*, KitCgTypeId elem,
                                       uint64_t count);
 
 /* Enums use a width-only integer base. */
 KIT_API KitCgTypeId kit_cg_type_enum(KitCompiler*, KitSym tag, KitCgTypeId base,
                                      const KitCgEnumValue* values,
                                      uint32_t nvalues);
 
 /* Records are nominal and may be declared before they are complete. Pointers
  * to incomplete records are valid; sizing, arrays, fields, by-value
  * params/results, locals, and memory accesses require complete/sized types.
  * Completion is one-shot and computes ABI/source layout for the record. */
 KIT_API KitCgTypeId kit_cg_type_record_decl(KitCompiler*, KitSym tag,
                                             int is_union);
 KIT_API KitStatus kit_cg_type_record_complete(KitCompiler*, KitCgTypeId record,
                                               const KitCgRecordDesc*);
 /* Convenience constructor: declare a fresh nominal record, complete it, and
  * return its id, or KIT_CG_TYPE_NONE on failure. */
 static inline KitCgTypeId kit_cg_type_record(KitCompiler* c,
                                              const KitCgRecordDesc* desc) {
   KitCgTypeId record;
   if (!desc) return KIT_CG_TYPE_NONE;
   record = kit_cg_type_record_decl(c, desc->tag, desc->is_union);
   if (record == KIT_CG_TYPE_NONE) return KIT_CG_TYPE_NONE;
   if (kit_cg_type_record_complete(c, record, desc) != KIT_OK)
     return KIT_CG_TYPE_NONE;
   return record;
 }
 
 /* Type queries.
  *
  * Layout and width queries report ABI/storage facts. Shape-specific queries are
  * exact over the operational type lattice. */
 KIT_API KitStatus kit_cg_type_info(KitCompiler*, KitCgTypeId, KitCgTypeInfo*);
 
 /* Stable per-id identity view. Returns a pointer to an interned KitCgTypeInfo
  * whose IDENTITY fields are authoritative for the lifetime of the compiler:
  * id, storage_id (always id), kind, and the BUILTIN / NOMINAL flag bits. The
  * layout substruct and the COMPLETE / SIZED flag bits are NOT maintained on
  * this view — completeness and sizing can change as records complete, and
  * layout is computed lazily — so call kit_cg_type_info for an authoritative
  * full snapshot. Returns NULL for an invalid id. The cheap identity queries
  * below are inline projections over this one extern. */
 KIT_API const KitCgTypeInfo* kit_cg_type_view(KitCompiler*, KitCgTypeId);
 
 KIT_API int kit_cg_type_same_storage(KitCompiler*, KitCgTypeId, KitCgTypeId);
 KIT_API int kit_cg_type_is_complete(KitCompiler*, KitCgTypeId);
 KIT_API int kit_cg_type_is_sized(KitCompiler*, KitCgTypeId);
 
 static inline KitCgTypeKind kit_cg_type_kind(KitCompiler* c, KitCgTypeId id) {
   const KitCgTypeInfo* t = kit_cg_type_view(c, id);
   return t ? t->kind : KIT_CG_TYPE_VOID;
 }
 /* The storage id. With no transparent wrapper kinds, this is identity. */
 static inline KitCgTypeId kit_cg_type_resolve_alias(KitCompiler* c,
                                                     KitCgTypeId id) {
   const KitCgTypeInfo* t = kit_cg_type_view(c, id);
   return t ? t->id : KIT_CG_TYPE_NONE;
 }
 static inline int kit_cg_type_is_void(KitCompiler* c, KitCgTypeId id) {
   const KitCgTypeInfo* t = kit_cg_type_view(c, id);
   return t && t->kind == KIT_CG_TYPE_VOID;
 }
 /* A function result carries a value unless it is absent or the void builtin. */
 static inline int kit_cg_func_result_has_value(KitCompiler* c,
                                                KitCgFuncResult result) {
   return result.type != KIT_CG_TYPE_NONE &&
          !kit_cg_type_is_void(c, result.type);
 }
 KIT_API uint64_t kit_cg_type_size(KitCompiler*, KitCgTypeId);
 KIT_API uint32_t kit_cg_type_align(KitCompiler*, KitCgTypeId);
 KIT_API uint32_t kit_cg_type_int_width(KitCompiler*, KitCgTypeId);
 KIT_API uint32_t kit_cg_type_float_width(KitCompiler*, KitCgTypeId);
 
 KIT_API KitCgTypeId kit_cg_type_ptr_pointee(KitCompiler*, KitCgTypeId);
 KIT_API uint32_t kit_cg_type_ptr_address_space(KitCompiler*, KitCgTypeId);
 KIT_API KitCgTypeId kit_cg_type_array_elem(KitCompiler*, KitCgTypeId);
 KIT_API uint64_t kit_cg_type_array_count(KitCompiler*, KitCgTypeId);
 
 /* The function's result. A no-value result uses the void builtin type id. */
 KIT_API KitCgFuncResult kit_cg_type_func_result(KitCompiler*, KitCgTypeId);
 KIT_API uint32_t kit_cg_type_func_nparams(KitCompiler*, KitCgTypeId);
 KIT_API KitCgFuncParam kit_cg_type_func_param(KitCompiler*, KitCgTypeId,
                                               uint32_t index);
 KIT_API KitCgCallConv kit_cg_type_func_call_conv(KitCompiler*, KitCgTypeId);
 KIT_API int kit_cg_type_func_is_variadic(KitCompiler*, KitCgTypeId);
 
 KIT_API KitSym kit_cg_type_record_tag(KitCompiler*, KitCgTypeId);
 KIT_API int kit_cg_type_record_is_union(KitCompiler*, KitCgTypeId);
 KIT_API uint32_t kit_cg_type_record_nfields(KitCompiler*, KitCgTypeId);
 /* Borrow the computed layout of a complete, sized record: total size/align and
  * each field's byte offset and bit geometry. Returns NULL for an invalid id, a
  * non-record, or an incomplete/unsized record. The returned pointer is owned by
  * CG and stable for the compiler's lifetime; frontends cache it instead of
  * copying offsets into a parallel layout table. Replaces per-field record
  * queries — fetch once and index fields[] directly. */
 KIT_API const KitCgRecordLayout* kit_cg_type_record_layout(KitCompiler*,
                                                            KitCgTypeId);
 
 KIT_API KitSym kit_cg_type_enum_tag(KitCompiler*, KitCgTypeId);
 KIT_API KitCgTypeId kit_cg_type_enum_base(KitCompiler*, KitCgTypeId);
 KIT_API uint32_t kit_cg_type_enum_nvalues(KitCompiler*, KitCgTypeId);
 KIT_API KitStatus kit_cg_type_enum_value(KitCompiler*, KitCgTypeId,
                                          uint32_t index, KitCgEnumValue* out);
 
 /* ============================================================
  * Debug Type Information
  * ============================================================ */
 
 /* Debug base-type encoding. Mirrors the producer's DEBUG_BE_* set so frontends
  * can round-trip source signedness into debug info without storage carrying it.
  */
 typedef enum KitCgDebugEncoding {
   KIT_CG_DEBUG_ENC_NONE,
   KIT_CG_DEBUG_ENC_BOOL,
   KIT_CG_DEBUG_ENC_SIGNED,
   KIT_CG_DEBUG_ENC_UNSIGNED,
   KIT_CG_DEBUG_ENC_SIGNED_CHAR,
   KIT_CG_DEBUG_ENC_UNSIGNED_CHAR,
   KIT_CG_DEBUG_ENC_FLOAT,
 } KitCgDebugEncoding;
 
 /* Debug type builders. These return KIT_CG_DEBUG_TYPE_NONE when debug emission
  * is not active on the KitCg session. The resulting handles are owned by that
  * session and are valid only for declaration attributes passed to the same
  * session. */
 KIT_API KitCgDebugType kit_cg_debug_base(KitCg*, KitSym name,
                                          KitCgDebugEncoding, uint32_t bytes);
 KIT_API KitCgDebugType kit_cg_debug_typedef(KitCg*, KitSym name,
                                             KitCgDebugType base);
 KIT_API KitCgDebugType kit_cg_debug_ptr(KitCg*, KitCgDebugType pointee);
 KIT_API KitCgDebugType kit_cg_debug_array(KitCg*, KitCgDebugType elem,
                                           uint64_t count);
 KIT_API KitCgDebugType kit_cg_debug_func(KitCg*, KitCgDebugType ret,
                                          const KitCgDebugType* params,
                                          uint32_t nparams, int variadic);
 KIT_API KitCgDebugType kit_cg_debug_enum(KitCg*, KitCgTypeId enum_type,
                                          KitCgDebugType base);
 KIT_API KitCgDebugType kit_cg_debug_of_type(KitCg*, KitCgTypeId);
 
 /* ============================================================
  * Target Facts
  * ============================================================ */
 
 typedef enum KitCgBackendFeatureFlag {
   KIT_CG_BACKEND_UNALIGNED_MEMORY = 1ull << 0,
   KIT_CG_BACKEND_STRICT_ALIGNMENT = 1ull << 1,
   KIT_CG_BACKEND_RED_ZONE = 1ull << 2,
   KIT_CG_BACKEND_SIMD = 1ull << 3,
   KIT_CG_BACKEND_POINTER_AUTH = 1ull << 4,
   KIT_CG_BACKEND_BRANCH_PROTECTION = 1ull << 5,
   /* Instruction and data caches are coherent: freshly written code is
    * executable without an explicit cache-flush / instruction-sync sequence.
    * Set for x86 (snooping I-cache) and wasm (no hardware cache model). Not set
    * for aarch64 / RISC-V, where JITs and self-modifying code must issue an
    * explicit __clear_cache (IC/DC maintenance + ISB; fence.i) before running
    * newly emitted instructions. */
   KIT_CG_BACKEND_ICACHE_COHERENT = 1ull << 6,
 } KitCgBackendFeatureFlag;
 
 KIT_API uint64_t kit_cg_target_backend_features(KitCompiler*);
 
 /* Shape of the target's `va_list` object, as an ABI fact. Frontends that
  * lower <stdarg.h> consult this to pick the right va_list representation
  * without reaching into libkit-internal ABI tables:
  *   KIT_CG_VALIST_OPAQUE  : implementation-private blob.
  *   KIT_CG_VALIST_POINTER : a single pointer that walks the arg area.
  *   KIT_CG_VALIST_AAPCS64 : the AArch64 __va_list register-save record.
  *   KIT_CG_VALIST_SYSV_X64: the System V x86-64 register-save record. */
 typedef enum KitCgVaListKind {
   KIT_CG_VALIST_OPAQUE,
   KIT_CG_VALIST_POINTER,
   KIT_CG_VALIST_AAPCS64,
   KIT_CG_VALIST_SYSV_X64,
 } KitCgVaListKind;
 KIT_API KitCgVaListKind kit_cg_target_va_list_kind(const KitCompiler*);
 
 /* The C source-level symbol prefix the active object format prepends on
  * disk: "_" for Mach-O, "" for ELF / COFF / Wasm. Never NULL. Drives the
  * preprocessor's __USER_LABEL_PREFIX__. */
 KIT_API const char* kit_cg_target_c_label_prefix(const KitCompiler*);
 
 /* Pointer width in bytes for an architecture, as a target fact independent of
  * any constructed KitTarget. Single source of truth for the byte-aligned
  * pointer size, so the object-format detector, the driver triple parser, and
  * any internal CG/link code agree on one mapping. Header-only (no KIT_API TU)
  * so it links anywhere the public headers reach — including arches that have no
  * codegen backend (x86_32 / arm32 / arm64 are still ABI-classifiable here).
  * wasm reports 4 (wasm32; wasm64's 8-byte width is carried on the target spec,
  * not the arch kind). Returns 0 for an unknown KitArchKind. */
 static inline uint8_t kit_arch_ptr_size(KitArchKind arch) {
   switch (arch) {
     case KIT_ARCH_X86_32:
     case KIT_ARCH_ARM_32:
     case KIT_ARCH_RV32:
     case KIT_ARCH_WASM:
       return 4u;
     case KIT_ARCH_X86_64:
     case KIT_ARCH_ARM_64:
     case KIT_ARCH_RV64:
       return 8u;
   }
   return 0u;
 }
 
 /* ============================================================
  * Declarations and Symbols
  * ============================================================ */
 
 typedef enum KitCgVisibility {
   /* Externally visible, object-format-default visibility. On ELF this maps to
    * STV_DEFAULT and remains preemptible when bind/output mode allow it. On
    * formats without an equivalent visibility field, this is the normal visible
    * symbol state. Local-bind symbols are still local. */
   KIT_CG_VIS_DEFAULT,
   KIT_CG_VIS_HIDDEN,
   KIT_CG_VIS_PROTECTED,
 } KitCgVisibility;
 
 typedef enum KitCgSymbolFlag {
   KIT_CG_SYMFLAG_NONE = 0,
   KIT_CG_SYM_USED = 1u << 0,
   KIT_CG_SYM_DLLIMPORT = 1u << 1,
   KIT_CG_SYM_DLLEXPORT = 1u << 2,
 } KitCgSymbolFlag;
 
 typedef struct KitCgSymbolAttrs {
   KitSymBind bind;
   KitCgVisibility visibility;
   uint32_t flags; /* KitCgSymbolFlag */
 } KitCgSymbolAttrs;
 
 typedef enum KitCgSymbolFeature {
   KIT_CG_SYMFEAT_WEAK,
   KIT_CG_SYMFEAT_PROTECTED_VISIBILITY,
   KIT_CG_SYMFEAT_DLLIMPORT,
   KIT_CG_SYMFEAT_DLLEXPORT,
   KIT_CG_SYMFEAT_COMDAT,
   KIT_CG_SYMFEAT_COMMON,
   KIT_CG_SYMFEAT_MERGE_SECTIONS,
   KIT_CG_SYMFEAT_CONSTRUCTOR_PRIORITY,
   KIT_CG_SYMFEAT_TLS_LOCAL_EXEC,
   KIT_CG_SYMFEAT_TLS_INITIAL_EXEC,
   KIT_CG_SYMFEAT_TLS_LOCAL_DYNAMIC,
   KIT_CG_SYMFEAT_TLS_GENERAL_DYNAMIC,
 } KitCgSymbolFeature;
 
 /* Whether the selected target supports a symbol feature; see
  * kit_cg_target_supports_call_conv for the capability-query contract. */
 KIT_API int kit_cg_target_supports_symbol_feature(KitCompiler*,
                                                   KitCgSymbolFeature);
 
 typedef enum KitCgFuncFlag {
   KIT_CG_FUNC_NONE = 0,
   KIT_CG_FUNC_NORETURN = 1u << 0,
   KIT_CG_FUNC_IFUNC = 1u << 1,
   KIT_CG_FUNC_COLD = 1u << 2,
   KIT_CG_FUNC_HOT = 1u << 3,
   KIT_CG_FUNC_NAKED = 1u << 4,
   KIT_CG_FUNC_INTERRUPT = 1u << 5,
   KIT_CG_FUNC_NO_RED_ZONE = 1u << 6,
 } KitCgFuncFlag;
 
 typedef enum KitCgInlinePolicy {
   KIT_CG_INLINE_DEFAULT,
   KIT_CG_INLINE_HINT,
   KIT_CG_INLINE_ALWAYS,
   KIT_CG_INLINE_NEVER,
 } KitCgInlinePolicy;
 
 typedef struct KitCgFuncAttrs {
   uint32_t flags;       /* KitCgFuncFlag */
   uint32_t stack_align; /* 0 = ABI default */
   KitSym section;       /* 0 = target default */
   KitSym target_features;
   KitCgInlinePolicy inline_policy;
   KitCgDebugType debug_type; /* 0 = derive from declared function type */
   /* Wasm-target import descriptor. Honored only by the wasm backend, ignored
    * by other targets. Promotes an undefined function symbol into a wasm
    * `(import "<module>" "<name>" ...)` entry instead of a missing definition.
    * Both 0 leaves the backend to fall back to module="env", name=<sym name>
    * when an undefined function is referenced. */
   KitSym wasm_import_module;
   KitSym wasm_import_name;
 } KitCgFuncAttrs;
 
 typedef enum KitCgTlsModel {
   /* Let the target/backend choose from the symbol properties, visibility,
    * output mode, and object format. Non-AUTO values are frontend requests
    * from source attributes or driver options; unsupported requests should be
    * diagnosed or conservatively widened. Object-format mechanisms such as
    * Mach-O TLVP are target-selected implementation details. */
   KIT_CG_TLS_AUTO,
   KIT_CG_TLS_LOCAL_EXEC,
   KIT_CG_TLS_INITIAL_EXEC,
   KIT_CG_TLS_LOCAL_DYNAMIC,
   KIT_CG_TLS_GENERAL_DYNAMIC,
 } KitCgTlsModel;
 
 typedef enum KitCgObjectFlag {
   KIT_CG_OBJ_NONE = 0,
   KIT_CG_OBJ_READONLY = 1u << 0,
   KIT_CG_OBJ_TLS = 1u << 1,
 } KitCgObjectFlag;
 
 typedef struct KitCgObjectAttrs {
   KitCgTlsModel tls_model;
   uint32_t flags;            /* KitCgObjectFlag */
   KitSym section;            /* 0 = target default */
   uint32_t align;            /* 0 = natural */
   KitCgDebugType debug_type; /* 0 = derive from object type */
 } KitCgObjectAttrs;
 
 typedef enum KitCgDeclKind {
   KIT_CG_DECL_FUNC,
   KIT_CG_DECL_OBJECT,
 } KitCgDeclKind;
 
 typedef struct KitCgDecl {
   KitCgDeclKind kind;
   KitSym linkage_name; /* exact linker-visible spelling */
   KitSym display_name; /* optional source/debug spelling; 0 = linkage_name */
   KitCgTypeId type;
   KitCgSymbolAttrs sym;
   union {
     KitCgFuncAttrs func;
     KitCgObjectAttrs object;
   } as;
 } KitCgDecl;
 
 typedef struct KitCgAlias {
   KitSym linkage_name;
   KitSym display_name; /* optional source/debug spelling; 0 = linkage_name */
   KitCgSym target;
   KitCgSymbolAttrs sym;
 } KitCgAlias;
 
 /* The declared type is the function type for function declarations and the
  * object type for object declarations. linkage_name is already mangled and
  * object-format decorated as desired by the frontend; CG does not apply a
  * C-language name policy.
  *
  * Undefined weak references are ordinary declarations with sym.bind =
  * KIT_SB_WEAK and no definition. Weak aliases are aliases whose attrs bind
  * is KIT_SB_WEAK. */
 KIT_API KitCgSym kit_cg_decl(KitCg*, KitCgDecl decl);
 
 /* Defines alias.linkage_name as another symbol for alias.target. */
 KIT_API KitCgSym kit_cg_alias(KitCg*, KitCgAlias alias);
 
 /* Converts a source-level C ABI symbol spelling to the exact object/linker
  * spelling for the selected target. This is object-format decoration only
  * (for example Mach-O's leading underscore); language-specific mangling
  * remains the frontend's responsibility. Use this when filling
  * KitCgDecl.linkage_name for symbols that should interoperate with C entry
  * names, libc symbols, and linker entry lookup. */
 KIT_API KitSym kit_cg_c_linkage_name(KitCompiler*, KitSym source_name);
 
 /* ============================================================
  * Function Bodies and Locals
  * ============================================================ */
 
 KIT_API void kit_cg_func_begin(KitCg*, KitCgSym sym);
 KIT_API void kit_cg_func_begin_attrs(KitCg*, KitCgSym sym,
                                      KitCgFuncAttrs attrs);
 /* Enable stack-canary instrumentation for the current function. Call after
  * declaring parameters and before the first protected stack object is used.
  * Idempotent. A no-op when KitCodeOptions.stack_protector is NONE. CG snapshots
  * the target ABI guard, checks it before every subsequent return, and disables
  * sibling/tail exits for the function. */
 KIT_API void kit_cg_stack_protector_enable(KitCg*);
 KIT_API void kit_cg_func_end(KitCg*);
 
 /* Reclaim the storage of dead compiler temporaries. A frontend calls this at a
  * full-expression / statement boundary where it has consumed all values it
  * pushed (the value stack is empty); the single-pass -O0 backend then recycles
  * the frame homes of its per-subexpression temps, bounding the frame to
  * max-simultaneous-live temps. A no-op when the value stack is non-empty or the
  * backend does not recycle (optimizer / C-source targets). Purely an
  * optimization: omitting it only enlarges the frame. */
 KIT_API void kit_cg_reclaim_temps(KitCg*);
 
 typedef enum KitCgLocalFlag {
   KIT_CG_LOCALFLAG_NONE = 0,
   KIT_CG_LOCAL_ARTIFICIAL = 1u << 1,
   KIT_CG_LOCAL_OPTIMIZED_OUT = 1u << 2,
   KIT_CG_LOCAL_COMPILER_TEMP = 1u << 3,
   /* Force an addressable storage home even when the type is scalar. Frontends
    * use this for source objects whose accesses must remain memory operations
    * (for example C volatile automatic objects). */
   KIT_CG_LOCAL_MEMORY_REQUIRED = 1u << 4,
 } KitCgLocalFlag;
 
 typedef struct KitCgLocalAttrs {
   KitSym name;
   uint32_t align;            /* 0 = natural */
   uint32_t flags;            /* KitCgLocalFlag */
   KitCgDebugType debug_type; /* 0 = derive from local/param type */
 } KitCgLocalAttrs;
 
 KIT_API KitCgLocal kit_cg_local(KitCg*, KitCgTypeId type,
                                 KitCgLocalAttrs attrs);
 /* Declares a source parameter as a local handle. Parameters must be declared
  * in order before ordinary locals; therefore the first n parameter handles in
  * a function are also the first n local ids. */
 KIT_API KitCgLocal kit_cg_param(KitCg*, uint32_t index, KitCgTypeId type,
                                 KitCgLocalAttrs attrs);
 
 /* Pops a byte size and pushes a pointer to stack storage with at least align
  * alignment. The allocation lifetime is the current function activation. */
 KIT_API void kit_cg_alloca(KitCg*, uint32_t align, KitCgTypeId result_ptr_type);
 
 /* ============================================================
  * Control flow
  * ============================================================ */
 
 /* Structured control flow scopes.
  *
  * kit_cg_scope_begin / kit_cg_block_begin create statement scopes with no
  * result values. The *_value variants create single-result expression scopes;
  * result_type must be a valid non-void type id.
  *
  * Stack effects for a value scope:
  *   break(scope)       -> pop result, exit scope
  *   break_true(scope)  -> stack is [result, bool]; pop bool; if true, pop
  *                         result and exit; otherwise pop result
  *   break_false(scope) -> same but exit on false
  *   scope_end(scope)   -> TOS is the fallthrough result
  *
  * continue/continue_true/continue_false never carry a result; they jump to
  * the loop header, not the scope exit. */
 KIT_API KitCgScope kit_cg_scope_begin(KitCg*);
 KIT_API KitCgScope kit_cg_scope_begin_value(KitCg*, KitCgTypeId result_type);
 
 /* Like kit_cg_scope_begin but opens a forward-only block: break exits past
  * the scope; continue is not legal. This is the natural shape for `if`/
  * `if-else` (a wrapping block whose break is "skip the rest"), and lets
  * backends with structured control flow (Wasm) emit `block`/`end` directly
  * instead of recognizing arbitrary forward-only label-and-jump patterns. */
 KIT_API KitCgScope kit_cg_block_begin(KitCg*);
 KIT_API KitCgScope kit_cg_block_begin_value(KitCg*, KitCgTypeId result_type);
 
 /* Multi-value scopes: a block/loop that carries N params and/or N results
  * (the value-stack analogue of a Wasm multi-value block). params/results are
  * listed value-stack bottom -> top.
  *
  *   block_begin_sig: params stay on the value stack for the body to consume;
  *     break / scope_end carry `nresults` values across the exit edge.
  *   scope_begin_sig (loop): the API snapshots the `nparams` params off the
  *     stack into loop-param locals, then reloads them so every back edge sees
  *     the same shape. A back edge re-supplies fresh params via
  *     kit_cg_scope_store_params (which pops `nparams` into those locals, no
  *     jump) followed by a jump to kit_cg_scope_continue_label.
  *
  * kit_cg_scope_begin / kit_cg_block_begin are the nparams==0, nresults==0
  * special cases; the *_value variants are nparams==0, nresults==1.
  * Results must be valid non-void type ids. break, break_true, break_false, the
  * continue ops and scope_end all generalize to N values. */
 typedef struct KitCgScopeSig {
   const KitCgTypeId* params; /* value-stack bottom -> top */
   uint32_t nparams;
   const KitCgTypeId* results; /* value-stack bottom -> top */
   uint32_t nresults;
 } KitCgScopeSig;
 KIT_API KitCgScope kit_cg_scope_begin_sig(KitCg*,
                                           const KitCgScopeSig*); /*loop*/
 KIT_API KitCgScope kit_cg_block_begin_sig(KitCg*, const KitCgScopeSig*);
 /* Pop `nparams` values into the loop's param locals (bottom->top), without
  * jumping. The caller then jumps kit_cg_scope_continue_label to take the back
  * edge. Valid only on a loop scope (one opened with a continue label). */
 KIT_API void kit_cg_scope_store_params(KitCg*, KitCgScope);
 
 KIT_API void kit_cg_scope_end(KitCg*, KitCgScope);
 /* Close a scope whose fall-through is unreachable (its body ended in a
  * branch/return so there are no fall-through results to consume). Unlike
  * kit_cg_scope_end it does not pop results off the stack; the value stack must
  * already be at the scope's base depth. The scope's results (set by whatever
  * branch exited it) are pushed on exit, exactly as kit_cg_scope_end does. */
 KIT_API void kit_cg_scope_end_unreachable(KitCg*, KitCgScope);
 /* Expose the labels CG minted for this scope. Frontends that emit
  * unstructured `jump`/`branch` ops (rather than going through the
  * scope_break/scope_continue helpers) can use these to land control at
  * the scope's break/continue points — handy when the same backend needs
  * to translate label-targeted jumps back into structured `break;`/
  * `continue;` later (the C source target does this). */
 KIT_API KitCgLabel kit_cg_scope_break_label(KitCg*, KitCgScope);
 KIT_API KitCgLabel kit_cg_scope_continue_label(KitCg*, KitCgScope);
 KIT_API void kit_cg_break(KitCg*, KitCgScope);
 KIT_API void kit_cg_break_true(KitCg*, KitCgScope);
 KIT_API void kit_cg_break_false(KitCg*, KitCgScope);
 KIT_API void kit_cg_continue(KitCg*, KitCgScope);
 KIT_API void kit_cg_continue_true(KitCg*, KitCgScope);
 KIT_API void kit_cg_continue_false(KitCg*, KitCgScope);
 
 /* Unstructured labels and jumps. */
 KIT_API KitCgLabel kit_cg_label_new(KitCg*);
 KIT_API void kit_cg_label_place(KitCg*, KitCgLabel);
 KIT_API void kit_cg_jump(KitCg*, KitCgLabel);
 KIT_API void kit_cg_branch_true(KitCg*, KitCgLabel);
 KIT_API void kit_cg_branch_false(KitCg*, KitCgLabel);
 
 typedef struct KitCgSwitchCase {
   uint64_t value; /* bit pattern interpreted using selector_type */
   KitCgLabel label;
 } KitCgSwitchCase;
 
 typedef enum KitCgSwitchHint {
   KIT_CG_SWITCH_TARGET_DEFAULT,
   KIT_CG_SWITCH_BRANCH_CHAIN,
   KIT_CG_SWITCH_JUMP_TABLE,
 } KitCgSwitchHint;
 
 typedef struct KitCgSwitch {
   KitCgTypeId selector_type;
   KitCgLabel default_label;
   const KitCgSwitchCase* cases;
   uint32_t ncases;
   KitCgSwitchHint hint;
 } KitCgSwitch;
 
 /* Pops an integer selector and branches to the case whose value matches
  * it, or to default_label if none does. Mirrors the shape of C's
  * `switch (val) { case V1: ...; default: ...; }`. Frontends that want
  * jump-table dispatch (wasm br_table, computed-goto-style direct
  * threading) pass dense case values 0..N-1 — backends can detect the
  * shape and emit a real table; the C target lets the host compiler
  * decide. The hint is advisory; targets may ignore it. */
 KIT_API void kit_cg_switch(KitCg*, KitCgSwitch sw);
 
 /* Pushes the address of a label in the current function. Label addresses are
  * first-class pointer values for direct-threaded interpreters: they may be
  * stored, loaded, selected from tables, compared for equality, and consumed by
  * kit_cg_computed_goto. They are only valid within the defining function's
  * dynamic activation and must not be called or dereferenced as data. */
 KIT_API void kit_cg_push_label_addr(KitCg*, KitCgLabel, KitCgTypeId ptr_type);
 
 /* Pops a label address and branches to it. valid_targets must name the
  * non-empty closed set of labels the target may resolve to; targets use it
  * for validation, CFG construction, and branch-protection lowering. */
 KIT_API void kit_cg_computed_goto(KitCg*, const KitCgLabel* valid_targets,
                                   uint32_t ntargets);
 
 /* Terminates the current block with unreachable code. This is a real
  * terminator, not a side-effect intrinsic. */
 KIT_API void kit_cg_unreachable(KitCg*);
 
 /* ============================================================
  * Memory Access
  * ============================================================ */
 
 typedef enum KitCgMemAccessFlag {
   KIT_CG_MEM_NONE = 0,
   /* Access is an externally observable side effect and must not be merged,
    * removed, or reordered across other volatile accesses. */
   KIT_CG_MEM_VOLATILE = 1u << 0,
   /* Backend hint (loads only): emit a sign-extending narrow load when
    * supported. Frontends normally set KIT_CG_MEM_SOURCE_SIGNED and let
    * kit_cg_load derive this for byte/half integer loads; direct callers may
    * still set it when they already know the following use is sign-extension.
    * Ignored on stores and bit-fields. */
   KIT_CG_MEM_SEXT_LOAD = 1u << 1,
   /* The source-language object being accessed is a signed integer. KitCgTypeId
    * intentionally carries width/category, not C signedness, so this keeps the
    * source semantic fact separate from the backend SEXT-load hint above. */
   KIT_CG_MEM_SOURCE_SIGNED = 1u << 2,
 } KitCgMemAccessFlag;
 
 typedef struct KitCgMemAccess {
   KitCgTypeId type;       /* value type loaded/stored, or element type */
   uint32_t align;         /* 0 = natural for type */
   uint32_t address_space; /* normally inherited from pointer type */
   uint32_t flags;         /* KitCgMemAccessFlag */
 } KitCgMemAccess;
 
 /* ============================================================
  * Value stack: PLACES and VALUES
  * ============================================================
  *
  * Every stack entry is exactly one of two kinds, and each op below declares the
  * kinds it consumes and produces. The op enforces this: handing an op the wrong
  * kind is a usage error and panics. CG never *infers* the kind of a stack entry
  * or silently inserts a dereference — addressing is always built explicitly.
  *
  *   PLACE  — an addressable, typed location of an object (a local's storage, a
  *            global, or a computed `[base + index*scale + offset]`). Produced
  * by push_local / deref / field / elem; consumed by load / store / addr.
  *
  *   VALUE  — a scalar rvalue: an integer, float, pointer, or 128-bit scalar.
  *            Produced by push_int/float/null, push_symbol_addr,
  * push_local_addr, addr, and load; consumed by the arithmetic / call / branch
  * ops.
  *
  * Aggregates (records, arrays) are ALWAYS a PLACE — there is no aggregate
  * VALUE. Copying an aggregate is an explicit store/memcpy between places.
  *
  * The four building blocks of addressing:
  *   - push_local l : —            -> PLACE          (the local's storage)
  *   - addr         : PLACE        -> VALUE(ptr)     (address of the place)
  *   - deref        : VALUE(ptr)   -> PLACE          (the place the ptr names)
  *   - field i      : PLACE(record)-> PLACE(field)   (sub-object, by layout)
  *   - elem         : VALUE(ptr),index VALUE -> PLACE (element of an array/ptr)
  * From these, `*p` is `deref`, `p->f` is `deref; field`, `s.f` is `field`,
  * `a[i]` is `addr; <decay to *elem>; elem`, and `&x` is `addr`. */
 
 KIT_API void kit_cg_dup(KitCg*);
 KIT_API void kit_cg_dup2(KitCg*); /* duplicates the top two slots */
 KIT_API void kit_cg_swap(KitCg*);
 KIT_API void kit_cg_drop(KitCg*);
 KIT_API void kit_cg_rot3(KitCg*); /* [..., a, b, c] -> [..., b, c, a] */
 
 typedef struct KitCgSlotInfo {
   KitCgTypeId cg_type;
   const void* lang_type;
   uint16_t lang_flags;
 } KitCgSlotInfo;
 
 /* Inspect and update frontend-owned facts on value-stack slots. CG treats
  * lang_type as opaque and lang_flags as frontend-defined bits; stack-producing
  * operations clear them, while structural stack operations copy/move them with
  * the slot. depth_from_top 0 names TOS.
  *
  * kit_cg_slot_info returns the whole {cg_type, lang_type, lang_flags} fact by
  * value (a zeroed struct when the slot does not exist). The narrower accessors
  * read one field directly with no copy and return zero/NULL when the slot does
  * not exist; prefer them on hot paths that need a single fact. */
 KIT_API KitCgSlotInfo kit_cg_slot_info(KitCg*, uint32_t depth_from_top);
 KIT_API KitCgTypeId kit_cg_slot_cg_type(KitCg*, uint32_t depth_from_top);
 KIT_API const void* kit_cg_slot_lang_type(KitCg*, uint32_t depth_from_top);
 KIT_API uint16_t kit_cg_slot_lang_flags(KitCg*, uint32_t depth_from_top);
 KIT_API void kit_cg_retag_top(KitCg*, const void* lang_type,
                               uint16_t lang_flags);
 KIT_API void kit_cg_retag_at(KitCg*, uint32_t depth_from_top,
                              const void* lang_type, uint16_t lang_flags);
 KIT_API void kit_cg_set_top_flags(KitCg*, uint16_t set, uint16_t clear);
 
 /* The current value-stack depth. Lets a frontend record a base depth and later
  * drop back to it (e.g. discarding the operands a Wasm polymorphic/unreachable
  * region left behind). */
 KIT_API uint32_t kit_cg_stack_depth(KitCg*);
 
 typedef struct KitCgConstInt {
   uint64_t lo;       /* low bits, always truncated to width */
   uint64_t hi;       /* high bits for width > 64 */
   uint16_t width;    /* 1..128 for integer constants */
   uint8_t is_signed; /* interpretation hint for convenience queries */
   uint8_t known;     /* 0 => not a compile-time integer constant */
 } KitCgConstInt;
 
 /* Suppress target emission while preserving value-stack shape and stack-owned
  * constant facts. Nested pushes are allowed; pop diagnoses underflow. */
 KIT_API void kit_cg_unevaluated_push(KitCg*);
 KIT_API void kit_cg_unevaluated_pop(KitCg*);
 
 /* Width-complete integer-constant query. Reads the stack-side constant payload,
  * not the emitted operand shape, and does not pop the value. */
 KIT_API int kit_cg_top_const_int_ex(KitCg*, KitCgConstInt* out_value);
 
 /* Convenience query for constants representable as one 64-bit lane. */
 KIT_API int kit_cg_top_const_i64(KitCg*, int64_t* out_value);
 
 /* Push a scalar integer VALUE with an explicit width-complete constant payload.
  * The value is truncated to the destination type width when that width is
  * integer-like and known. */
 KIT_API void kit_cg_push_const_int(KitCg*, KitCgTypeId type,
                                    const KitCgConstInt* value);
 
 /* Compatibility wrapper for older callers that only need a signed 64-bit
  * result. */
 KIT_API int kit_cg_top_const_int(KitCg*, int64_t* out_value);
 
 /* Push a scalar VALUE. */
 KIT_API void kit_cg_push_int(KitCg*, uint64_t value, KitCgTypeId type);
 KIT_API void kit_cg_push_float(KitCg*, double value, KitCgTypeId type);
 KIT_API void kit_cg_push_null(KitCg*, KitCgTypeId ptr_type);
 /* Push the PLACE that is the local's storage. Stack: [] -> [place]. */
 KIT_API void kit_cg_push_local(KitCg*, KitCgLocal local);
 /* Push the local's address as a pointer VALUE (sugar for push_local; addr).
  * Stack: [] -> [ptr]. */
 KIT_API void kit_cg_push_local_addr(KitCg*, KitCgLocal local);
 
 /* Anonymous immutable data. Returns a local readonly object symbol; callers
  * can materialize its address (a VALUE) with push_symbol_addr. pointee_type
  * describes the logical value at that address, enabling const_data +
  * push_symbol_addr + deref + load to materialize arbitrary-width constants. */
 KIT_API KitCgSym kit_cg_const_data(KitCg*, const uint8_t* data, size_t len,
                                    uint32_t align, KitCgTypeId pointee_type);
 
 /* Push &sym + addend as a pointer VALUE. For TLS objects this means the address
  * of the current thread's instance; the target chooses LE/IE/GD/TLVP or
  * equivalent lowering from the symbol attrs and output mode. Stack: [] ->
  * [ptr].
  */
 KIT_API void kit_cg_push_symbol_addr(KitCg*, KitCgSym sym, int64_t addend);
 
 /* PLACE -> VALUE(ptr): the address of the place (e.g. `&x`, or to pass/escape).
  * Stack: [place] -> [ptr]. Errors if TOS is not a PLACE. */
 KIT_API void kit_cg_addr(KitCg*);
 
 /* VALUE(ptr) -> PLACE: the explicit pointer->place transition. The produced
  * place is `*(ptr + offset bytes)`; `offset` is a byte displacement folded into
  * the addressing mode (0 for a plain `*p`). Stack: [ptr] -> [place]. Errors if
  * TOS is not a pointer VALUE — a PLACE must be turned into a pointer with
  * `addr` first; the op never guesses. */
 KIT_API void kit_cg_deref(KitCg*, int64_t offset);
 
 /* PLACE(record) -> PLACE(field): project a record place to one of its fields by
  * index; the byte offset and field type come from the record's layout (CG owns
  * layout). Stack: [place] -> [place]. Errors if TOS is not a record PLACE — for
  * `p->f` the frontend does `deref; field`, not `field` on a pointer.
  *
  * Bit-field PLACE subkind: when field_index names a bit-field, `field` projects
  * to a *bit-field place* — a PLACE that addresses the field's storage unit and
  * additionally carries the bit-field descriptor (bit offset/width, storage-unit
  * size, signedness) from the record layout. A bit-field place is a place like
  * any other: a plain `load` reads the field (extract + sign/zero-extend) and a
  * plain `store` writes it (read-modify-write insert). There is no separate
  * bit-field memop and no bit-field rider on KitCgMemAccess; the place is the
  * one and only carrier of bit-field geometry. `addr` and aggregate access on a
  * bit-field place are not legal (a bit-field has no addressable byte location);
  * the frontend rejects `&` / `sizeof` on a bit-field before reaching CG. */
 KIT_API void kit_cg_field(KitCg*, uint32_t field_index);
 
 /* PLACE -> PLACE: project to a byte-offset subobject with a frontend-supplied
  * field type. This is the layout-known counterpart to kit_cg_field: CG does no
  * record lookup, but still folds byte_offset into the place operand when the
  * target addressing mode can carry it. Bit-field geometry, if any, is attached
  * separately with kit_cg_field_bits. */
 KIT_API void kit_cg_field_at(KitCg*, int64_t byte_offset,
                              KitCgTypeId field_type);
 
 /* PLACE -> PLACE(bit-field): tag the TOS place as a bit-field place carrying
  * the given bit geometry. This is the manual-addressing counterpart to the
  * implicit bit-field projection `field` performs: a frontend that builds the
  * storage-unit place itself (deref/elem onto the storage unit) calls this to
  * attach the descriptor, after which a plain load/store extracts/inserts the
  * field. The place must address the field's storage unit. bit_storage_size is
  * the storage- unit size in bytes; bit_signed selects signed extraction on
  * load. Stack: [place] -> [place]. There is no separate bit-field memop — the
  * place is the one carrier of bit-field geometry. */
 KIT_API void kit_cg_field_bits(KitCg*, uint16_t bit_offset, uint16_t bit_width,
                                uint32_t bit_storage_size, int bit_signed);
 
 /* (VALUE(ptr to T), index VALUE) -> PLACE(T): the element at `*(base +
  * index*sizeof(T) + offset)`. The index is scaled by sizeof(T) (the pointer's
  * pointee) and the constant `offset` byte displacement is folded in, so the
  * place is a single `[base + index*scale + offset]` addressing mode (base and
  * index dynamic; scale and offset constant). The base is a pointer VALUE; an
  * array is decayed to a pointer (`addr` + cast to *T) by the frontend first.
  * Stack: [base, index] -> [place]. Errors if the base is not a pointer VALUE.
  */
 KIT_API void kit_cg_elem(KitCg*, int64_t offset);
 
 /* Like kit_cg_elem, but the index is scaled by an EXPLICIT `elem_size` instead
  * of the base pointer's pointee size, and the resulting place's access type is
  * the base pointee. Lets a frontend build `[base + index*elem_size + offset]`
  * where the index stride (the containing array's element size) differs from the
  * accessed sub-object's size — e.g. `arr[i].f` strides by sizeof(elem) while
  * accessing the field `f`. The caller bitcasts the base to the access type
  * first. Stack: [base, index] -> [place]. */
 KIT_API void kit_cg_elem_scaled(KitCg*, uint32_t elem_size, int64_t offset);
 
 /* Load a VALUE from a PLACE / store a VALUE into a PLACE. The PLACE carries all
  * addressing (built via push_local / deref / field / elem); the memop takes no
  * effective-address rider. When the PLACE is a bit-field place (produced by
  * `field` on a bit-field), the load/store extract/insert the field per the
  * descriptor the place carries — `access` then describes only the access type,
  * alignment, and volatility, never bit geometry. Both error if the addressed
  * operand is not a PLACE — a pointer VALUE must be `deref`'d first.
  *
  * Stack effects:
  *   load:  [place]        -> [value]
  *   store: [place, value] -> []
  *   store_keep: [place, value] -> [value] */
 KIT_API void kit_cg_load(KitCg*, KitCgMemAccess access);
 KIT_API void kit_cg_store(KitCg*, KitCgMemAccess access);
 KIT_API void kit_cg_store_keep(KitCg*, KitCgMemAccess access);
 
 /* ============================================================
  * ABI variadic argument access
  * ============================================================ */
 
 /* This models only target calling-convention varargs; higher-level rest
  * parameters should lower to explicit aggregate parameters before reaching CG.
  *
  * The frontend allocates a local of KIT_CG_BUILTIN_VARARG_STATE and pushes
  * that local's address before each operation. The implementation reads and
  * writes the state in memory according to the target ABI. */
 KIT_API void kit_cg_vararg_start(KitCg*); /* pop &state */
 KIT_API void kit_cg_vararg_next(KitCg*,
                                 KitCgTypeId type); /* pop &state; push value */
 KIT_API void kit_cg_vararg_end(KitCg*);            /* pop &state             */
 KIT_API void kit_cg_vararg_copy(KitCg*);           /* pop &dst, &src         */
 
 /* ============================================================
  * Integer Operations
  * ============================================================ */
 
 typedef enum KitCgIntBinOp {
   KIT_CG_INT_ADD,
   KIT_CG_INT_SUB,
   KIT_CG_INT_MUL,
   KIT_CG_INT_SDIV,
   KIT_CG_INT_UDIV,
   KIT_CG_INT_SREM,
   KIT_CG_INT_UREM,
   KIT_CG_INT_AND,
   KIT_CG_INT_OR,
   KIT_CG_INT_XOR,
   KIT_CG_INT_SHL,
   KIT_CG_INT_LSHR,
   KIT_CG_INT_ASHR,
 } KitCgIntBinOp;
 
 typedef enum KitCgIntOpFlag {
   KIT_CG_INTOP_NONE = 0,
   KIT_CG_INTOP_NSW = 1u << 0,
   KIT_CG_INTOP_NUW = 1u << 1,
   KIT_CG_INTOP_EXACT = 1u << 2,
   /* Overflow semantics are explicit because integer types are width-only.
    * Signed and unsigned trap/saturate flags are mutually exclusive. */
   KIT_CG_INTOP_TRAP_SIGNED_OVERFLOW = 1u << 3,
   KIT_CG_INTOP_TRAP_UNSIGNED_OVERFLOW = 1u << 4,
   KIT_CG_INTOP_SATURATE_SIGNED = 1u << 5,
   KIT_CG_INTOP_SATURATE_UNSIGNED = 1u << 6,
 } KitCgIntOpFlag;
 
 typedef enum KitCgIntCmpOp {
   KIT_CG_INT_EQ,
   KIT_CG_INT_NE,
   KIT_CG_INT_LT_S,
   KIT_CG_INT_LE_S,
   KIT_CG_INT_GT_S,
   KIT_CG_INT_GE_S,
   KIT_CG_INT_LT_U,
   KIT_CG_INT_LE_U,
   KIT_CG_INT_GT_U,
   KIT_CG_INT_GE_U,
 } KitCgIntCmpOp;
 
 typedef enum KitCgIntUnOp {
   KIT_CG_INT_NEG,
   KIT_CG_INT_NOT,
   KIT_CG_INT_BNOT,
 } KitCgIntUnOp;
 
 KIT_API void kit_cg_int_binop(KitCg*, KitCgIntBinOp, uint32_t flags);
 KIT_API void kit_cg_int_unop(KitCg*, KitCgIntUnOp, uint32_t flags);
 KIT_API void kit_cg_int_cmp(KitCg*, KitCgIntCmpOp);
 
 /* ============================================================
  * Floating-Point Operations
  * ============================================================ */
 
 typedef enum KitCgFpBinOp {
   KIT_CG_FP_ADD,
   KIT_CG_FP_SUB,
   KIT_CG_FP_MUL,
   KIT_CG_FP_DIV,
   /* No FP remainder: it is a libcall (fmod/fmodf/fmodl), which the frontend
    * emits directly. */
 } KitCgFpBinOp;
 
 typedef enum KitCgFpCmpOp {
   KIT_CG_FP_OEQ,
   KIT_CG_FP_ONE,
   KIT_CG_FP_OLT,
   KIT_CG_FP_OLE,
   KIT_CG_FP_OGT,
   KIT_CG_FP_OGE,
   KIT_CG_FP_UEQ,
   KIT_CG_FP_UNE,
   KIT_CG_FP_ULT,
   KIT_CG_FP_ULE,
   KIT_CG_FP_UGT,
   KIT_CG_FP_UGE,
 } KitCgFpCmpOp;
 
 typedef enum KitCgFpUnOp {
   KIT_CG_FP_NEG,
 } KitCgFpUnOp;
 
 typedef enum KitCgFpFlag {
   KIT_CG_FP_NONE = 0,
   KIT_CG_FP_REASSOC = 1u << 0,
   KIT_CG_FP_NO_NANS = 1u << 1,
   KIT_CG_FP_NO_INFS = 1u << 2,
   KIT_CG_FP_NO_SIGNED_ZEROS = 1u << 3,
   KIT_CG_FP_ALLOW_RECIP = 1u << 4,
   KIT_CG_FP_APPROX = 1u << 5,
 } KitCgFpFlag;
 
 KIT_API void kit_cg_fp_binop(KitCg*, KitCgFpBinOp, uint32_t flags);
 KIT_API void kit_cg_fp_unop(KitCg*, KitCgFpUnOp, uint32_t flags);
 KIT_API void kit_cg_fp_cmp(KitCg*, KitCgFpCmpOp);
 
 /* ============================================================
  * Conversions
  * ============================================================ */
 
 typedef enum KitCgRounding {
   KIT_CG_ROUND_DEFAULT,
   KIT_CG_ROUND_NEAREST_EVEN,
   KIT_CG_ROUND_TOWARD_ZERO,
   KIT_CG_ROUND_DOWN,
   KIT_CG_ROUND_UP,
 } KitCgRounding;
 
 KIT_API void kit_cg_sext(KitCg*, KitCgTypeId dst);
 KIT_API void kit_cg_zext(KitCg*, KitCgTypeId dst);
 KIT_API void kit_cg_trunc(KitCg*, KitCgTypeId dst);
 KIT_API void kit_cg_ptr_to_int(KitCg*, KitCgTypeId dst);
 KIT_API void kit_cg_int_to_ptr(KitCg*, KitCgTypeId dst);
 KIT_API void kit_cg_bitcast(KitCg*, KitCgTypeId dst);
 KIT_API void kit_cg_fpext(KitCg*, KitCgTypeId dst);
 KIT_API void kit_cg_fptrunc(KitCg*, KitCgTypeId dst);
 KIT_API void kit_cg_sint_to_float(KitCg*, KitCgTypeId dst,
                                   KitCgRounding rounding);
 KIT_API void kit_cg_uint_to_float(KitCg*, KitCgTypeId dst,
                                   KitCgRounding rounding);
 KIT_API void kit_cg_float_to_sint(KitCg*, KitCgTypeId dst,
                                   KitCgRounding rounding);
 KIT_API void kit_cg_float_to_uint(KitCg*, KitCgTypeId dst,
                                   KitCgRounding rounding);
 
 /* ============================================================
  * Calls and Returns
  * ============================================================ */
 
 /* Tail-call policy for a call site.
  *
  * A tail call is a TERMINATOR: it ends the current function. It pushes no
  * result onto the value stack, and the caller must not emit kit_cg_ret
  * after it — the call is the return.
  *
  * Two distinct conditions govern whether a tail call is legal:
  *
  *  - Signature match is a PRECONDITION the frontend must guarantee: the
  *    callee's return type must be ABI-compatible with the enclosing
  *    function's declared return type, and the call must sit in return
  *    position. A violation is a frontend bug; CG aborts (compiler_panic)
  *    regardless of policy — it is never treated as a fallback case.
  *
  *  - ABI realizability is DISCOVERED during emission and is target-specific:
  *    can control transfer to the callee while reusing (and tearing down) the
  *    current frame, with the callee's outgoing argument area and return
  *    mechanism fitting the space the caller itself received? sret and
  *    variadic are NOT inherent blockers — an sret return is forwarded via the
  *    function's own incoming sret pointer, and a variadic callee is fine when
  *    its argument area fits the caller's incoming area. The usual blocker is
  *    an outgoing argument area that exceeds that space; some are arch-specific
  *    (e.g. wasm packs varargs into a caller-frame buffer that a sibling call
  *    would dangle). This is what ALLOWED vs MUST governs.
  */
 typedef enum KitCgTailPolicy {
   /* Ordinary call. Result is pushed; not a terminator. */
   KIT_CG_TAIL_DEFAULT,
   /* Tail-call (terminator) if ABI-realizable; otherwise silently emit an
    * ordinary call and synthesize the caller's return of the result. Never
    * fails for realizability. */
   KIT_CG_TAIL_ALLOWED,
   /* Tail-call (terminator); if not ABI-realizable, CG fails with a
    * diagnostic naming the reason. Never silently degrades to an ordinary
    * call. */
   KIT_CG_TAIL_MUST,
 } KitCgTailPolicy;
 
 typedef enum KitCgCallFlag {
   KIT_CG_CALL_NONE = 0,
   KIT_CG_CALL_COLD = 1u << 0,
 } KitCgCallFlag;
 
 typedef struct KitCgCallAttrs {
   KitCgTailPolicy tail;
   uint32_t flags; /* KitCgCallFlag */
   KitCgInlinePolicy inline_policy;
 } KitCgCallAttrs;
 
 /* kit_cg_call pops a computed function pointer plus nargs arguments.
  * kit_cg_call_symbol emits a direct call to the declared function symbol,
  * allowing the backend/linker to choose PLT/stub/IAT/direct/IFUNC handling.
  *
  * For tail policies (see KitCgTailPolicy): the call is a terminator that
  * pushes no result. A MUST tail call that is not ABI-realizable fails with a
  * diagnostic; an ALLOWED tail call that is not realizable silently degrades
  * to an ordinary call followed by a synthesized return of the result. A
  * tail call whose callee return type is incompatible with the enclosing
  * function's return type is a frontend bug and aborts under any policy.
  *
  * Results: a non-tail call to a value-returning callee pushes the callee's
  * single result onto the stack (TOS). A void callee pushes nothing. */
 KIT_API void kit_cg_call(KitCg*, uint32_t nargs, KitCgTypeId fn_type,
                          KitCgCallAttrs attrs);
 KIT_API void kit_cg_call_symbol(KitCg*, KitCgSym sym, uint32_t nargs,
                                 KitCgCallAttrs attrs);
 /* Returns from the current function. Pops the enclosing function's single
  * result value from TOS, or nothing for a void function. This is the single
  * return entry point. */
 KIT_API void kit_cg_ret(KitCg*);
 
 /* ============================================================
  * Intrinsics
  * ============================================================ */
 
 typedef enum KitCgIntrinsic {
   KIT_CG_INTRIN_TRAP,
   KIT_CG_INTRIN_CLZ, /* zero input returns bit width     */
   KIT_CG_INTRIN_CTZ, /* zero input returns bit width     */
   KIT_CG_INTRIN_POPCOUNT,
   KIT_CG_INTRIN_BSWAP,
   KIT_CG_INTRIN_SETJMP,         /* pop &buf; push i32              */
   KIT_CG_INTRIN_LONGJMP,        /* pop &buf, val; no return        */
   KIT_CG_INTRIN_SADD_OVERFLOW,  /* pop a, b; push result, overflow */
   KIT_CG_INTRIN_UADD_OVERFLOW,  /* pop a, b; push result, overflow */
   KIT_CG_INTRIN_SSUB_OVERFLOW,  /* pop a, b; push result, overflow */
   KIT_CG_INTRIN_USUB_OVERFLOW,  /* pop a, b; push result, overflow */
   KIT_CG_INTRIN_SMUL_OVERFLOW,  /* pop a, b; push result, overflow */
   KIT_CG_INTRIN_UMUL_OVERFLOW,  /* pop a, b; push result, overflow */
   KIT_CG_INTRIN_FMA,            /* pop a, b, c; push a * b + c     */
   KIT_CG_INTRIN_PREFETCH,       /* pop addr; no result             */
   KIT_CG_INTRIN_EXPECT,         /* pop val, expected; push val     */
   KIT_CG_INTRIN_ASSUME_ALIGNED, /* pop ptr; push aligned ptr       */
   KIT_CG_INTRIN_SYSCALL,        /* pop nr, args...; push long      */
   KIT_CG_INTRIN_IRQ_SAVE,       /* push unsigned long              */
   KIT_CG_INTRIN_IRQ_RESTORE,    /* pop prev                        */
   KIT_CG_INTRIN_IRQ_DISABLE,
   KIT_CG_INTRIN_IRQ_ENABLE,
   KIT_CG_INTRIN_DMB, /* pop KitCgBarrierScope         */
   KIT_CG_INTRIN_DSB, /* pop KitCgBarrierScope         */
   KIT_CG_INTRIN_ISB,
   KIT_CG_INTRIN_DCACHE_CLEAN, /* pop ptr, size                   */
   KIT_CG_INTRIN_DCACHE_INVALIDATE,
   KIT_CG_INTRIN_DCACHE_CLEAN_INVALIDATE,
   KIT_CG_INTRIN_ICACHE_INVALIDATE,
   KIT_CG_INTRIN_CPU_NOP,
   KIT_CG_INTRIN_CPU_YIELD,
   KIT_CG_INTRIN_WFI,
   KIT_CG_INTRIN_WFE,         /* arm/aarch64 only                */
   KIT_CG_INTRIN_SEV,         /* arm/aarch64 only                */
   KIT_CG_INTRIN_CORO_SWITCH, /* pop from, to, value; push value */
   /* Frame-pointer-chain introspection (GCC __builtin_frame_address /
    * __builtin_return_address). The level is a compile-time constant passed as a
    * single immediate operand (nargs == 1); level 0 names the current frame.
    * Both push a void*. Lowered as an unrolled FP walk; targets with no frame
    * pointer (wasm) report unsupported. */
   KIT_CG_INTRIN_FRAME_ADDRESS,  /* pop level(u32 const); push void* */
   KIT_CG_INTRIN_RETURN_ADDRESS, /* pop level(u32 const); push void* */
   /* Read the target cycle/timestamp counter (GCC/Clang
    * __builtin_readcyclecounter). No operands; pushes an unsigned 64-bit value.
    * Lowered to the native counter read (x86 RDTSC, aarch64 MRS CNTVCT_EL0,
    * riscv64 RDCYCLE). Targets without a single-register 64-bit counter read
    * report unsupported. */
   KIT_CG_INTRIN_READCYCLECOUNTER, /* push u64 */
   /* High half of a full-width integer product. Both pop two equal-width
    * integer operands and push a result of that width. SMUL_HIGH interprets
    * both operands as two's-complement signed; UMUL_HIGH is unsigned. */
   KIT_CG_INTRIN_SMUL_HIGH,
   KIT_CG_INTRIN_UMUL_HIGH,
 } KitCgIntrinsic;
 
 typedef enum KitCgBarrierScope {
   KIT_CG_BARRIER_FULL,
   KIT_CG_BARRIER_INNER,
   KIT_CG_BARRIER_INNER_STORE,
   KIT_CG_BARRIER_OUTER,
   KIT_CG_BARRIER_OUTER_STORE,
   KIT_CG_BARRIER_NON_SHARE,
 } KitCgBarrierScope;
 
 /* Pops nargs operands. result_type must be a valid type id; the void builtin
  * means no result is pushed. Overflow intrinsics push two values: result,
  * overflow_bool regardless of result_type. Syscall uses nargs = argc + 1: the
  * syscall number plus 0..6 long arguments. Runtime-extension intrinsics mirror
  * rt/include/kit/{syscall,baremetal,coro}.h and must diagnose targets where
  * the primitive has no legal lowering. */
 KIT_API void kit_cg_intrinsic(KitCg*, KitCgIntrinsic, uint32_t nargs,
                               KitCgTypeId result_type);
 
 /* Capability query for kit_cg_intrinsic: true when the selected target has a
  * legal lowering for this intrinsic (see kit_cg_target_supports_call_conv for
  * the contract). Frontends test this before requesting a baremetal/CPU
  * intrinsic so they can emit their own unsupported-feature diagnostic instead
  * of tripping the CG fatal. */
 KIT_API int kit_cg_target_supports_intrinsic(KitCompiler*, KitCgIntrinsic);
 
 /* ============================================================
  * Fixed-Sized Memory Operations
  * ============================================================ */
 
 /* Stack:
  *   memcpy/memmove: [dst, src] -> []
  *   memset:         [dst]      -> [] */
 KIT_API void kit_cg_memcpy(KitCg*, uint64_t size, KitCgMemAccess dst,
                            KitCgMemAccess src);
 KIT_API void kit_cg_memmove(KitCg*, uint64_t size, KitCgMemAccess dst,
                             KitCgMemAccess src);
 KIT_API void kit_cg_memset(KitCg*, uint8_t val, uint64_t size,
                            KitCgMemAccess dst);
 
 /* ============================================================
  * Atomics
  * ============================================================ */
 
 typedef enum KitCgAtomicOp {
   KIT_CG_ATOMIC_XCHG,
   KIT_CG_ATOMIC_ADD,
   KIT_CG_ATOMIC_SUB,
   KIT_CG_ATOMIC_AND,
   KIT_CG_ATOMIC_OR,
   KIT_CG_ATOMIC_XOR,
   KIT_CG_ATOMIC_NAND,
 } KitCgAtomicOp;
 
 typedef enum KitCgMemOrder {
   KIT_CG_MO_RELAXED,
   KIT_CG_MO_CONSUME,
   KIT_CG_MO_ACQUIRE,
   KIT_CG_MO_RELEASE,
   KIT_CG_MO_ACQ_REL,
   KIT_CG_MO_SEQ_CST,
 } KitCgMemOrder;
 
 KIT_API int kit_cg_atomic_is_legal(KitCompiler*, KitCgMemAccess access,
                                    KitCgMemOrder order);
 KIT_API int kit_cg_atomic_is_lock_free(KitCompiler*, KitCgMemAccess access);
 KIT_API void kit_cg_atomic_load(KitCg*, KitCgMemAccess access,
                                 KitCgMemOrder order);
 KIT_API void kit_cg_atomic_store(KitCg*, KitCgMemAccess access,
                                  KitCgMemOrder order);
 KIT_API void kit_cg_atomic_rmw(KitCg*, KitCgMemAccess access, KitCgAtomicOp,
                                KitCgMemOrder order);
 /* Stack: [ptr, expected, desired] -> [prior, ok_bool]. */
 KIT_API void kit_cg_atomic_cmpxchg(KitCg*, KitCgMemAccess access,
                                    KitCgMemOrder success, KitCgMemOrder failure,
                                    int weak);
 KIT_API void kit_cg_atomic_fence(KitCg*, KitCgMemOrder);
 
 /* ============================================================
  * Inline Assembly
  * ============================================================ */
 
 typedef enum KitCgAsmDir {
   KIT_CG_ASM_IN,
   KIT_CG_ASM_OUT,
   KIT_CG_ASM_INOUT,
 } KitCgAsmDir;
 
 typedef enum KitCgAsmFlag {
   KIT_CG_ASM_NONE = 0,
   KIT_CG_ASM_VOLATILE = 1u << 0,
   KIT_CG_ASM_PURE = 1u << 1,
   KIT_CG_ASM_NOMEM = 1u << 2,
   KIT_CG_ASM_READONLY = 1u << 3,
   KIT_CG_ASM_PRESERVES_FLAGS = 1u << 4,
   KIT_CG_ASM_NOSTACK = 1u << 5,
   KIT_CG_ASM_NORETURN = 1u << 6,
 } KitCgAsmFlag;
 
 typedef enum KitCgAsmClobberAbiSet {
   KIT_CG_ASM_CLOBBER_ABI_NONE = 0,
   KIT_CG_ASM_CLOBBER_ABI_CALLER_SAVED = 1u << 0,
   /* Every callee-saved register of the target ABI. The compiler preserves them
    * across the asm block (prologue/epilogue save on the optimizer path, a
    * per-block spill on the single-pass path) just as it would for named
    * callee-saved clobbers — an arch-neutral way to say "this asm trashes the
    * callee-saved register file". */
   KIT_CG_ASM_CLOBBER_ABI_CALLEE_SAVED = 1u << 1,
 } KitCgAsmClobberAbiSet;
 
 typedef struct KitCgAsmOperand {
   KitSym constraint; /* interned target constraint string */
   KitSym name;       /* interned symbolic operand name; 0 if absent */
   KitCgTypeId type;
   /* Explicit hard register this operand must occupy, named by its target
    * spelling ("r10", "x8", "a7", ...); 0 when unconstrained. Set by a frontend
    * for a GNU local register variable (`register T x __asm__("r10")`) used as
    * an operand. The name is opaque to the frontend and CG — only the target's
    * register file resolves it to a physical register. */
   KitSym reg;
   uint8_t dir; /* KitCgAsmDir */
   uint8_t pad[3];
 } KitCgAsmOperand;
 
 typedef struct KitCgInlineAsm {
   KitSym tmpl;
   const KitCgAsmOperand* outputs;
   uint32_t noutputs;
   const KitCgAsmOperand* inputs;
   uint32_t ninputs;
   const KitSym* clobbers;
   uint32_t nclobbers;
   uint32_t flags;            /* KitCgAsmFlag */
   uint32_t clobber_abi_sets; /* KitCgAsmClobberAbiSet */
 } KitCgInlineAsm;
 
 /* Inputs are popped in declaration order. Outputs are pushed in declaration
  * order as fresh values after the asm block. INOUT outputs consume one
  * initial value each after the explicit inputs, in output declaration order;
  * tied operands, earlyclobber, register classes, explicit registers,
  * immediates, memory operands, and target-specific alternatives are expressed
  * in the per-operand constraint string. Template, constraints, and clobbers
  * are pre-interned strings. clobber_abi_sets names target-defined ABI register
  * sets such as all caller-saved registers. */
 KIT_API void kit_cg_inline_asm(KitCg*, KitCgInlineAsm asm_block);
 KIT_API void kit_cg_file_scope_asm(KitCg*, KitSlice asm_source);
 
 /* ============================================================
  * Data Definitions
  * ============================================================ */
 
 typedef enum KitCgDataDefFlag {
   KIT_CG_DATADEF_NONE = 0,
   KIT_CG_DATADEF_RETAIN = 1u << 0,
   KIT_CG_DATADEF_MERGE = 1u << 1,
   KIT_CG_DATADEF_STRINGS = 1u << 2,
   KIT_CG_DATADEF_READONLY = 1u << 3,
   KIT_CG_DATADEF_ZERO_FILL = 1u << 4,
   /* Static storage with function/block scope for source backends. Native
    * object backends may still emit ordinary private data. */
   KIT_CG_DATADEF_FUNCTION_LOCAL = 1u << 5,
 } KitCgDataDefFlag;
 
 typedef struct KitCgDataDefAttrs {
   KitSym section;   /* 0 = target default for the symbol */
   uint32_t align;   /* 0 = natural */
   uint32_t entsize; /* 0 = target default; used by merge/string data */
   uint32_t flags;   /* KitCgDataDefFlag */
 } KitCgDataDefAttrs;
 
 /* data_begin defines storage for an already-declared object symbol.
  * data_common defines tentative/common zero-initialized storage when the
  * target format supports it.
  *
  * Data definitions may be emitted while a function body is open. The current
  * function remains open across data_begin/data_end so frontends can define
  * block-scope statics and computed-goto dispatch tables that need function
  * label context. */
 KIT_API void kit_cg_data_begin(KitCg*, KitCgSym sym, KitCgDataDefAttrs attrs);
 KIT_API void kit_cg_data_common(KitCg*, KitCgSym sym, uint64_t size,
                                 uint32_t align);
 KIT_API void kit_cg_data_end(KitCg*);
 
 /* Appends to the currently open data definition. */
 KIT_API void kit_cg_data_align(KitCg*, uint32_t align);
 KIT_API void kit_cg_data_pad(KitCg*, uint64_t size, uint8_t value);
 KIT_API void kit_cg_data_int(KitCg*, uint64_t value, KitCgTypeId type);
 KIT_API void kit_cg_data_float(KitCg*, double value, KitCgTypeId type);
 KIT_API void kit_cg_data_bytes(KitCg*, const uint8_t* data, size_t len);
 KIT_API void kit_cg_data_zero(KitCg*, uint64_t size);
 
 /* Relocatable data expressions. These describe the value encoded in the data
  * stream; they do not request a lowering strategy such as GOT, PLT, TLVP, or
  * a TLS access model. width is the encoded field width in bytes. address_space
  * is the pointer address space of address constants; use 0 for the target data
  * address space. */
 KIT_API void kit_cg_data_addr(KitCg*, KitCgSym target, int64_t addend,
                               uint32_t width, uint32_t address_space);
 /* Encodes a function-local label address for direct-threaded dispatch tables.
  * The target label must have been created by kit_cg_label_new; it does not
  * need to be placed yet, and the containing function must still be open so the
  * label-address object can be tied to that function's label namespace. This
  * supports the normal direct-threaded lowering: declare a dispatch-table
  * symbol, begin the function, create labels, emit the table as data while the
  * function is open, then resume code emission. The resulting value is an opaque
  * label-address pointer: it may be loaded, stored, compared for equality,
  * selected from tables, and consumed by kit_cg_computed_goto in the label's
  * defining function. It must not be called, dereferenced as data, or used by
  * another function's computed goto. */
 KIT_API void kit_cg_data_label_addr(KitCg*, KitCgLabel target, int64_t addend,
                                     uint32_t width, uint32_t address_space);
 KIT_API void kit_cg_data_pcrel(KitCg*, KitCgSym target, int64_t addend,
                                uint32_t width);
 KIT_API void kit_cg_data_symdiff(KitCg*, KitCgSym lhs, KitCgSym rhs,
                                  int64_t addend, uint32_t width);
 
 /* ============================================================
  * Static Inline Convenience Operations
  * ============================================================ */
 
 static inline void kit_cg_push_bytes(KitCg* cg, const uint8_t* data, size_t len,
                                      KitCgTypeId pointee_type) {
   KitCgSym sym = kit_cg_const_data(cg, data, len, 0, pointee_type);
   kit_cg_push_symbol_addr(cg, sym, 0);
 }
 
 static inline void kit_cg_call_default(KitCg* cg, uint32_t nargs,
                                        KitCgTypeId fn_type) {
   KitCgCallAttrs attrs;
   attrs.tail = KIT_CG_TAIL_DEFAULT;
   attrs.flags = 0;
   attrs.inline_policy = KIT_CG_INLINE_DEFAULT;
   kit_cg_call(cg, nargs, fn_type, attrs);
 }
 
 static inline void kit_cg_call_symbol_default(KitCg* cg, KitCgSym sym,
                                               uint32_t nargs) {
   KitCgCallAttrs attrs;
   attrs.tail = KIT_CG_TAIL_DEFAULT;
   attrs.flags = 0;
   attrs.inline_policy = KIT_CG_INLINE_DEFAULT;
   kit_cg_call_symbol(cg, sym, nargs, attrs);
 }
 
 static inline void kit_cg_tail_call(KitCg* cg, uint32_t nargs,
                                     KitCgTypeId fn_type) {
   KitCgCallAttrs attrs;
   attrs.tail = KIT_CG_TAIL_ALLOWED;
   attrs.flags = 0;
   attrs.inline_policy = KIT_CG_INLINE_DEFAULT;
   kit_cg_call(cg, nargs, fn_type, attrs);
 }
 
 static inline void kit_cg_tail_call_symbol(KitCg* cg, KitCgSym sym,
                                            uint32_t nargs) {
   KitCgCallAttrs attrs;
   attrs.tail = KIT_CG_TAIL_ALLOWED;
   attrs.flags = 0;
   attrs.inline_policy = KIT_CG_INLINE_DEFAULT;
   kit_cg_call_symbol(cg, sym, nargs, attrs);
 }
 
 static inline void kit_cg_musttail_call(KitCg* cg, uint32_t nargs,
                                         KitCgTypeId fn_type) {
   KitCgCallAttrs attrs;
   attrs.tail = KIT_CG_TAIL_MUST;
   attrs.flags = 0;
   attrs.inline_policy = KIT_CG_INLINE_DEFAULT;
   kit_cg_call(cg, nargs, fn_type, attrs);
 }
 
 static inline void kit_cg_musttail_call_symbol(KitCg* cg, KitCgSym sym,
                                                uint32_t nargs) {
   KitCgCallAttrs attrs;
   attrs.tail = KIT_CG_TAIL_MUST;
   attrs.flags = 0;
   attrs.inline_policy = KIT_CG_INLINE_DEFAULT;
   kit_cg_call_symbol(cg, sym, nargs, attrs);
 }
 
 /* Read the scalar value of a local. Stack: [] -> [value]. */
 static inline void kit_cg_local_read(KitCg* cg, KitCgLocal local,
                                      KitCgMemAccess access) {
   kit_cg_push_local(cg, local);
   kit_cg_load(cg, access);
 }
 
 /* Write the scalar value on TOS into a local. Stack: [value] -> []. */
 static inline void kit_cg_local_write(KitCg* cg, KitCgLocal local,
                                       KitCgMemAccess access) {
   kit_cg_push_local(cg, local); /* [value, lv] */
   kit_cg_swap(cg);              /* [lv, value] */
   kit_cg_store(cg, access);
 }
 
 /* Increment/decrement an lvalue in place. Stack: [lv] -> [result].
  * post=1 pushes the old value; post=0 pushes the new value.
  * op is KIT_CG_INT_ADD or KIT_CG_INT_SUB. ty is the promoted integer type
  * of the lvalue. */
 static inline void kit_cg_inc_dec(KitCg* cg, KitCgIntBinOp op, int post,
                                   KitCgTypeId ty, KitCgMemAccess access) {
   kit_cg_dup(cg);          /* [lv, lv] */
   kit_cg_load(cg, access); /* [lv, old] */
   if (post) {
     kit_cg_dup(cg);              /* [lv, old, old] */
     kit_cg_push_int(cg, 1, ty);  /* [lv, old, old, 1] */
     kit_cg_int_binop(cg, op, 0); /* [lv, old, new] */
     kit_cg_rot3(cg);             /* [old, new, lv] */
     kit_cg_swap(cg);             /* [old, lv, new] */
     kit_cg_store(cg, access);    /* [old] */
   } else {
     kit_cg_push_int(cg, 1, ty);  /* [lv, old, 1] */
     kit_cg_int_binop(cg, op, 0); /* [lv, new] */
     kit_cg_dup(cg);              /* [lv, new, new] */
     kit_cg_rot3(cg);             /* [new, new, lv] */
     kit_cg_swap(cg);             /* [new, lv, new] */
     kit_cg_store(cg, access);    /* [new] */
   }
 }
 
 /* `if (cond) then [else else_body]` lowering via two nested forward blocks.
  *
  *   outer = block_begin             (break = "end of if")
  *     inner = block_begin           (break = "else entry point")
  *       break_false(inner)          ; pop cond, skip then-body if false
  *       then-body
  *     if_else: break(outer); end inner
  *     [optional else-body]
  *   if_end: end outer
  *
  * Frontends must call kit_cg_if_else exactly once after the then-body
  * (even if there is no else clause — the call closes the inner block so
  * if_end can close only the outer). Using structured scopes means backends
  * that already lower BLOCK + break natively (every native arch and the Wasm
  * target) handle `if`/`if-else` without a CFG-to-structured pass. */
 typedef struct KitCgIf {
   KitCgScope outer;
   KitCgScope inner;
 } KitCgIf;
 
 static inline KitCgIf kit_cg_if_begin(KitCg* cg) {
   KitCgIf it;
   it.outer = kit_cg_block_begin(cg);
   it.inner = kit_cg_block_begin(cg);
   kit_cg_break_false(cg, it.inner);
   return it;
 }
 
 static inline void kit_cg_if_else(KitCg* cg, KitCgIf it) {
   kit_cg_break(cg, it.outer);
   kit_cg_scope_end(cg, it.inner);
 }
 
 static inline void kit_cg_if_end(KitCg* cg, KitCgIf it) {
   kit_cg_scope_end(cg, it.outer);
 }
 
 /* Extract bits [lo, lo+width) from TOS as an unsigned value.
  * Stack: [value] -> [field]. ty is the integer type of the value.
  * width < 64 masks with (1<<width)-1; width == 64 keeps all bits. */
 static inline void kit_cg_bitget(KitCg* cg, KitCgTypeId ty, uint32_t lo,
                                  uint32_t width) {
   if (lo > 0) {
     kit_cg_push_int(cg, lo, ty);
     kit_cg_int_binop(cg, KIT_CG_INT_LSHR, 0);
   }
   if (width < 64) {
     kit_cg_push_int(cg, (1ULL << width) - 1, ty);
     kit_cg_int_binop(cg, KIT_CG_INT_AND, 0);
   }
 }
 
 /* Insert the low width bits of src into dst at bit position lo.
  * Stack: [dst, src] -> [result]. ty is the integer type.
  * result = (dst & ~field_mask) | ((src << lo) & field_mask)
  * where field_mask = ((1<<width)-1) << lo. width < 64; for width == 64 use
  * bitget + shift + or directly. */
 static inline void kit_cg_bitset(KitCg* cg, KitCgTypeId ty, uint32_t lo,
                                  uint32_t width) {
   uint64_t field_mask = ((1ULL << width) - 1) << lo;
   uint64_t clear_mask = ~field_mask;
   kit_cg_swap(cg); /* [src, dst] */
   kit_cg_dup(cg);  /* [src, dst, dst] */
   kit_cg_push_int(cg, clear_mask, ty);
   kit_cg_int_binop(cg, KIT_CG_INT_AND, 0); /* [src, dst, dst_cleared] */
   kit_cg_rot3(cg);                         /* [dst, dst_cleared, src] */
   if (lo > 0) {
     kit_cg_push_int(cg, lo, ty);
     kit_cg_int_binop(cg, KIT_CG_INT_SHL, 0); /* [dst, dst_cleared, src<<lo] */
   }
   kit_cg_push_int(cg, field_mask, ty);
   kit_cg_int_binop(cg, KIT_CG_INT_AND, 0); /* [dst, dst_cleared, bits] */
   kit_cg_rot3(cg);                         /* [dst_cleared, bits, dst] */
   kit_cg_drop(cg);                         /* [dst_cleared, bits] */
   kit_cg_int_binop(cg, KIT_CG_INT_OR, 0);  /* [result] */
 }
 
 #endif