# 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](0017-prelude-classes.md).
- `bool_to_str : (borrow Bool) -> Str` — `"true"`/`"false"`.
  Backs `Show Bool` in the [prelude](0017-prelude-classes.md).
- `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](0017-prelude-classes.md).
- `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](0017-prelude-classes.md)),
which feeds the heap-Str result of `show x` into `io/print_str`.

Equality on `Str` dispatches via `prelude.Eq.eq` (Str instance,
lowered by `try_emit_primitive_instance_body::eq__Str` to a call
into `@ail_str_eq` with the `alwaysinline` attribute). Ordering on
`Str` dispatches via `prelude.Ord.compare` (Str instance, lowered
by `try_emit_primitive_instance_body::compare__Str` to a call into
`@ail_str_compare` then a three-way branch ladder constructing
`LT`/`EQ`/`GT`). The polymorphic helpers `ne` / `lt` / `le` / `gt`
/ `ge` resolve via the class layer on top of `eq` / `compare`.
There are no primitive operator names `==` / `<` / `!=` / etc. in
the language.

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 (`@fputs`, `@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 print path uses `@fputs(bytes, @stdout)` so that
`(do io/print_str s)` writes exactly the bytes of `s` with no
implicit trailing newline (Gitea #29; the earlier `@puts` lowering
appended a newline per call).

The heap-Str realisation participates in standard RC (see
[memory model](0008-memory-model.md)): 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`.