AILang/design/contracts/str-abi.md

Str ABI

Heap-Str primitives

The runtime ships a small family of operations that produce or transform heap-allocated Str values uniformly across static-Str and heap-Str inputs (the consumer ABI is identical between realisations — see the Str ABI table below). All take their input(s) by borrow and return an owned Str. Each is registered as a builtin in crates/ailang-check/src/builtins.rs, lowered inline in crates/ailang-codegen/src/lib.rs::lower_app to a call ptr @ailang_<name>, and backed by a runtime/str.c C helper.

• int_to_str : (borrow Int) -> Str — decimal rendering of an Int. Backs Show Int in the prelude.
• bool_to_str : (borrow Bool) -> Str — "true"/"false". Backs Show Bool in the prelude.
• float_to_str : (borrow Float) -> Str — type-installed; codegen is reserved and not yet shipped.
• str_clone : (borrow Str) -> Str — allocates a fresh heap-Str copy of the input's bytes. Backs Show Str in the prelude.
• str_concat : (borrow Str, borrow Str) -> Str — combines two Str values into a single owned Str. General-purpose; commonly used in Show bodies for labelled output ((app str_concat "label=" (app int_to_str x))).

The four Show-backers above are not directly observable to the LLM-author writing a Show <T> instance — the prelude's instance bodies dispatch into them. str_concat IS directly observable because the LLM-author calls it explicitly when authoring an instance body that wants to combine fragments.

Primitive output for Str values goes through io/print_str directly; values of other primitive types route through the polymorphic print helper (see prelude classes), which feeds the heap-Str result of show x into io/print_str.

==, <, <=, >, >= REMAIN primitive operators. Class methods are accessed by name (eq x y, lt x y, …), not via these operators.

Arithmetic operators (+, -, *, /) stay primitive and per-type.

Str ABI. A Str is a pointer to a structure with i64 len at offset 0 followed by len bytes plus a trailing NUL at offset 8. Two realisations share this consumer ABI:

Realisation	Origin	rc_header	Memory
static-Str	string literals (@.str_* LLVM globals)	none	.rodata, packed-struct <{ i64, [N+1 x i8] }>
heap-Str	runtime allocations (int_to_str, float_to_str, ...)	yes, at payload - 8	malloc'd via ailang_rc_alloc(8 + len + 1)

Every consumer (@puts, @strcmp, @ail_str_eq, @ail_str_compare) GEPs +8 from the Str pointer to reach the bytes, regardless of realisation. The byte-comparison semantics are inherited from libc strcmp — locale-independent, NUL- terminated.

The heap-Str realisation participates in standard RC (see memory model): the rc_header slot eight bytes before the len field is managed by ailang_rc_alloc / ailang_rc_inc / ailang_rc_dec exactly like any other RC-allocated cell. The static-Str realisation has no rc_header slot at all; the bytes at payload - 8 belong to the previous global in .rodata and reading them is undefined.

The static-Str non-RC invariant is enforced at codegen. Two mechanisms keep static-Str pointers out of ailang_rc_dec along every shipping execution path: (1) the non-escape lowering pass and the move-tracking partial-drop logic prevent let-binders or pattern-binders for static-Str literals from reaching scope-close drop emission; (2) the Type::Con { name: "Str" } carve-outs in field_drop_call and in the Term::App arm of drop_symbol_for_binder (both in crates/ailang-codegen/src/drop.rs) route the rare case that does reach drop emission through ailang_rc_dec, which itself only fires for heap-Str at runtime (static-Str pointers never carry a live rc_header; if codegen ever let one through, the runtime would corrupt .rodata-adjacent memory). No runtime guard backs the invariant up; the codegen proof is the protection.

Ratified by: crates/ail/tests/e2e.rs.