CG type/debug split: move source spelling off the operational type id

Goal. Make KitCgTypeId a storage/ABI/operational identity only, and carry source-facing spelling (primitive sign+name, typedef names, enum underlying spelling) on a separate, optional debug channel consumed at the points where debug info is actually produced. The result removes pervasive alias-resolution from the CG hot path: with no transparent wrapper kinds left in the operational lattice, api_unalias_type, the storage_id-vs-id split, and the per-backend if (ALIAS) recurse; if (SOURCE_BASE) recurse boilerplate all disappear.

This resolves CG-TYPES.md §10 Open Question 1 ("Should KIT_CG_TYPE_ALIAS remain a true public kind, or should source aliases move entirely into debug/C-backend metadata?") — extended to cover KIT_CG_TYPE_SOURCE_BASE, which was added after that question was written.

This is a clean-break redesign, no backcompat, in the spirit of CG-TYPES.md. The capability that KIT_CG_TYPE_SOURCE_BASE delivers (faithful signed/unsigned/ char debug, plus enum enumerators) is preserved — only its placement moves.

---

1. Current State

The public type lattice (include/kit/cg.h, src/cg/type.c) contains two transparent wrapper kinds whose only purpose is debug-info spelling:

• KIT_CG_TYPE_ALIAS — a named typedef over a base type (kit_cg_type_alias). Dead for every real frontend: the only callers are test/api/cg_type_test.c. The C frontend never creates aliases (so C typedef names are already absent from DWARF today).
• KIT_CG_TYPE_SOURCE_BASE — a source-facing scalar spelling (name + KitCgDebugEncoding) over a width-only storage builtin (kit_cg_type_source_base, added by commit 244f1039). The C frontend lowers every integer/char scalar to one of these (lang/c/type/type.c, type_cg_scalar), so in practice almost every integer id flowing through CG is a wrapper.

Both kinds are transparent to storage: every ABI/codegen/predicate site strips them to the terminal builtin via api_unalias_type before use.

What the wrappers buy us (measured)

• The only consumer of the exact wrapper kind is debug info: api_debug_type (src/cg/debug.c) maps ALIAS → DW_TAG_typedef and SOURCE_BASE → DW_TAG_base_type + DW_ATE_*. Reached at three live sites — the subprogram type at kit_cg_func_begin_attrs and locals/params in api_debug_emit_source_locals (src/cg/session.c).
• src/opt/ has zero references to either kind. The optimizer only ever sees unaliased storage types.
• Nothing in ABI/calling-convention/operation lowering reads the wrapper: signedness of operations comes from op selection (SDIV/UDIV, sext/zext) and from KIT_CG_ABI_SIGNEXT/ZEROEXT attrs; load signedness comes from the KIT_CG_MEM_SOURCE_SIGNED flag. The encoding on a source-base is a debug vehicle, never consulted for codegen.
• Struct/union member types do not reach DWARF at all today: api_debug_type's record case calls debug_type_record_begin then immediately debug_type_record_end, never debug_type_record_field. So source-base spelling on field types — and on interned func-sig param types — is consumed by nothing.
• Enums do now thread enumerators (commit 244f1039): api_debug_type emits DW_TAG_enumeration_type with DW_TAG_enumerator children over the enum's underlying type. The underlying type may itself be a source-base.

What it costs

• api_unalias_type is called pervasively: ~33 per-op hot-path sites (src/cg/value.c, arith.c, call.c, memory.c), ~9 more inside type.c itself (the float/i128 predicates, predicate-bits fill, complete/sized/valid, enum-base validation, same_storage), plus the recursive alias-stripping prologue duplicated across every ABI backend (src/abi/abi.c, abi_rv64.c, abi_sysv_x64.c, abi_aapcs64.c, abi_win64_x64.c, src/arch/wasm/abi.c) and ~10 functions in type.c/fold.c (cg_type_pointee, cg_type_func_ret_id, kit_cg_type_int_width/float_width, api_int_like_width, api_type_is_bool, cg_type_complete_id, cg_type_sized_id, cg_type_same_storage_rec).
• A per-type-entry caching subsystem that exists largely to amortize the above: storage_id (the unalias terminal, filled once by api_type_info_fill), pred_bits/pred_valid (predicate bitset computed on the unaliased type).
• A two-headed type-info surface (kit_cg_type_view identity prefix vs kit_cg_type_info full snapshot) plus storage_id, kit_cg_type_resolve_alias, and kit_cg_type_same_storage, all there to manage the alias↔storage split. kit_cg_type_is_void is a two-hop through storage_id.

Recent movement (reconciled)

Three same-day changes touched this area and the plan is written against the current working tree:

• 64afd07c (clean cutover) — direct-index ids; void is always the void builtin; KIT_CG_TYPE_NONE is invalid/absent only.
• 244f1039 — added SOURCE_BASE and threaded enum enumerators into debug info. This plan reverses the placement of that spelling (onto a debug channel) without dropping the capability.
• Uncommitted working tree — consolidated the unalias caching: deleted the redundant CgApiTypeKind/CgApiType.kind (entry kind is now e->cg.kind), folded the old unaliased/unalias_filled fields into a single info.storage_id filled by api_type_info_fill, and made kit_cg_type_info delegate to kit_cg_type_view. This cleaned up the cost but did not remove the unaliasing — the pervasiveness above is fully intact, and storage_id is now load-bearing.

This consolidation is evidence for the split, and makes it cleaner to land: the unalias walk is now concentrated in one place (api_type_info_fill) instead of two.

---

2. Problems

2.1 One id, two roles

KitCgTypeId is overloaded to be both the storage/ABI/operational identity (what every op needs; width-only for integers) and the source spelling for debug (name

• signedness). To make one id serve both, transparent wrappers carry role-2 data but must be seen through for every role-1 use. That see-through is the pervasive api_unalias_type.

2.2 Distinct spellings force distinct operational ids

Two C types (int, unsigned int) share storage i32, so a spelling cannot hang off the shared storage id — each spelling needs its own id. As long as those ids are operational and handed to ops, ops must map them back to storage. The only way to remove unaliasing is for ops to receive storage ids and for spelling to travel separately.

2.3 The payoff is tiny and shrinking

The exact wrapper kind is consumed at three debug sites; ALIAS is dead; struct members (the bulk of would-be spelled types) are not emitted at all. The cost — pervasive unalias + a caching subsystem + per-backend boilerplate + a split type API — is paid everywhere to feed a narrow, cold consumer.

---

3. Design Decisions

#	Decision	Choice
E1	Operational lattice	KitCgTypeId kinds shrink to VOID, BOOL, INT(width), FLOAT(width), PTR, ARRAY, FUNC, RECORD, ENUM, VARARG_STATE. No ALIAS, no SOURCE_BASE.
E2	Storage identity	storage_id == id for every operational type. api_unalias_type is deleted; kit_cg_type_resolve_alias becomes identity; kit_cg_type_is_void is a single kind check.
E3	Debug spelling home	A separate, optional KitCgDebugType handle, built only when debug info is requested, consumed only at debug emission.
E4	Debug graph reuse	KitCgDebugType references operational ids for structural/nominal pieces (records, enums, funcs) via kit_cg_debug_of_type; the frontend overrides only leaves (primitive spellings) and inserts typedefs. No duplication of record/enum/func debug emission.
E5	Attachment	Decl-bearing APIs gain an optional KitCgDebugType field; 0 (NONE) means "derive the default from the operational type" — preserving today's behavior for frontends that do not set it.
E6	Interning purity	Debug types never enter interned operational descriptors (KitCgFuncSig/KitCgFuncParam), so spelling never splits structural interning.
E7	Capability preservation	Faithful signed/unsigned/char debug and enum enumerators (from 244f1039) are preserved via the debug channel; DWARF output is byte-identical.
E8	Non-C frontends	Toy and Wasm pass 0 and rely on the existing default derivation (which they already use today — void/bool/float are never wrapped). No change required.

---

4. New Public Shape

4.1 Debug-type handle and builders

Thin public wrappers over the existing src/debug/ DebugType producer (which already has base/typedef/ptr/array/record/enum/func builders). Available only on a KitCg with debug enabled; no-ops returning NONE otherwise.

typedef uint32_t KitCgDebugType;          /* 0 = derive from the operational type */
#define KIT_CG_DEBUG_TYPE_NONE 0u

/* A named primitive leaf (DW_TAG_base_type): "int"/signed/4, etc. */
KIT_API KitCgDebugType kit_cg_debug_base(KitCg*, KitSym name,
                                         KitCgDebugEncoding, uint32_t bytes);
/* A named typedef (DW_TAG_typedef) over another debug type. */
KIT_API KitCgDebugType kit_cg_debug_typedef(KitCg*, KitSym name, KitCgDebugType);
/* Structural debug types mirroring operational composition. */
KIT_API KitCgDebugType kit_cg_debug_ptr(KitCg*, KitCgDebugType pointee);
KIT_API KitCgDebugType kit_cg_debug_array(KitCg*, KitCgDebugType elem,
                                          uint64_t count);
/* Derive a debug type from an operational type: records/enums/funcs (with their
 * existing emission) and default-named scalars. The leaf-override + typedef
 * builders above are layered on top of this. */
KIT_API KitCgDebugType kit_cg_debug_of_type(KitCg*, KitCgTypeId);

Composition examples (frontend side):

• int* → debug_ptr(debug_base("int", SIGNED, 4))
• unsigned → debug_base("unsigned int", UNSIGNED, 4)
• struct S* → debug_ptr(debug_of_type(S))
• double → debug_of_type(f64) (default name is correct)
• typedef T int; T x; → debug_typedef("T", debug_base("int", SIGNED, 4)) (this gains typedef DIEs, which the current design silently drops)

KitCgDebugEncoding is unchanged — it is already the clean debug-only enum; it moves from kit_cg_type_source_base to kit_cg_debug_base.

4.2 Attachment points

Debug-only fields; 0 ⇒ derive default from the operational type.

typedef struct KitCgLocalAttrs {
  KitSym name;
  uint32_t align;
  uint32_t flags;
  KitCgDebugType debug_type;   /* NEW: 0 = derive from the local's type */
} KitCgLocalAttrs;             /* covers both kit_cg_local and kit_cg_param */

typedef struct KitCgFuncAttrs {
  /* ... existing ... */
  KitCgDebugType debug_type;   /* NEW: the subprogram's type DIE; 0 = derive */
} KitCgFuncAttrs;              /* NOT in the interned KitCgFuncSig (E6) */

typedef struct KitCgObjectAttrs {
  /* ... existing ... */
  KitCgDebugType debug_type;   /* NEW: global object's type DIE; 0 = derive */
} KitCgObjectAttrs;

api_debug_type(KitCgTypeId) becomes a resolver over KitCgDebugType: when a decl site supplies a debug type, emit that; when it supplies NONE, fall back to the operational-type walk that exists today. Record member types (when DWARF members are eventually emitted) will carry KitCgDebugType on KitCgField at that time; nothing depends on it now.

4.3 Operational API simplifications

• Delete kit_cg_type_alias, kit_cg_type_source_base, and their accessors (kit_cg_type_alias_name/base, kit_cg_type_source_base_name/storage/encoding).
• Delete KIT_CG_TYPE_ALIAS, KIT_CG_TYPE_SOURCE_BASE from KitCgTypeKind.
• kit_cg_type_resolve_alias returns its argument (identity). Keep as a trivial documented accessor or remove; kit_cg_type_same_storage reduces to structural storage comparison with no alias step.
• KitCgTypeInfo.storage_id always equals id. Decision point (Open Q1): keep the field as a documented == id identity (zero churn to the struct/ABI) or remove it.

---

5. Internal Architecture

5.1 Type table

CgApiType loses the wrapper-specific state once the kinds are gone:

• api_type_info_fill (src/cg/type.c) drops its while (ALIAS||SOURCE_BASE) walk; info.storage_id = id.
• api_unalias_type is deleted. Its ~33 hot-path callers and ~9 in-type.c callers use the id directly.
• pred_bits/pred_valid no longer need an unalias step — the kind is now exact, so cg_type_is_int/_float/_ptr/etc. read the kind directly. The bitset cache can be kept (one indexed load) or dropped (kind lookup is already one load); prefer dropping it to shed state unless a measurement says keep.
• The ALIAS/SOURCE_BASE recursion deletes from cg_type_pointee, cg_type_func_ret_id/_result_id/_param_id, kit_cg_type_int_width, kit_cg_type_float_width, api_int_like_width, api_type_is_bool, cg_type_complete_id, cg_type_sized_id, cg_type_same_storage_rec.

5.2 ABI layer

The if (t->kind == KIT_CG_TYPE_ALIAS) recurse; if (... SOURCE_BASE) recurse prologue deletes from abi_cg_type_info (src/abi/abi.c) and from every per-arch classifier (abi_rv64.c, abi_sysv_x64.c, abi_aapcs64.c, abi_win64_x64.c, src/arch/wasm/abi.c). ABI queries see only real storage kinds.

5.3 Debug producer

src/debug/ is untouched. src/cg/debug.c changes from "walk the operational CgType and special-case ALIAS/SOURCE_BASE" to "walk a KitCgDebugType graph; for an operational-type reference, dispatch into the existing record/enum/func/ptr/array emission." Enum enumerators stay on the operational enum entry (nothing unaliases an enum, so they cost no pervasiveness); only the enum's underlying spelling comes from the debug channel.

---

6. Frontend Impact

6.1 C frontend (the only affected frontend)

• type_cg_scalar (lang/c/type/type.c) stops wrapping in source-base; returns the bare builtin. t->cg_id becomes a pure storage id, used unchanged at all operational sites (memaccess, convert, params, locals, fields, calls).
• Add a parallel lazy type_cg_debug(Type*) → KitCgDebugType, cached as t->dbg_id, structurally identical to type_cg_lower. The existing 13-entry kScalarDbg table now drives kit_cg_debug_base instead of kit_cg_type_source_base. The two lowerings can share one traversal (they recurse in lockstep) if that is cleaner.
• At decl sites — kit_cg_local, kit_cg_param, kit_cg_func_begin_attrs, global object definition — set attrs.debug_type = type_cg_debug(t).
• Enum lowering keeps passing enumerators to kit_cg_type_enum (operational); the enum's debug underlying spelling rides on type_cg_debug.

6.2 Toy / Wasm

No change. They pass 0 for debug_type and get today's default derivation.

---

7. Implementation Plan

Phase 1: Add the debug channel, migrate C behind it

• Add KitCgDebugType, the builders, and the decl-attr fields.
• Make api_debug_type a resolver: supplied KitCgDebugType wins; NONE derives the default from the operational type (today's behavior).
• Add type_cg_debug to the C frontend; set debug_type at decl sites.
• SOURCE_BASE/ALIAS still exist at this point; the goal is for debug to stop reading them. Verify DWARF byte-identity (make test-debug test-dwarf, kit cc -g spot checks for DW_ATE_unsigned/signed_char/unsigned_char and enumerator DIEs).

Phase 2: Delete the wrappers and all unaliasing

Once debug no longer reads the wrappers, cut over in one clean break:

• Stop the C frontend creating source-base ids (type_cg_scalar returns the builtin).
• Delete kit_cg_type_alias/source_base + accessors, the two KitCgTypeKind values, api_unalias_type, and the recursion/prologues listed in §5.
• Collapse storage_id to id (or remove the field — Open Q1).
• Simplify kit_cg_type_resolve_alias/is_void/same_storage.

Phase 3: Tests

• Rewrite test/api/cg_type_test.c alias/source-base cases as KitCgDebugType builder + emission tests.
• Add a debug-channel test: a local of unsigned, a signed char, an enum, and a typedef each produce the expected DWARF DIE.

---

8. Validation

• make test-debug test-dwarf — primary gate; DWARF must be byte-identical for the signed/unsigned/char/enum cases 244f1039 introduced.
• make test-cg-api — type API contract.
• make test-parse test-toy test-opt — frontend + mid-end unaffected.
• make test-smoke-x64 test-smoke-rv64 — end-to-end with -g.
• Ecosystem / byte-identity gate (see PERF.md and the ecosystem harness): object output must be unchanged; DWARF must match.

Scenario coverage: int/unsigned/char/signed char/unsigned char locals and params; enums with enumerators; typedef DIEs (new, previously dropped); function pointers; records (members still opaque — confirm no regression); va_list; non-C frontends emit unchanged debug via the default path.

---

9. Acceptance Criteria

• KitCgTypeKind has no ALIAS/SOURCE_BASE; KitCgTypeId is storage/ABI only.
• api_unalias_type and the per-backend alias/source-base prologues are gone.
• storage_id == id everywhere (field kept as identity or removed).
• No CG hot-path op resolves aliases; predicates read the exact kind.
• DWARF output for the 244f1039 capabilities is byte-identical; typedef DIEs are additionally available.
• Toy and Wasm are unchanged.
• No global state, no VLAs; debug-type state hangs off KitCg.

---

10. Open Questions

1. Keep or remove KitCgTypeInfo.storage_id? It becomes vestigial (== id). Keeping it as a documented identity is zero-churn and leaves kit_cg_type_resolve_alias meaningful as a trivial accessor; removing it is cleaner but touches the public struct and every reader. Prefer remove for a true clean break, consistent with CG-TYPES.md's no-backcompat stance.
2. Should enum enumerators also move to the debug channel? They are debug-only in principle, but they already live on the operational enum entry and cost no pervasiveness (nothing unaliases an enum). Prefer leave on the operational enum to minimize churn; revisit only if member-type debug work wants a uniform debug-graph representation.
3. kit_cg_debug_of_type vs a fully parallel debug graph. The plan leans on of_type to reuse existing record/enum/func emission. If a future need arises to spell those differently from their operational shape (rare), the builder set would grow kit_cg_debug_struct/union/enum/func. Prefer the minimal of_type-based set until such a need is concrete.