diff --git a/docs/plans/hs.1.md b/docs/plans/hs.1.md new file mode 100644 index 0000000..21df1bf --- /dev/null +++ b/docs/plans/hs.1.md @@ -0,0 +1,790 @@ +# hs.1 — Heap-Str ABI: Static-Str Layout Migration — Implementation Plan + +> **Parent spec:** `docs/specs/2026-05-12-heap-str-abi.md` +> +> **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement` +> to run this plan. Steps use `- [ ]` checkboxes for tracking. + +**Goal:** Migrate static-Str LLVM globals from the current raw +`[N+1 x i8]` byte-array shape to the unified packed-struct shape +`<{ i64, i64, [N+1 x i8] }>` carrying a `UINT64_MAX` sentinel +rc-header, an explicit `len` field, and the bytes + terminating +`NUL`. Switch the two `Literal::Str` codegen sites to materialise +an IR-Str pointer that lands on the `len`-field of the new global +(via constexpr `getelementptr`). Adjust the three codegen sites +that pass a Str pointer to a `NUL`-terminated-bytes C-API consumer +(`@puts`, `@ail_str_eq`, `@ail_str_compare`) to emit a `+8` +`getelementptr` immediately before the call to land on the bytes. +After this iter, the IR-Str-pointer convention is "the value +flowing through the IR as a `Str` points at the `len`-field of +the global"; every existing program produces byte-identical +stdout. + +**Architecture:** Pure codegen-side refactor. No runtime changes, +no checker changes, no new builtins. The new global layout has the +sentinel-header slot that the next iter (`hs.2`) will exploit by +adding the `UINT64_MAX` short-circuit to `ailang_rc_inc` / +`ailang_rc_dec` in `runtime/rc.c`; in this iter the sentinel value +is hardcoded in the global initialiser and never observed by any +caller. The `+8` adjustments at C-API sites mean `@puts`, +`@ail_str_eq`, `@ail_str_compare` continue to receive a +`NUL`-terminated bytes pointer — they expect raw `char*`, unchanged +from today, only the offset machinery in the caller shifts. Format +strings (`%lld\n`, `%g\n`, `true\n`, `false\n`) keep the old raw +`[N x i8]` shape — they are runtime-internal scaffolding, never +flow as language `Str` values, and never reach the new ABI. + +**Tech Stack:** Rust crate `ailang-codegen` (`crates/ailang-codegen/src/lib.rs`, +test module in the same file). Snapshot fixture in `crates/ail/tests/snapshots/hello.ll`. + +--- + +## Files this plan creates or modifies + +- **Modify:** `crates/ailang-codegen/src/lib.rs:534` — add a parallel + field `str_literals: BTreeMap` on the + `Emitter` struct next to the existing `strings` field. Same key + shape; the two tables coexist. +- **Modify:** `crates/ailang-codegen/src/lib.rs:753` — initialise + `str_literals: BTreeMap::new()` in the same constructor block + that initialises `strings`. +- **Modify:** `crates/ailang-codegen/src/lib.rs:2487-2498` — add a + new function `intern_str_literal` next to the existing + `intern_string`. Same dedup-by-content semantics but writes into + `self.str_literals` and reuses `self.str_counter` for monotonic + naming so the produced global names remain alphabetically + orderable alongside format-string globals. +- **Modify:** `crates/ailang-codegen/src/lib.rs:283-411` — add a + second aggregation `all_str_literals: BTreeMap>` alongside the existing `all_strings`, + populated from `emitter.str_literals` symmetrically to the + existing populate-from-`emitter.strings` block at line 403-410. +- **Modify:** `crates/ailang-codegen/src/lib.rs:438-450` — add a + parallel emission loop after the existing one. The new loop + emits each entry as + `@ = private unnamed_addr constant <{ i64, i64, [N+1 x i8] }> <{ i64 -1, i64 N, [N+1 x i8] c"\00" }>, align 8` + where `N = c_byte_len(content)` (the bytes, excluding the + trailing `NUL`) and the `[N+1]` includes the `NUL`. +- **Modify:** `crates/ailang-codegen/src/lib.rs:890-893` — switch + the `Literal::Str` arm inside `emit_const_def`'s match block to + call `intern_str_literal` and return the constexpr-GEP form + instead of the bare `@{g}` name. +- **Modify:** `crates/ailang-codegen/src/lib.rs:1202-1207` — switch + the `Literal::Str` arm inside `lower_term`'s match block + symmetrically. +- **Modify:** `crates/ailang-codegen/src/lib.rs:2152-2170` — at + `io/print_str`, emit a `getelementptr i8, ptr , i64 8` to land + on the bytes pointer immediately before the `@puts` call. +- **Modify:** `crates/ailang-codegen/src/lib.rs:2256-2268` — at + `eq__Str` intercept, emit `+8` GEPs on both `a_ssa` and `b_ssa` + before the `@ail_str_eq` call. +- **Modify:** `crates/ailang-codegen/src/lib.rs:2302-2321` — at + `compare__Str` intercept, emit `+8` GEPs on both `a_ssa` and + `b_ssa` before the `@ail_str_compare` call. +- **Modify:** `crates/ail/tests/snapshots/hello.ll` — regenerate + via `UPDATE_SNAPSHOTS=1 cargo test --workspace ir_snapshot_hello` + after Task 4 lands; the `@.str_hello_str_0` global and the + `@puts` callsite both change shape. +- **Test:** `crates/ailang-codegen/src/lib.rs` (test module starting + around `:3340`) — five new IR-shape tests pinning the new + conventions: + - `static_str_global_uses_packed_struct_with_sentinel_and_len` + - `static_str_callsite_pointer_is_payload_via_constexpr_gep` + - `print_str_calls_puts_with_bytes_pointer` + - `eq_str_calls_ail_str_eq_with_bytes_pointer` + - `compare_str_calls_ail_str_compare_with_bytes_pointer` + +--- + +## Task 1: Migrate Str-literal globals to packed-struct layout + +This task introduces the new emission machinery AND switches the +two language-`Str` codegen sites to use it. The two changes are +inseparable — `intern_str_literal` produces no observable output +without the callsite switch, and the callsite switch references a +function that doesn't exist without the new infrastructure. + +**Files:** +- Modify: `crates/ailang-codegen/src/lib.rs:534, 753, 283-411, 438-450, 890-893, 1202-1207, 2487-2498` +- Test: `crates/ailang-codegen/src/lib.rs` (test module) + +- [ ] **Step 1: Write the failing test `static_str_global_uses_packed_struct_with_sentinel_and_len`.** + +Add this test to the `tests` module at the bottom of +`crates/ailang-codegen/src/lib.rs`, near the existing +`eq_str_mono_symbol_emits_ail_str_eq_call` test: + +```rust +/// Iter hs.1: language `Str` literals emit as packed-struct +/// globals carrying a `UINT64_MAX` sentinel rc-header, an +/// explicit `len` field, and the bytes + trailing NUL. This +/// test pins the layout shape against a tiny single-Literal::Str +/// fixture. +#[test] +fn static_str_global_uses_packed_struct_with_sentinel_and_len() { + let m = Module { + schema: SCHEMA.into(), + name: "t".into(), + imports: vec![], + defs: vec![ + Def::Const(ConstDef { + name: "greeting".into(), + ty: Type::str_(), + body: Term::Lit { lit: Literal::Str { value: "hello".into() } }, + doc: None, + }), + Def::Fn(FnDef { + name: "main".into(), + ty: Type::Fn { + params: vec![], + ret: Box::new(Type::unit()), + effects: vec![], + param_modes: vec![], + ret_mode: ParamMode::Implicit, + }, + params: vec![], + body: Term::Lit { lit: Literal::Unit }, + suppress: vec![], + doc: None, + }), + ], + }; + let ir = emit_ir(&m).unwrap(); + assert!( + ir.contains(r#"<{ i64, i64, [6 x i8] }> <{ i64 -1, i64 5, [6 x i8] c"hello\00" }>"#), + "expected packed-struct global with sentinel + len + bytes + NUL; ir was:\n{ir}" + ); +} +``` + +- [ ] **Step 2: Run test to verify it fails.** + +Run: `cargo test --workspace -p ailang-codegen static_str_global_uses_packed_struct_with_sentinel_and_len` +Expected: FAIL — the IR currently emits `[6 x i8] c"hello\00"`, not the packed-struct form. + +- [ ] **Step 3: Add the `str_literals` field to `Emitter`.** + +Modify `crates/ailang-codegen/src/lib.rs:534` to add the field next +to `strings`: + +```rust +strings: BTreeMap, +str_literals: BTreeMap, +``` + +And initialise in the constructor at `:753`: + +```rust +strings: BTreeMap::new(), +str_literals: BTreeMap::new(), +``` + +- [ ] **Step 4: Add the `intern_str_literal` function.** + +Modify `crates/ailang-codegen/src/lib.rs:2487-2498` to add a +parallel function next to `intern_string`: + +```rust +fn intern_str_literal(&mut self, hint: &str, content: &str) -> String { + if let Some((name, _)) = self.str_literals.get(content) { + return name.clone(); + } + // Mangling per module: `.str___`. Shares + // the same monotonic `str_counter` with `intern_string` so + // global names are stable-ordered across runs. + let name = format!(".str_{}_{}_{}", self.module_name, hint, self.str_counter); + self.str_counter += 1; + let len = c_byte_len(content); + self.str_literals + .insert(content.to_string(), (name.clone(), len)); + name +} +``` + +- [ ] **Step 5: Add aggregation of `str_literals` in `lower_workspace`.** + +Modify the workspace-aggregation block at `crates/ailang-codegen/src/lib.rs:283-411`. + +Add a parallel `all_str_literals` declaration next to +`all_strings` at line 283: + +```rust +let mut all_str_literals: BTreeMap> = BTreeMap::new(); +``` + +And add a parallel population block immediately after the +existing `all_strings.insert(...)` at line 410: + +```rust +let mut lit_entries: Vec<(String, String)> = Vec::new(); +for (content, (name, _)) in &emitter.str_literals { + lit_entries.push((name.clone(), content.clone())); +} +lit_entries.sort_by(|a, b| a.0.cmp(&b.0)); +all_str_literals.insert(mname.clone(), lit_entries); +``` + +- [ ] **Step 6: Emit the packed-struct globals.** + +Modify the global-emission loop at +`crates/ailang-codegen/src/lib.rs:438-450`. Immediately after +the existing `for entries in all_strings.values() { ... }` block, +add the parallel emission for `all_str_literals`: + +`c_byte_len(content)` (defined at +`crates/ailang-codegen/src/synth.rs:260` as `s.len() + 1`) returns +the byte length INCLUDING the trailing NUL. The array dim is +`[c_byte_len(content) x i8]`; the i64 `len`-field stores +`c_byte_len(content) - 1` (bytes excluding NUL). + +```rust +for entries in all_str_literals.values() { + for (name, content) in entries { + let escaped = ll_string_literal(content); + let total = c_byte_len(content); // bytes + NUL + let bytes_len = total - 1; // bytes only + out.push_str(&format!( + "@{name} = private unnamed_addr constant <{{ i64, i64, [{total} x i8] }}> <{{ i64 -1, i64 {bytes_len}, [{total} x i8] c\"{escaped}\" }}>, align 8\n", + )); + emitted_global = true; + } +} +``` + +- [ ] **Step 7: Switch the two `Literal::Str` arms to `intern_str_literal`.** + +Modify `crates/ailang-codegen/src/lib.rs:890-893` from: + +```rust +Literal::Str { value } => { + let g = self.intern_string("str", value); + ("ptr".to_string(), format!("@{g}")) +} +``` + +to: + +```rust +Literal::Str { value } => { + let g = self.intern_str_literal("str", value); + let total = c_byte_len(value); // bytes + NUL + ( + "ptr".to_string(), + format!( + "getelementptr inbounds (<{{ i64, i64, [{total} x i8] }}>, ptr @{g}, i32 0, i32 1)", + ), + ) +} +``` + +And symmetrically at `crates/ailang-codegen/src/lib.rs:1202-1207`: + +```rust +Literal::Str { value } => { + let g = self.intern_str_literal("str", value); + let total = c_byte_len(value); // bytes + NUL + ( + format!( + "getelementptr inbounds (<{{ i64, i64, [{total} x i8] }}>, ptr @{g}, i32 0, i32 1)", + ), + "ptr".into(), + ) +} +``` + +- [ ] **Step 8: Run the test to verify it passes.** + +Run: `cargo test --workspace -p ailang-codegen static_str_global_uses_packed_struct_with_sentinel_and_len` +Expected: PASS. + +- [ ] **Step 9: Add the constexpr-GEP shape test.** + +Append to the same test module: + +```rust +/// Iter hs.1: a `Literal::Str` at a callsite materialises a +/// constexpr `getelementptr` landing on the `len`-field of the +/// packed-struct global, not the bare global name. This pins the +/// IR-Str-pointer convention used uniformly by all consumers. +#[test] +fn static_str_callsite_pointer_is_payload_via_constexpr_gep() { + let m = Module { + schema: SCHEMA.into(), + name: "t".into(), + imports: vec![], + defs: vec![Def::Fn(FnDef { + name: "main".into(), + ty: Type::Fn { + params: vec![], + ret: Box::new(Type::unit()), + effects: vec![], + param_modes: vec![], + ret_mode: ParamMode::Implicit, + }, + params: vec![], + body: Term::App { + f: Box::new(Term::Var { name: "io/print_str".into() }), + args: vec![Term::Lit { lit: Literal::Str { value: "hi".into() } }], + }, + suppress: vec![], + doc: None, + })], + }; + let ir = emit_ir(&m).unwrap(); + assert!( + ir.contains(r#"getelementptr inbounds (<{ i64, i64, [3 x i8] }>, ptr @.str_t_str_0, i32 0, i32 1)"#), + "expected constexpr-GEP-to-len-field at callsite; ir was:\n{ir}" + ); +} +``` + +- [ ] **Step 10: Run test to verify it passes.** + +Run: `cargo test --workspace -p ailang-codegen static_str_callsite_pointer_is_payload_via_constexpr_gep` +Expected: PASS. + +--- + +## Task 2: `+8` GEP at `io/print_str` callsite + +Between Task 1 completing and Task 2 completing, programs that +print a Str literal would pass the IR-Str pointer (now at +`len`-field) directly to `@puts`, which would print 8 bytes of +length-field junk before the actual bytes. This task makes the +print path consume the bytes pointer correctly. + +**Files:** +- Modify: `crates/ailang-codegen/src/lib.rs:2152-2170` +- Test: `crates/ailang-codegen/src/lib.rs` (test module) + +- [ ] **Step 1: Write the failing test `print_str_calls_puts_with_bytes_pointer`.** + +```rust +/// Iter hs.1: after the layout migration, the `io/print_str` +/// path must `getelementptr i8` +8 onto the IR-Str pointer before +/// passing it to `@puts`, so `@puts` receives the bytes pointer +/// (skipping the `len` field) and produces correct output. +#[test] +fn print_str_calls_puts_with_bytes_pointer() { + let m = Module { + schema: SCHEMA.into(), + name: "t".into(), + imports: vec![], + defs: vec![Def::Fn(FnDef { + name: "main".into(), + ty: Type::Fn { + params: vec![], + ret: Box::new(Type::unit()), + effects: vec![], + param_modes: vec![], + ret_mode: ParamMode::Implicit, + }, + params: vec![], + body: Term::App { + f: Box::new(Term::Var { name: "io/print_str".into() }), + args: vec![Term::Lit { lit: Literal::Str { value: "hi".into() } }], + }, + suppress: vec![], + doc: None, + })], + }; + let ir = emit_ir(&m).unwrap(); + // Expect a +8 GEP immediately preceding the @puts call. + let body_idx = ir.find("define i8 @ail_t_main").expect("main body"); + let body = &ir[body_idx..]; + let puts_idx = body.find("@puts(").expect("@puts call present"); + let before_puts = &body[..puts_idx]; + assert!( + before_puts.contains("getelementptr inbounds i8, ptr ") && before_puts.contains(", i64 8"), + "expected `getelementptr inbounds i8, ptr , i64 8` before @puts call; ir body was:\n{body}" + ); +} +``` + +- [ ] **Step 2: Run test to verify it fails.** + +Run: `cargo test --workspace -p ailang-codegen print_str_calls_puts_with_bytes_pointer` +Expected: FAIL — no GEP precedes `@puts` today; the IR-Str pointer +is passed directly. + +- [ ] **Step 3: Add the `+8` GEP at the `io/print_str` callsite.** + +Modify `crates/ailang-codegen/src/lib.rs:2152-2170` from: + +```rust +"io/print_str" => { + if args.len() != 1 { + return Err(CodegenError::Internal( + "io/print_str arity".into(), + )); + } + let (v, vty) = self.lower_term(&args[0])?; + if vty != "ptr" { + return Err(CodegenError::Internal( + "io/print_str needs ptr".into(), + )); + } + self.body + .push_str(&format!(" {call_kw} i32 @puts(ptr {v})\n")); + if tail { + self.body.push_str(" ret i8 0\n"); + self.block_terminated = true; + } + Ok(("0".into(), "i8".into())) +} +``` + +to: + +```rust +"io/print_str" => { + if args.len() != 1 { + return Err(CodegenError::Internal( + "io/print_str arity".into(), + )); + } + let (v, vty) = self.lower_term(&args[0])?; + if vty != "ptr" { + return Err(CodegenError::Internal( + "io/print_str needs ptr".into(), + )); + } + // Iter hs.1: `Str` values now flow as a pointer to the + // `len`-field of the packed-struct slab; @puts needs the + // bytes pointer 8 bytes further on. + let bytes = self.fresh_ssa(); + self.body.push_str(&format!( + " {bytes} = getelementptr inbounds i8, ptr {v}, i64 8\n" + )); + self.body + .push_str(&format!(" {call_kw} i32 @puts(ptr {bytes})\n")); + if tail { + self.body.push_str(" ret i8 0\n"); + self.block_terminated = true; + } + Ok(("0".into(), "i8".into())) +} +``` + +- [ ] **Step 4: Run test to verify it passes.** + +Run: `cargo test --workspace -p ailang-codegen print_str_calls_puts_with_bytes_pointer` +Expected: PASS. + +--- + +## Task 3: `+8` GEPs at `eq__Str` intercept + +**Files:** +- Modify: `crates/ailang-codegen/src/lib.rs:2256-2268` +- Test: `crates/ailang-codegen/src/lib.rs` (test module) + +- [ ] **Step 1: Write the failing test `eq_str_calls_ail_str_eq_with_bytes_pointer`.** + +```rust +/// Iter hs.1: `eq__Str`'s body must `getelementptr i8` +8 on +/// both operand pointers before calling `@ail_str_eq`, since the +/// IR-Str pointer now lands on the `len`-field, not the bytes. +#[test] +fn eq_str_calls_ail_str_eq_with_bytes_pointer() { + let m = Module { + schema: SCHEMA.into(), + name: "prelude".into(), + imports: vec![], + defs: vec![ + Def::Fn(FnDef { + name: "eq__Str".into(), + ty: Type::Fn { + params: vec![Type::str_(), Type::str_()], + ret: Box::new(Type::bool_()), + effects: vec![], + param_modes: vec![ParamMode::Borrow, ParamMode::Borrow], + ret_mode: ParamMode::Implicit, + }, + params: vec!["x".into(), "y".into()], + body: Term::Lit { lit: Literal::Bool { value: false } }, + suppress: vec![], + doc: None, + }), + Def::Fn(FnDef { + name: "main".into(), + ty: Type::Fn { + params: vec![], + ret: Box::new(Type::unit()), + effects: vec![], + param_modes: vec![], + ret_mode: ParamMode::Implicit, + }, + params: vec![], + body: Term::Lit { lit: Literal::Unit }, + suppress: vec![], + doc: None, + }), + ], + }; + let ir = emit_ir(&m).unwrap(); + let body_idx = ir.find("define i1 @ail_prelude_eq__Str").expect("eq__Str body"); + let body = &ir[body_idx..]; + let eq_idx = body.find("@ail_str_eq(").expect("@ail_str_eq call present"); + let before_eq = &body[..eq_idx]; + // Two GEPs (one per operand) must precede the call. + let gep_count = before_eq.matches("getelementptr inbounds i8, ptr ").count(); + assert_eq!( + gep_count, 2, + "expected 2 +8 GEPs before @ail_str_eq (one per operand); ir body was:\n{body}" + ); + assert!( + before_eq.matches(", i64 8").count() >= 2, + "expected both GEPs to be `, i64 8`; ir body was:\n{body}" + ); +} +``` + +- [ ] **Step 2: Run test to verify it fails.** + +Run: `cargo test --workspace -p ailang-codegen eq_str_calls_ail_str_eq_with_bytes_pointer` +Expected: FAIL — current body passes `a_ssa` and `b_ssa` directly. + +- [ ] **Step 3: Add the `+8` GEPs at the `eq__Str` intercept.** + +Modify `crates/ailang-codegen/src/lib.rs:2256-2268` (the `eq__Str` arm +of `try_emit_primitive_instance_body`). Replace the body +construction: + +```rust +let n = self.locals.len(); +let a_ssa = self.locals[n - 2].1.clone(); +let b_ssa = self.locals[n - 1].1.clone(); +let dst = self.fresh_ssa(); +self.body.push_str(&format!( + " {dst} = call zeroext i1 @ail_str_eq(ptr {a_ssa}, ptr {b_ssa})\n" +)); +self.body.push_str(&format!(" ret i1 {dst}\n")); +self.body.push_str("}\n\n"); +self.block_terminated = true; +Ok(true) +``` + +with: + +```rust +let n = self.locals.len(); +let a_ssa = self.locals[n - 2].1.clone(); +let b_ssa = self.locals[n - 1].1.clone(); +// Iter hs.1: IR-Str pointers now land on the `len`-field of the +// packed-struct slab; @ail_str_eq's strcmp-based body needs the +// bytes pointer 8 bytes further on. +let a_bytes = self.fresh_ssa(); +let b_bytes = self.fresh_ssa(); +self.body.push_str(&format!( + " {a_bytes} = getelementptr inbounds i8, ptr {a_ssa}, i64 8\n" +)); +self.body.push_str(&format!( + " {b_bytes} = getelementptr inbounds i8, ptr {b_ssa}, i64 8\n" +)); +let dst = self.fresh_ssa(); +self.body.push_str(&format!( + " {dst} = call zeroext i1 @ail_str_eq(ptr {a_bytes}, ptr {b_bytes})\n" +)); +self.body.push_str(&format!(" ret i1 {dst}\n")); +self.body.push_str("}\n\n"); +self.block_terminated = true; +Ok(true) +``` + +- [ ] **Step 4: Run test to verify it passes.** + +Run: `cargo test --workspace -p ailang-codegen eq_str_calls_ail_str_eq_with_bytes_pointer` +Expected: PASS. + +--- + +## Task 4: `+8` GEPs at `compare__Str` intercept + +**Files:** +- Modify: `crates/ailang-codegen/src/lib.rs:2302-2321` +- Test: `crates/ailang-codegen/src/lib.rs` (test module) + +- [ ] **Step 1: Write the failing test `compare_str_calls_ail_str_compare_with_bytes_pointer`.** + +```rust +/// Iter hs.1: `compare__Str`'s body must `getelementptr i8` +8 +/// on both operand pointers before calling `@ail_str_compare`, +/// symmetric to the `eq__Str` change. +#[test] +fn compare_str_calls_ail_str_compare_with_bytes_pointer() { + // The synth_compare_module helper already exists in the test + // module for the other compare__T tests; use it. + let m = synth_compare_module("compare__Str", Type::str_()); + let ir = emit_ir(&m).unwrap(); + let body_idx = ir + .find("define ptr @ail_prelude_compare__Str") + .expect("compare__Str body"); + let body = &ir[body_idx..]; + let cmp_idx = body + .find("@ail_str_compare(") + .expect("@ail_str_compare call present"); + let before_cmp = &body[..cmp_idx]; + let gep_count = before_cmp.matches("getelementptr inbounds i8, ptr ").count(); + assert_eq!( + gep_count, 2, + "expected 2 +8 GEPs before @ail_str_compare; ir body was:\n{body}" + ); + assert!( + before_cmp.matches(", i64 8").count() >= 2, + "expected both GEPs to be `, i64 8`; ir body was:\n{body}" + ); +} +``` + +(If `synth_compare_module` doesn't exist as a helper, look for the +existing `compare_str_mono_symbol_emits_ail_str_compare_call` test +at `crates/ailang-codegen/src/lib.rs:3626` and copy its fixture +construction inline.) + +- [ ] **Step 2: Run test to verify it fails.** + +Run: `cargo test --workspace -p ailang-codegen compare_str_calls_ail_str_compare_with_bytes_pointer` +Expected: FAIL. + +- [ ] **Step 3: Add the `+8` GEPs at the `compare__Str` intercept.** + +Modify `crates/ailang-codegen/src/lib.rs:2302-2321`. Replace: + +```rust +let n = self.locals.len(); +let a_ssa = self.locals[n - 2].1.clone(); +let b_ssa = self.locals[n - 1].1.clone(); +let cmp_res = self.fresh_ssa(); +self.body.push_str(&format!( + " {cmp_res} = call i32 @ail_str_compare(ptr {a_ssa}, ptr {b_ssa})\n" +)); +self.emit_compare_ladder( + &format!("icmp slt i32 {cmp_res}, 0"), + &format!("icmp eq i32 {cmp_res}, 0"), +)?; +Ok(true) +``` + +with: + +```rust +let n = self.locals.len(); +let a_ssa = self.locals[n - 2].1.clone(); +let b_ssa = self.locals[n - 1].1.clone(); +// Iter hs.1: IR-Str pointers now land on the `len`-field of the +// packed-struct slab; @ail_str_compare's strcmp-based body needs +// the bytes pointer 8 bytes further on. +let a_bytes = self.fresh_ssa(); +let b_bytes = self.fresh_ssa(); +self.body.push_str(&format!( + " {a_bytes} = getelementptr inbounds i8, ptr {a_ssa}, i64 8\n" +)); +self.body.push_str(&format!( + " {b_bytes} = getelementptr inbounds i8, ptr {b_ssa}, i64 8\n" +)); +let cmp_res = self.fresh_ssa(); +self.body.push_str(&format!( + " {cmp_res} = call i32 @ail_str_compare(ptr {a_bytes}, ptr {b_bytes})\n" +)); +self.emit_compare_ladder( + &format!("icmp slt i32 {cmp_res}, 0"), + &format!("icmp eq i32 {cmp_res}, 0"), +)?; +Ok(true) +``` + +- [ ] **Step 4: Run test to verify it passes.** + +Run: `cargo test --workspace -p ailang-codegen compare_str_calls_ail_str_compare_with_bytes_pointer` +Expected: PASS. + +--- + +## Task 5: Regenerate `hello.ll` snapshot and end-to-end regression + +The IR snapshot of `hello.ail` (the only canonical example that +exercises a Str literal through @puts) now mismatches the actual +IR after Tasks 1+2 landed. Regenerate via the project's +`UPDATE_SNAPSHOTS=1` mechanism, then run the full regression +suite to confirm byte-identical program outputs. + +**Files:** +- Modify: `crates/ail/tests/snapshots/hello.ll` (regenerated) + +- [ ] **Step 1: Confirm the `ir_snapshot_hello` test fails before regenerating.** + +Run: `cargo test --workspace -p ail ir_snapshot_hello` +Expected: FAIL — the snapshot mismatch should report a diff +showing the new packed-struct global and the `+8` GEP before `@puts`. + +- [ ] **Step 2: Regenerate the snapshot.** + +Run: `UPDATE_SNAPSHOTS=1 cargo test --workspace -p ail ir_snapshot_hello` +Expected: PASS, with stderr `updated snapshot: `. + +- [ ] **Step 3: Inspect the regenerated snapshot to confirm shape.** + +Run: `head -25 crates/ail/tests/snapshots/hello.ll` +Expected: the `@.str_hello_str_0` global is now +`<{ i64, i64, [15 x i8] }> <{ i64 -1, i64 14, [15 x i8] c"Hello, AILang.\00" }>, align 8` +(exact `len` is 14 because "Hello, AILang." has 14 bytes; total +array is 15 with the trailing `NUL`). The `@puts` call line is +preceded by a `getelementptr inbounds i8, ptr , i64 8` and the +call argument is the GEP result, not the bare global. Confirm +visually before continuing. + +- [ ] **Step 4: Run `cargo test --workspace` end-to-end.** + +Run: `cargo test --workspace` +Expected: PASS, all tests green. + +- [ ] **Step 5: Run `bench/compile_check.py`.** + +Run: `python3 bench/compile_check.py` +Expected: every `examples/` program compiles without error or +warning; the script exits 0. + +- [ ] **Step 6: Run `bench/cross_lang.py`.** + +Run: `python3 bench/cross_lang.py` +Expected: every fixture in `bench/reference/` produces +byte-identical stdout from its AILang and C implementations; +the script exits 0. This is the strongest regression gate — +it confirms that the layout migration left observable program +behaviour completely unchanged. + +- [ ] **Step 7: Confirm no other snapshots changed.** + +Run: `git status crates/ail/tests/snapshots/` +Expected: only `hello.ll` shows as modified. The other snapshots +(`sum.ll`, `list.ll`, `max3.ll`, `ws_main.ll`) contain only +format-string globals (`@.str_*_fmt_int_0` etc.), which kept the +raw `[N x i8]` shape — they should be byte-identical to before. +If any of them changed, investigate before continuing: it means +this iter inadvertently affected format-string emission. + +--- + +## Notes for the implementer + +- The IR-shape tests in Tasks 1-4 all use substring assertions — + insensitive to SSA-naming changes. They will survive future + refactors that rename intermediate variables but break if the + fundamental IR shape changes. + +- Between Tasks 1 and 4 completing, programs that print or compare + Str literals would produce wrong output if executed end-to-end. + The per-task IR-shape tests do not catch this; Task 5's + regression suite does. If `cargo test --workspace` is invoked + mid-iter (between Tasks 1 and 4), it will report failures in + the e2e suite that are EXPECTED and will resolve once Task 4 + lands. The implementer should not panic at intermediate + failures and should not commit before Task 5 reports green. + +- No `runtime/` or `crates/ailang-check/` changes are required in + this iter. If the implementer finds themselves editing those + paths, they have strayed from scope. + +- No `git commit` step. The Boss commits the working-tree diff at + iter end after audit-level inspection.