AILang/docs/journals/2026-05-12-iter-hs.1.md

iter hs.1 — Heap-Str ABI: Static-Str layout migration

Date: 2026-05-12 Started from: 69bb5f9952 Status: DONE Tasks completed: 5 of 5

Summary

First iter of the heap-Str ABI milestone. Pure codegen-side refactor: language Str literals now emit as packed-struct LLVM globals <{ i64, i64, [N+1 x i8] }> <{ i64 -1, i64 N, [N+1 x i8] c"...\00" }> carrying a UINT64_MAX sentinel rc-header in the first slot, an explicit byte length in the second, and the bytes plus trailing NUL in the array tail. The IR-Str-pointer convention is now uniform: a language Str value flowing through the IR is a ptr landing on the len-field (offset +8 from the header, -8 from the bytes). Every codegen site that hands a Str pointer to a NUL-terminated-bytes C-API consumer emits a getelementptr inbounds i8, ptr <v>, i64 8 immediately before the call. The sentinel slot is hardcoded in the global initialiser and not yet observed by any caller — hs.2 will add the UINT64_MAX short-circuit to ailang_rc_inc / ailang_rc_dec in runtime/rc.c to exploit it. Format strings (%lld\n, %g\n, true\n, false\n) are unchanged — they are runtime-internal scaffolding, never flow as language Str values, and remain in the raw [N x i8] shape via the original intern_string / all_strings path. Acceptance verified end-to-end: full cargo test --workspace green (no regressions across 74 e2e fixtures), bench/compile_check.py exit 0, bench/cross_lang.py exit 0 (byte-identical stdout across all ail/c benchmark pairs).

Per-task notes

• iter hs.1.1: introduced parallel str_literals interning table on Emitter, intern_str_literal fn, workspace-level all_str_literals aggregation, and a parallel global-emission loop emitting the packed-struct shape. Switched both Literal::Str arms (emit_const_def, lower_term) to call intern_str_literal and materialise a constexpr getelementptr inbounds (<{ i64, i64, [N x i8] }>, ptr @g, i32 0, i32 1) landing on the len-field. Two pinning tests added.
• iter hs.1.2: io/print_str arm now emits a +8 GEP to land on the bytes pointer before calling @puts. One pinning test added.
• iter hs.1.3: eq__Str arm of try_emit_primitive_instance_body now emits +8 GEPs on both operands before calling @ail_str_eq. One pinning test added.
• iter hs.1.4: compare__Str arm of try_emit_primitive_instance_body now emits +8 GEPs on both operands before calling @ail_str_compare. One pinning test added.
• iter hs.1.5: regenerated crates/ail/tests/snapshots/hello.ll via UPDATE_SNAPSHOTS=1. Full cargo test --workspace revealed a regression in eq_demo traced to a fourth codegen site not enumerated in the plan: lower_eq's "Str" arm calls @strcmp inline (separate from the eq__Str instance-method intercept) to lower == on Str literals and Str-pattern desugaring in classify_str. Fixed inline with the same +8 GEP shape; one additional pinning test added.

Concerns

• The plan claimed three codegen sites pass a Str pointer to a NUL-terminated-bytes C-API consumer (@puts, @ail_str_eq, @ail_str_compare); in fact a fourth site exists in lower_eq's "Str" arm, calling @strcmp directly. This is the dispatch path for the surface-level == operator on Str and for (pat-lit "...") desugar against a Str scrutinee. The fourth site is required to meet the iter's stated acceptance criterion (byte-identical stdout); fixing it was discovered via the e2e regression in eq_demo rather than via the per-task IR-shape checks. The fix has the same shape as Tasks 2-4 and the corresponding pinning test (lower_eq_str_calls_strcmp_with_bytes_pointer) is added. The plan's "Files this plan creates or modifies" enumeration should list crates/ailang-codegen/src/lib.rs:2520-2529 as a fifth modify site for any future re-execution.
• The plan's two test fixtures in Task 1 contained schema-syntax errors that prevented compilation: ConstDef.body (actual: value), Term::App { f, args } (actual: callee, args, tail), and Term::App { Term::Var "io/print_str", ... } for what is actually a Term::Do effect op. Tests were adapted to compile while preserving the substantive assertions verbatim. Same applies to the test in Task 2 (Term::App → Term::Do for the io/print_str invocation and added effects: ["IO"] on the main fn so the typecheck-side dispatch finds the effect). These were small per-test fixture adaptations, not changes to the asserted IR shape.

Known debt

• The sentinel value -1 (UINT64_MAX) is hardcoded in the global initialiser. hs.2 adds the matching short-circuit check in ailang_rc_inc / ailang_rc_dec so static-Str pointers can flow through generic RC paths without ref-count traffic. Until hs.2 lands, no caller actually observes the sentinel — static Str slabs are still invisible to the RC runtime by construction (the call sites for inc / dec against Str values are still gated by the same uniqueness-inference pass that elided them pre-iter).

Files touched

• crates/ailang-codegen/src/lib.rs — Emitter field, intern fn, workspace aggregation, global emission, two Literal::Str arm switches, four C-API-callsite +8 GEP adjustments (io/print_str, eq__Str, compare__Str, lower_eq Str arm), six new IR-shape pinning tests in the test module.
• crates/ail/tests/snapshots/hello.ll — regenerated snapshot showing the new packed-struct global and the +8 GEP before @puts. No other snapshot under crates/ail/tests/snapshots/ changed (other snapshots contain only format-string globals which kept the raw [N x i8] shape).

Stats

bench/orchestrator-stats/2026-05-12-iter-hs.1.json