iter hs.1: static-Str layout migration — packed-struct globals + sentinel rc-header + len

First iter of the heap-Str ABI milestone. Pure codegen refactor; every existing program produces byte-identical stdout.

Static-Str LLVM globals migrate from `[N x i8] c"…\00"` to `<{ i64, i64, [N x i8] }> <{ i64 -1, i64 N-1, [N x i8] c"…\00" }>`, carrying the UINT64_MAX sentinel rc-header (slot exploited in hs.2 via runtime short-circuit) and an explicit byte length. Two parallel intern paths (`intern_string` for raw format scaffolding, new `intern_str_literal` for language Str values) keep format strings untouched in `[N x i8]` shape.

IR-Str pointers now uniformly land on the len-field (offset +8 from rc-header, -8 from bytes). Four codegen sites that hand a Str pointer to a NUL-terminated-bytes C-API consumer now emit a +8 GEP first: `@puts` (io/print_str), `@ail_str_eq` (eq__Str intercept), `@ail_str_compare` (compare__Str intercept), and `@strcmp` (lower_eq Str arm — the 4th site was not in the plan; surfaced by Task-5 e2e regression and fixed inline).

6 new IR-shape pinning tests; `hello.ll` snapshot regenerated; cross_lang.py + compile_check.py + full `cargo test --workspace` green.

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

@@ -0,0 +1,19 @@
+{
+  "iter_id": "hs.1",
+  "date": "2026-05-12",
+  "mode": "standard",
+  "outcome": "DONE",
+  "tasks_total": 5,
+  "tasks_completed": 5,
+  "reloops_per_task": {
+    "1": 0,
+    "2": 0,
+    "3": 0,
+    "4": 0,
+    "5": 1
+  },
+  "review_loops_spec": 0,
+  "review_loops_quality": 0,
+  "blocked_reason": null,
+  "notes": "Task 5 incurred one extra inline implementer-phase loop after the e2e regression suite surfaced a fourth codegen site (lower_eq Str arm, line 2520-2529 calling @strcmp directly) the plan did not enumerate. Fix shape was identical to Tasks 2-4 (+8 GEP on operands), added one pinning test, and discharged the iter's stated acceptance criterion (byte-identical stdout). Logged in journal Concerns as a plan-enumeration gap."
+}

crates/ail/tests/snapshots/hello.ll

@@ -2,7 +2,7 @@
 source_filename = "hello.ail"
 target triple = "<NORMALIZED>"
 
-@.str_hello_str_0 = private unnamed_addr constant [15 x i8] c"Hello, AILang.\00", align 1
+@.str_hello_str_0 = private unnamed_addr constant <{ i64, i64, [15 x i8] }> <{ i64 -1, i64 14, [15 x i8] c"Hello, AILang.\00" }>, align 8
 
 declare i32 @printf(ptr, ...)
 declare i32 @puts(ptr)
@@ -15,7 +15,8 @@ declare i64 @llvm.fptosi.sat.i64.f64(double)
 @ail_hello_main_clos = private unnamed_addr constant { ptr, ptr } { ptr @ail_hello_main_adapter, ptr null }
 define i8 @ail_hello_main() {
 entry:
-  call i32 @puts(ptr @.str_hello_str_0)
+  %v1 = getelementptr inbounds i8, ptr getelementptr inbounds (<{ i64, i64, [15 x i8] }>, ptr @.str_hello_str_0, i32 0, i32 1), i64 8
+  call i32 @puts(ptr %v1)
   ret i8 0
 }
 

crates/ailang-codegen/src/lib.rs

@@ -282,6 +282,10 @@ fn lower_workspace_inner(ws: &Workspace, alloc: AllocStrategy) -> Result<String>
     let mut body = String::new();
     let mut all_strings: BTreeMap<String, Vec<(String, String)>> = BTreeMap::new();
     // ^ per module: list of (global-name, content). Order = insertion order.
+    // Iter hs.1: parallel aggregation for language `Str`-literal globals
+    // (packed-struct shape). Same map shape; emitted by a parallel loop
+    // alongside the existing one.
+    let mut all_str_literals: BTreeMap<String, Vec<(String, String)>> = BTreeMap::new();
 
     // Pass 1: per-module top-level symbol tables.
     // - `module_user_fns`: LLVM-typed FnSig for monomorphic fns. Used by
@@ -408,6 +412,13 @@ fn lower_workspace_inner(ws: &Workspace, alloc: AllocStrategy) -> Result<String>
         // uses a monotonic counter, so alphabetic is enough).
         entries.sort_by(|a, b| a.0.cmp(&b.0));
         all_strings.insert(mname.clone(), entries);
+        // Iter hs.1: parallel collection of `Str`-literal globals.
+        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);
     }
 
     // Trampoline: verify that the entry module has a
@@ -448,6 +459,21 @@ fn lower_workspace_inner(ws: &Workspace, alloc: AllocStrategy) -> Result<String>
             emitted_global = true;
         }
     }
+    // Iter hs.1: packed-struct globals for language `Str` literals.
+    // The `i64 -1` slot is the `UINT64_MAX` sentinel rc-header; the
+    // next `i64` is the byte length (excluding the trailing NUL); the
+    // `[N+1 x i8]` carries the bytes followed by the terminating NUL.
+    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;
+        }
+    }
     if emitted_global {
         out.push('\n');
     }
@@ -532,6 +558,13 @@ struct Emitter<'a> {
     body: String,
     /// String constants: content -> (global name (without `@`), llvm type length incl. \0)
     strings: BTreeMap<String, (String, usize)>,
+    /// Iter hs.1: language `Str` literals interned as packed-struct
+    /// globals (`<{ i64, i64, [N+1 x i8] }>`) carrying a `UINT64_MAX`
+    /// sentinel rc-header and an explicit `len` field. Parallel to
+    /// `strings` (which still serves runtime-internal format strings
+    /// like `%lld\n` / `true\n` in the raw `[N x i8]` shape). Same
+    /// key shape; the two tables coexist.
+    str_literals: BTreeMap<String, (String, usize)>,
     /// Local symbol table per function: (name, ssa, llvm_type, ail_type).
     /// The AILang type is recorded so that the codegen-side type tracker
     /// can derive substitutions at polymorphic call sites without
@@ -751,6 +784,7 @@ impl<'a> Emitter<'a> {
             header: String::new(),
             body: String::new(),
             strings: BTreeMap::new(),
+            str_literals: BTreeMap::new(),
             locals: Vec::new(),
             counter: 0,
             str_counter: 0,
@@ -888,8 +922,18 @@ impl<'a> Emitter<'a> {
             ),
             Literal::Unit => ("i8".to_string(), "0".to_string()),
             Literal::Str { value } => {
-                let g = self.intern_string("str", value);
-                ("ptr".to_string(), format!("@{g}"))
+                // Iter hs.1: emit a packed-struct global and return a
+                // constexpr-GEP pointer landing on the `len`-field, so
+                // every IR-Str pointer in this codegen pipeline has
+                // the same shape (header at -8, len at 0, bytes at +8).
+                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)",
+                    ),
+                )
             }
             Literal::Float { bits } => ("double".to_string(), format!("0x{:016X}", bits)),
         };
@@ -1200,10 +1244,18 @@ impl<'a> Emitter<'a> {
                     "i1".into(),
                 ),
                 Literal::Str { value } => {
-                    // Create global constant; in opaque-pointer LLVM,
-                    // `@name` is directly a valid `ptr`.
-                    let g = self.intern_string("str", value);
-                    (format!("@{g}"), "ptr".into())
+                    // Iter hs.1: language `Str` literals materialise as
+                    // a constexpr-GEP into the packed-struct global,
+                    // landing on the `len`-field so the IR-Str
+                    // pointer carries header at -8 and bytes at +8.
+                    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(),
+                    )
                 }
                 Literal::Unit => ("0".into(), "i8".into()),
                 Literal::Float { bits } => (format!("0x{:016X}", bits), "double".into()),
@@ -2161,8 +2213,15 @@ impl<'a> Emitter<'a> {
                         "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 {v})\n"));
+                    .push_str(&format!("  {call_kw} i32 @puts(ptr {bytes})\n"));
                 if tail {
                     self.body.push_str("  ret i8 0\n");
                     self.block_terminated = true;
@@ -2258,9 +2317,21 @@ impl<'a> Emitter<'a> {
                 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_ssa}, ptr {b_ssa})\n"
+                    "  {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");
@@ -2309,9 +2380,21 @@ impl<'a> Emitter<'a> {
                 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_ssa}, ptr {b_ssa})\n"
+                    "  {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"),
@@ -2435,9 +2518,22 @@ impl<'a> Emitter<'a> {
                     Ok((dst, "i1".into()))
                 }
                 "Str" => {
+                    // Iter hs.1: IR-Str pointers now land on the
+                    // `len`-field of the packed-struct slab; @strcmp
+                    // needs the bytes pointer 8 bytes further on.
+                    // Parallel to the `eq__Str` and `compare__Str`
+                    // intercepts in `try_emit_primitive_instance_body`.
+                    let a_bytes = self.fresh_ssa();
+                    let b_bytes = self.fresh_ssa();
+                    self.body.push_str(&format!(
+                        "  {a_bytes} = getelementptr inbounds i8, ptr {a}, i64 8\n"
+                    ));
+                    self.body.push_str(&format!(
+                        "  {b_bytes} = getelementptr inbounds i8, ptr {b}, i64 8\n"
+                    ));
                     let cmp = self.fresh_ssa();
                     self.body.push_str(&format!(
-                        "  {cmp} = call i32 @strcmp(ptr {a}, ptr {b})\n"
+                        "  {cmp} = call i32 @strcmp(ptr {a_bytes}, ptr {b_bytes})\n"
                     ));
                     let dst = self.fresh_ssa();
                     self.body.push_str(&format!(
@@ -2497,6 +2593,23 @@ impl<'a> Emitter<'a> {
         name
     }
 
+    /// Iter hs.1: parallel to `intern_string`, but for language `Str`
+    /// literals emitted as packed-struct globals (sentinel + len +
+    /// bytes + NUL). Shares the same monotonic `str_counter` so the
+    /// produced global names remain alphabetically orderable
+    /// alongside format-string globals.
+    fn intern_str_literal(&mut self, hint: &str, content: &str) -> String {
+        if let Some((name, _)) = self.str_literals.get(content) {
+            return name.clone();
+        }
+        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
+    }
+
     /// Iter 12b: lightweight AILang-type computation for an expression
     /// in the current scope. Mirrors what the typechecker already
     /// derived; we replay it here only because the typechecker doesn't
@@ -3693,4 +3806,272 @@ mod tests {
             defs: vec![ordering, compare, main_def],
         }
     }
+
+    /// 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_(),
+                    value: 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}"
+        );
+    }
+
+    /// 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!["IO".into()],
+                    param_modes: vec![],
+                    ret_mode: ParamMode::Implicit,
+                },
+                params: vec![],
+                body: Term::Do {
+                    op: "io/print_str".into(),
+                    args: vec![Term::Lit { lit: Literal::Str { value: "hi".into() } }],
+                    tail: false,
+                },
+                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}"
+        );
+    }
+
+    /// 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!["IO".into()],
+                    param_modes: vec![],
+                    ret_mode: ParamMode::Implicit,
+                },
+                params: vec![],
+                body: Term::Do {
+                    op: "io/print_str".into(),
+                    args: vec![Term::Lit { lit: Literal::Str { value: "hi".into() } }],
+                    tail: false,
+                },
+                suppress: vec![],
+                doc: None,
+            })],
+        };
+        let ir = emit_ir(&m).unwrap();
+        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 <v>, i64 8` before @puts call; ir body was:\n{body}"
+        );
+    }
+
+    /// 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}"
+        );
+    }
+
+    /// 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() {
+        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}"
+        );
+    }
+
+    /// Iter hs.1: the `==` operator on `Str` lowers via an inline
+    /// `@strcmp` call (separate from the `eq__Str` instance-method
+    /// intercept used by the dictionary path). Both operand pointers
+    /// must be `+8` GEP'd to land on the bytes pointer before
+    /// `@strcmp`, symmetric to the `eq__Str` and `compare__Str`
+    /// fixes. Without this, `==` on Str literals reads the 8-byte
+    /// `len`-field as bytes and never finds the NUL terminator
+    /// within the expected range, breaking string equality.
+    #[test]
+    fn lower_eq_str_calls_strcmp_with_bytes_pointer() {
+        let m = Module {
+            schema: SCHEMA.into(),
+            name: "t".into(),
+            imports: vec![],
+            defs: vec![
+                Def::Fn(FnDef {
+                    name: "test".into(),
+                    ty: Type::Fn {
+                        params: vec![],
+                        ret: Box::new(Type::bool_()),
+                        effects: vec![],
+                        param_modes: vec![],
+                        ret_mode: ParamMode::Implicit,
+                    },
+                    params: vec![],
+                    body: Term::App {
+                        callee: Box::new(Term::Var { name: "==".into() }),
+                        args: vec![
+                            Term::Lit { lit: Literal::Str { value: "a".into() } },
+                            Term::Lit { lit: Literal::Str { value: "b".into() } },
+                        ],
+                        tail: 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_t_test").expect("test body");
+        let body = &ir[body_idx..];
+        let cmp_idx = body.find("@strcmp(").expect("@strcmp 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 @strcmp (one per operand); 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}"
+        );
+    }
 }

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

@@ -0,0 +1,118 @@
+# iter hs.1 — Heap-Str ABI: Static-Str layout migration
+
+**Date:** 2026-05-12
+**Started from:** 69bb5f9952fb51af7cdf4e36f77cff1b6cd73c40
+**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 GEP`s 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 GEP`s 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`

docs/journals/INDEX.md

@@ -30,3 +30,4 @@
 - 2026-05-12 — audit-ms: milestone close (Multi-subject Authoring-Form Test — CodeLlama Replication) — architect clean, bench all-green (same 5-metric latency.explicit_at_rc improvement cluster as audit-cma earlier today, baseline left pristine for second consecutive audit) → 2026-05-12-audit-ms.md
 - 2026-05-12 — iter ext-rename: `.ailx` → `.ail` extension rename across the live toolchain (61 example renames + 35 content edits + experiment-crate cohort rename `ailx → ail`); historical docs (journals, archive, specs, plans, frozen experiment runs) deliberately untouched; cargo+bench all-green; opens follow-up `.ail`-CLI-acceptance iter → 2026-05-12-iter-ext-rename.md
 - 2026-05-12 — iter ext-cli.1: `ail check`/build/run/...all 12 path-taking subcommands now accept `.ail` (Form A) inputs via `ailang_surface::{load_module, load_workspace}` (extension-dispatching loaders + injection point `core::load_workspace_with<F>`); workspace imports prefer `.ail` sibling over `.ail.json`; new `WorkspaceLoadError::SurfaceParse` variant routes surface parse errors as `surface-parse-error` structured diagnostics through `ail check --json`; DESIGN.md §Decision 6 CLI addendum; +7 new tests; closes the loop opened by iter ext-rename → 2026-05-12-iter-ext-cli.1.md
+- 2026-05-12 — iter hs.1: heap-Str ABI iter 1 — static-Str LLVM globals migrate from `[N x i8]` to packed-struct `<{ i64, i64, [N x i8] }>` carrying a `UINT64_MAX` sentinel rc-header + explicit `len`; IR-Str pointers now land on the `len`-field; `@puts` / `@ail_str_eq` / `@ail_str_compare` / `@strcmp` callsites GEP +8 to recover the bytes pointer (4 sites; plan listed 3, Task-5 e2e regression surfaced the 4th); 6 IR-shape pins; format strings stay raw `[N x i8]`; cross_lang.py + compile_check.py + full cargo test --workspace all green; byte-identical stdout across every example → 2026-05-12-iter-hs.1.md