AILang/docs/plans/24.1.md

# 24.1 — `bool_to_str` + `str_clone` Runtime + Codegen Wiring — Implementation Plan

> **Parent spec:** `docs/specs/2026-05-12-24-show-print.md` (commit 953f2e1)
>
> **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement`
> to run this plan. Steps use `- [ ]` checkboxes for tracking.

**Goal:** Wire two new heap-Str-producing primitives — `bool_to_str`
and `str_clone` — through the runtime C code, type checker, codegen
IR lowering, and IR-header preamble, mechanically mirror-imaging
the existing hs.4 wiring for `int_to_str` / `float_to_str`.

**Architecture:** Pure-additive wiring across four crates / files.
The two new C functions live in `runtime/str.c` next to
`ailang_int_to_str` / `ailang_float_to_str`. Type signatures land
lockstep in `crates/ailang-check/src/builtins.rs::install` and
`crates/ailang-codegen/src/synth.rs::builtin_value_type` (both
sides MUST agree on `ParamMode::Own` for `ret_mode`). Codegen
gains two IR-header declares, two `Emitter::lower_app` arms, and
two `is_static_callee` whitelist entries — all in
`crates/ailang-codegen/src/lib.rs`. Five IR snapshots regenerate
because the header preamble grows by two lines. Nine new tests
land: 2 builtins-install unit tests (parallel to
`install_int_to_str_signature`), 2 IR-shape unit pins (parallel to
`int_to_str_lowers_to_ailang_int_to_str_call`), 2 RC-stats E2E,
2 stdout-smoke E2E (one per Bool branch), plus a cross-realisation
E2E for `str_clone`. No checker-level architectural decisions —
all design is committed in the parent spec.

**Tech Stack:** `ailang-check::builtins`,
`ailang-codegen::lib::Emitter::{lower_app, is_static_callee}`,
`ailang-codegen::synth::builtin_value_type`, `runtime/str.c` (C
with `<stdbool.h>`), `crates/ail/tests/e2e.rs` (E2E harness with
`build_and_run_with_rc_stats` from eob.1).

---

**Files this plan creates or modifies:**

- Modify: `runtime/str.c:143` — append two new C functions
  `ailang_bool_to_str(bool)` and `ailang_str_clone(const char *)`.
- Modify: `crates/ailang-check/src/builtins.rs:212` — insert two new
  `env.globals.insert` blocks for `bool_to_str` and `str_clone`
  (parallel to the existing `int_to_str` / `float_to_str` blocks at
  `:193-212`).
- Modify: `crates/ailang-check/src/builtins.rs:307` — add row
  `("int_to_str", "(Int) -> Str")` (pre-existing drift: hs.4 installed
  it in `env.globals` but missed the `list()` row) plus two new rows
  for `bool_to_str` and `str_clone`.
- Modify: `crates/ailang-check/src/builtins.rs:467` — append two new
  unit tests `install_bool_to_str_signature` and
  `install_str_clone_signature` (parallel to the existing
  `install_int_to_str_signature` at `:461-467`).
- Modify: `crates/ailang-codegen/src/synth.rs:180` — insert two new
  arms in `builtin_value_type` for `bool_to_str` and `str_clone`
  (parallel to the existing `int_to_str` arm at `:174-180`).
- Modify: `crates/ailang-codegen/src/lib.rs:538` — insert two new
  IR-header declares `declare ptr @ailang_bool_to_str(i1)` and
  `declare ptr @ailang_str_clone(ptr)` after the existing
  `@ailang_int_to_str` / `@ailang_float_to_str` declares at
  `:537-538`.
- Modify: `crates/ailang-codegen/src/lib.rs:1933` — insert two new
  `lower_app` arms for `bool_to_str` and `str_clone` after the
  existing `float_to_str` arm at `:1915-1933`.
- Modify: `crates/ailang-codegen/src/lib.rs:2133` — extend
  `is_static_callee` `matches!` whitelist (at `:2126-2134`) with
  `"bool_to_str"` and `"str_clone"`.
- Modify: `crates/ailang-codegen/src/lib.rs:4204` — append two new
  IR-shape pin tests `bool_to_str_emits_call_to_ailang_bool_to_str`
  and `str_clone_emits_call_to_ailang_str_clone` (parallel to the
  existing `int_to_str_lowers_to_ailang_int_to_str_call` at
  `:4131-4165`).
- Modify: `crates/ail/tests/snapshots/hello.ll`, `list.ll`, `max3.ll`,
  `sum.ll`, `ws_main.ll` — regenerate 5 IR snapshots via
  `UPDATE_SNAPSHOTS=1 cargo test ir_snapshot_` after the IR header
  grows by two `declare` lines.
- Create: `examples/bool_to_str_drop_rc.ail.json` — `let s = bool_to_str true in do io/print_str s` for the RC-stats test.
- Create: `examples/bool_to_str_smoke_false.ail.json` — `let s = bool_to_str false in do io/print_str s` for the false-branch stdout-smoke test.
- Create: `examples/str_clone_drop_rc.ail.json` — `let s = str_clone "hello" in do io/print_str s` for the RC-stats test (also doubles as the stdout-smoke test for `str_clone`).
- Create: `examples/str_clone_cross_realisation.ail.json` — clones both `int_to_str 42` (heap-Str input) and the static-Str literal `"abc"` and prints both, pinning the uniform consumer ABI claim.
- Test: `crates/ail/tests/e2e.rs:2657` — append five new tests
  (`bool_to_str_drop_balances_rc_stats`,
  `bool_to_str_emits_true_branch`, `bool_to_str_emits_false_branch`,
  `str_clone_drop_balances_rc_stats`,
  `str_clone_cross_realisation_uniform_abi`).

---

### Task 1: Runtime C functions in `runtime/str.c`

Add two new C functions paralleling `ailang_int_to_str` /
`ailang_float_to_str`. Both allocate fresh heap-Str slabs via the
existing `str_alloc` helper (which calls `ailang_rc_alloc`) and
return the payload pointer. `<stdbool.h>` is already included at
`:16` so `bool` is in scope.

**Files:**
- Modify: `runtime/str.c:143`

- [ ] **Step 1: Append `ailang_bool_to_str` after `ailang_float_to_str`**

Edit `runtime/str.c` — insert after the closing brace of
`ailang_float_to_str` (which ends at line 143):

```c

/* Convert a bool into a heap-allocated Str — "true" (4 bytes) or
 * "false" (5 bytes). Heap-allocates every call; the static-Str
 * literal alternative (used by a hypothetical `\x -> if x then "true"
 * else "false"` schema body) would require phi-of-static-Str
 * through the drop-elision pipeline which is not load-bearing-
 * ratified today (see parent spec §"Out of scope" / `bool_to_str` as
 * schema-if).
 *
 * Returns the payload pointer of a fresh heap-Str slab.
 */
char *ailang_bool_to_str(bool b) {
    const char *lit = b ? "true" : "false";
    uint64_t len = b ? 4 : 5;
    char *payload = str_alloc(len);
    memcpy(payload + 8, lit, len);
    payload[8 + len] = '\0';
    return payload;
}
```

- [ ] **Step 2: Append `ailang_str_clone` after `ailang_bool_to_str`**

Edit `runtime/str.c` — insert after the closing brace of the just-
added `ailang_bool_to_str`:

```c

/* Clone a Str into a fresh heap-Str slab. Reads `len` from the
 * first 8 bytes of the source payload, allocates a new slab of the
 * same length via `str_alloc`, and memcpy's the payload bytes plus
 * the trailing NUL. Works uniformly on static-Str and heap-Str
 * inputs because the consumer ABI (i64 len at offset 0, bytes
 * starting at offset 8, NUL at offset 8 + len) is identical
 * between realisations (see DESIGN.md §"Str ABI"); the rc_header at
 * offset -8 — present only on heap-Str — is never consulted.
 *
 * Used by `show__Str` (parent spec milestone 24): converts a
 * borrowed Str input into an Owned heap-Str output, preserving
 * the uniform `show : forall a. Show a => (a borrow) -> Str Own`
 * signature.
 *
 * Returns the payload pointer of a fresh heap-Str slab.
 */
char *ailang_str_clone(const char *src) {
    uint64_t len = *(const uint64_t *)src;
    char *payload = str_alloc(len);
    memcpy(payload + 8, src + 8, len);
    payload[8 + len] = '\0';
    return payload;
}
```

- [ ] **Step 3: Verify str.c compiles standalone via `cargo build --workspace`**

Run: `cargo build --workspace 2>&1 | tail -20`
Expected: clean build, no warnings, no errors. (The new C functions
are unreachable from any IR call site until Task 3 lands the
codegen wiring, but the .o builds fine in isolation.)

---

### Task 2: Builtin install — checker + synth.rs lockstep + `list()` rows + unit tests

Install both signatures in `crates/ailang-check/src/builtins.rs::install`
with `ret_mode: ParamMode::Own`, mirror in
`crates/ailang-codegen/src/synth.rs::builtin_value_type`. Add the
two new rows plus the pre-existing-missing `int_to_str` row in
`list()`. Two new unit tests in builtins.rs's tests module.

**Files:**
- Modify: `crates/ailang-check/src/builtins.rs:212`
- Modify: `crates/ailang-check/src/builtins.rs:307`
- Modify: `crates/ailang-check/src/builtins.rs:467`
- Modify: `crates/ailang-codegen/src/synth.rs:180`

- [ ] **Step 1: Insert `bool_to_str` and `str_clone` env.globals.insert blocks**

Edit `crates/ailang-check/src/builtins.rs:212` — insert after the
closing of the `int_to_str` block (which ends at line 212, the line
with `);`) and before the `env.globals.insert("is_nan".into(), ...)`
block at line 213:

```rust
    env.globals.insert(
        "bool_to_str".into(),
        Type::Fn {
            params: vec![Type::bool_()],
            ret: Box::new(Type::str_()),
            effects: vec![],
            param_modes: vec![],
            ret_mode: ailang_core::ast::ParamMode::Own,
        },
    );
    env.globals.insert(
        "str_clone".into(),
        Type::Fn {
            params: vec![Type::str_()],
            ret: Box::new(Type::str_()),
            effects: vec![],
            param_modes: vec![ailang_core::ast::ParamMode::Borrow],
            ret_mode: ailang_core::ast::ParamMode::Own,
        },
    );
```

Note: `str_clone`'s `param_modes` carries an explicit `Borrow` for
the single Str input, matching the parent spec's
`(Str borrow) -> Str` signature. `bool_to_str`'s `param_modes` stays
empty (Bool is bit-copied; no borrow/own distinction).

- [ ] **Step 2: Add three rows to `list()` vec — `int_to_str` (drift fix), `bool_to_str`, `str_clone`**

Edit `crates/ailang-check/src/builtins.rs:307` — replace the line:

```rust
        ("float_to_str", "(Float) -> Str"),
```

with:

```rust
        ("float_to_str", "(Float) -> Str"),
        ("int_to_str", "(Int) -> Str"),
        ("bool_to_str", "(Bool) -> Str"),
        ("str_clone", "(Str) -> Str"),
```

(The `int_to_str` row is the pre-existing-drift fix flagged by
plan-recon; hs.4 added the `env.globals` entry at `:204` but missed
the corresponding `list()` row.)

- [ ] **Step 3: Append `install_bool_to_str_signature` and `install_str_clone_signature` unit tests**

Edit `crates/ailang-check/src/builtins.rs:467` — insert after the
closing brace of `install_int_to_str_signature` (which ends at line
467) and before the next test (`install_is_nan_signature` at line
473):

```rust

    /// Iter 24.1: `bool_to_str : (Bool) -> Str`. Codegen lowers via the
    /// runtime C glue `ailang_bool_to_str` from `runtime/str.c`.
    #[test]
    fn install_bool_to_str_signature() {
        let ty = synth_in_builtins_env(&app("bool_to_str", vec![lit_bool(true)]));
        assert_eq!(ty, Type::str_(), "(bool_to_str true) must type as Str");
    }

    /// Iter 24.1: `str_clone : (Str borrow) -> Str`. Codegen lowers via the
    /// runtime C glue `ailang_str_clone` from `runtime/str.c`.
    #[test]
    fn install_str_clone_signature() {
        let ty = synth_in_builtins_env(&app("str_clone", vec![lit_str("hi")]));
        assert_eq!(ty, Type::str_(), "(str_clone \"hi\") must type as Str");
    }
```

Note: if `lit_bool` / `lit_str` test helpers do not exist in the
local test module, fall back to the explicit shape:

```rust
let ty = synth_in_builtins_env(&app(
    "bool_to_str",
    vec![Term::Lit { lit: Literal::Bool { value: true } }],
));
```

(check the existing `install_is_nan_signature` test at `:474-479`
for the in-use helper shape; if it uses `lit_float`, then
`lit_bool` / `lit_str` likely exist as siblings.)

- [ ] **Step 4: Run builtins.rs tests to verify all three new tests pass**

Run: `cargo test --workspace -p ailang-check builtins::tests 2>&1 | tail -20`
Expected: all builtins::tests green, including the two new
`install_bool_to_str_signature` and `install_str_clone_signature`.

- [ ] **Step 5: Mirror lockstep arms in `synth.rs::builtin_value_type`**

Edit `crates/ailang-codegen/src/synth.rs:180` — insert after the
closing brace of the `int_to_str` arm (which ends at line 180,
`},`) and before the `is_nan` arm at line 181:

```rust
        "bool_to_str" => Type::Fn {
            params: vec![Type::bool_()],
            ret: Box::new(Type::str_()),
            effects: vec![],
            param_modes: vec![],
            ret_mode: ParamMode::Own,
        },
        "str_clone" => Type::Fn {
            params: vec![Type::str_()],
            ret: Box::new(Type::str_()),
            effects: vec![],
            param_modes: vec![ParamMode::Borrow],
            ret_mode: ParamMode::Own,
        },
```

- [ ] **Step 6: Verify lockstep — full workspace builds clean**

Run: `cargo build --workspace 2>&1 | tail -20`
Expected: clean build, no warnings. Both `builtins.rs::install` and
`synth.rs::builtin_value_type` now agree on the two new symbols.

---

### Task 3: Codegen IR wiring — header preamble declares + `lower_app` arms + `is_static_callee` whitelist

Three sub-edits all in `crates/ailang-codegen/src/lib.rs`. Adds two
IR-header `declare` lines, two `lower_app` call-emission arms, and
two whitelist entries in `is_static_callee`.

**Files:**
- Modify: `crates/ailang-codegen/src/lib.rs:538`
- Modify: `crates/ailang-codegen/src/lib.rs:1933`
- Modify: `crates/ailang-codegen/src/lib.rs:2133`

- [ ] **Step 1: Add two IR-header declares**

Edit `crates/ailang-codegen/src/lib.rs:538` — replace the line:

```rust
    out.push_str("declare ptr @ailang_float_to_str(double)\n");
```

with:

```rust
    out.push_str("declare ptr @ailang_float_to_str(double)\n");
    // Iter 24.1: heap-Str primitive externs for the `show` instances
    // — `ailang_bool_to_str` (Show Bool) and `ailang_str_clone`
    // (Show Str). Same dual-realisation ABI as int_to_str /
    // float_to_str: rc_header at offset -8 on the heap-Str output;
    // consumer ABI shared with static-Str (len at offset 0, bytes
    // at offset 8). Declared unconditionally on the same rationale
    // — runtime/str.c is unconditionally linked and clang -O2 dead-
    // strips when no caller exists.
    out.push_str("declare ptr @ailang_bool_to_str(i1)\n");
    out.push_str("declare ptr @ailang_str_clone(ptr)\n");
```

- [ ] **Step 2: Add two `lower_app` arms**

Edit `crates/ailang-codegen/src/lib.rs:1933` — insert after the
closing brace of the `float_to_str` arm (which ends at line 1933,
the line with `}`) and before line 1934 (the blank line preceding
the cross-module-call comment block):

```rust
        if name == "bool_to_str" {
            // Iter 24.1: lowers to the runtime C glue
            // `ailang_bool_to_str(i1) -> ptr` defined in
            // `runtime/str.c`. Returned pointer is a heap-Str
            // (rc_header at offset -8; consumer ABI shared with
            // static-Str). Used by `show__Bool` in milestone 24.
            if args.len() != 1 {
                return Err(CodegenError::Internal("bool_to_str arity".into()));
            }
            let (a, _) = self.lower_term(&args[0])?;
            let dst = self.fresh_ssa();
            self.body.push_str(&format!(
                "  {dst} = call ptr @ailang_bool_to_str(i1 {a})\n"
            ));
            return Ok((dst, "ptr".to_string()));
        }
        if name == "str_clone" {
            // Iter 24.1: lowers to the runtime C glue
            // `ailang_str_clone(ptr) -> ptr` defined in
            // `runtime/str.c`. Reads `len` from offset 0 of the
            // source Str payload and allocates a fresh heap-Str
            // slab; works uniformly on static-Str and heap-Str
            // inputs because the consumer ABI is identical. Used by
            // `show__Str` in milestone 24.
            if args.len() != 1 {
                return Err(CodegenError::Internal("str_clone arity".into()));
            }
            let (a, _) = self.lower_term(&args[0])?;
            let dst = self.fresh_ssa();
            self.body.push_str(&format!(
                "  {dst} = call ptr @ailang_str_clone(ptr {a})\n"
            ));
            return Ok((dst, "ptr".to_string()));
        }
```

- [ ] **Step 3: Extend `is_static_callee` whitelist**

Edit `crates/ailang-codegen/src/lib.rs:2133` — replace the line:

```rust
                | "int_to_str"
```

with:

```rust
                | "int_to_str"
                | "bool_to_str"
                | "str_clone"
```

- [ ] **Step 4: Build workspace to verify codegen compiles**

Run: `cargo build --workspace 2>&1 | tail -20`
Expected: clean build, no warnings, no errors. The new arms are
unreachable from any test yet, but the file compiles.

---

### Task 4: IR-shape unit pin tests in `lib.rs::tests`

Two new tests in `crates/ailang-codegen/src/lib.rs`'s `mod tests`
block, mechanical copies of the existing
`int_to_str_lowers_to_ailang_int_to_str_call` template.

**Files:**
- Modify: `crates/ailang-codegen/src/lib.rs:4204`

- [ ] **Step 1: Append `bool_to_str_emits_call_to_ailang_bool_to_str`**

Edit `crates/ailang-codegen/src/lib.rs:4204` — insert after the
closing brace of `float_to_str_no_longer_errors_internal` (which
ends at line 4204, `}`) and before the `}` of `mod tests` at line
4205:

```rust

    /// Iter 24.1: a `Term::App` calling `bool_to_str` lowers to
    /// `call ptr @ailang_bool_to_str(i1 %a)`. Pins the new builtin's
    /// lowering shape against the runtime C glue introduced in this
    /// iter (mirror of hs.4's `int_to_str_lowers_to_ailang_int_to_str_call`).
    #[test]
    fn bool_to_str_emits_call_to_ailang_bool_to_str() {
        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::App {
                        callee: Box::new(Term::Var { name: "bool_to_str".into() }),
                        args: vec![Term::Lit { lit: Literal::Bool { value: true } }],
                        tail: false,
                    }],
                    tail: false,
                },
                suppress: vec![],
                doc: None,
            })],
        };
        let ir = emit_ir(&m).unwrap();
        assert!(
            ir.contains("call ptr @ailang_bool_to_str(i1 "),
            "expected lowering of bool_to_str to call @ailang_bool_to_str; ir was:\n{ir}"
        );
    }
```

- [ ] **Step 2: Append `str_clone_emits_call_to_ailang_str_clone`**

Edit `crates/ailang-codegen/src/lib.rs` — insert immediately after
the closing brace of `bool_to_str_emits_call_to_ailang_bool_to_str`
just added in Step 1:

```rust

    /// Iter 24.1: a `Term::App` calling `str_clone` lowers to
    /// `call ptr @ailang_str_clone(ptr %a)`. Pins the new builtin's
    /// lowering shape against the runtime C glue introduced in this
    /// iter (mirror of hs.4's `int_to_str_lowers_to_ailang_int_to_str_call`).
    #[test]
    fn str_clone_emits_call_to_ailang_str_clone() {
        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::App {
                        callee: Box::new(Term::Var { name: "str_clone".into() }),
                        args: vec![Term::Lit { lit: Literal::Str { value: "hi".into() } }],
                        tail: false,
                    }],
                    tail: false,
                },
                suppress: vec![],
                doc: None,
            })],
        };
        let ir = emit_ir(&m).unwrap();
        assert!(
            ir.contains("call ptr @ailang_str_clone(ptr "),
            "expected lowering of str_clone to call @ailang_str_clone; ir was:\n{ir}"
        );
    }
```

- [ ] **Step 3: Run the two new tests**

Run: `cargo test --workspace -p ailang-codegen bool_to_str_emits_call_to_ailang_bool_to_str str_clone_emits_call_to_ailang_str_clone 2>&1 | tail -20`
Expected: both PASS.

---

### Task 5: Regenerate the five IR snapshots

The IR header preamble grew by two `declare` lines (Task 3 Step 1),
which shifts the byte content of every IR snapshot. Five existing
snapshots in `crates/ail/tests/snapshots/` need regeneration. The
snapshot harness lives at `crates/ail/tests/ir_snapshot.rs:76` and
honours `UPDATE_SNAPSHOTS=1` to overwrite the goldens.

**Files:**
- Modify: `crates/ail/tests/snapshots/hello.ll`
- Modify: `crates/ail/tests/snapshots/list.ll`
- Modify: `crates/ail/tests/snapshots/max3.ll`
- Modify: `crates/ail/tests/snapshots/sum.ll`
- Modify: `crates/ail/tests/snapshots/ws_main.ll`

- [ ] **Step 1: Verify the IR-snapshot tests FAIL pre-regen**

Run: `cargo test --workspace -p ail ir_snapshot_ 2>&1 | tail -30`
Expected: all five `ir_snapshot_*` tests FAIL with diff output
showing the new `declare ptr @ailang_bool_to_str(i1)` and
`declare ptr @ailang_str_clone(ptr)` lines appearing in the
generated IR but not in the golden.

- [ ] **Step 2: Regenerate snapshots**

Run: `UPDATE_SNAPSHOTS=1 cargo test --workspace -p ail ir_snapshot_ 2>&1 | tail -10`
Expected: all five `ir_snapshot_*` tests PASS (because
`UPDATE_SNAPSHOTS=1` overwrites the goldens rather than asserting
against them).

- [ ] **Step 3: Verify the regenerated snapshots have exactly the two new declares**

Run: `grep -c "declare ptr @ailang_bool_to_str\|declare ptr @ailang_str_clone" crates/ail/tests/snapshots/*.ll`
Expected: each of the 5 files reports 2 (one match for each new
declare line).

- [ ] **Step 4: Verify the IR-snapshot tests now PASS without UPDATE_SNAPSHOTS**

Run: `cargo test --workspace -p ail ir_snapshot_ 2>&1 | tail -10`
Expected: all five `ir_snapshot_*` tests PASS.

---

### Task 6: E2E fixtures + tests + acceptance gate

Four new `.ail.json` fixtures in `examples/`, five new E2E tests in
`crates/ail/tests/e2e.rs`, then the full acceptance run.

**Files:**
- Create: `examples/bool_to_str_drop_rc.ail.json`
- Create: `examples/bool_to_str_smoke_false.ail.json`
- Create: `examples/str_clone_drop_rc.ail.json`
- Create: `examples/str_clone_cross_realisation.ail.json`
- Modify: `crates/ail/tests/e2e.rs:2657`

- [ ] **Step 1: Create `examples/bool_to_str_drop_rc.ail.json`**

Write a new file `examples/bool_to_str_drop_rc.ail.json` with this
exact content (template: `examples/int_to_str_drop_rc.ail.json`
adapted for `bool_to_str` with literal `true`):

```json
{
  "schema": "ailang/v0",
  "name": "bool_to_str_drop_rc",
  "imports": [],
  "defs": [
    {
      "kind": "fn",
      "name": "main",
      "type": {
        "k": "fn",
        "params": [],
        "ret": { "k": "con", "name": "Unit" },
        "effects": ["IO"]
      },
      "params": [],
      "doc": "Iter 24.1: pin that `bool_to_str` participates in RC discipline. Bind the heap-Str result to `s`, consume `s` once in `io/print_str`, let the binder drop at scope close. Under --alloc=rc with AILANG_RC_STATS=1 the atexit summary must report allocs == 1 && frees == 1 && live == 0 — the heap-Str slab allocated by str_alloc inside ailang_bool_to_str rides the same rc_header + ailang_rc_dec path as int_to_str.",
      "body": {
        "t": "let",
        "name": "s",
        "value": {
          "t": "app",
          "fn": { "t": "var", "name": "bool_to_str" },
          "args": [{ "t": "lit", "lit": { "kind": "bool", "value": true } }]
        },
        "body": {
          "t": "do",
          "op": "io/print_str",
          "args": [{ "t": "var", "name": "s" }]
        }
      }
    }
  ]
}
```

- [ ] **Step 2: Create `examples/bool_to_str_smoke_false.ail.json`**

Write a new file `examples/bool_to_str_smoke_false.ail.json` with this
exact content (identical to Step 1's fixture but with literal `false`):

```json
{
  "schema": "ailang/v0",
  "name": "bool_to_str_smoke_false",
  "imports": [],
  "defs": [
    {
      "kind": "fn",
      "name": "main",
      "type": {
        "k": "fn",
        "params": [],
        "ret": { "k": "con", "name": "Unit" },
        "effects": ["IO"]
      },
      "params": [],
      "doc": "Iter 24.1: stdout-smoke for the false branch of bool_to_str. Stdout must be `false\\n` (puts adds the newline). Companion of bool_to_str_drop_rc.ail.json (which covers the true branch and the RC-stats invariant).",
      "body": {
        "t": "let",
        "name": "s",
        "value": {
          "t": "app",
          "fn": { "t": "var", "name": "bool_to_str" },
          "args": [{ "t": "lit", "lit": { "kind": "bool", "value": false } }]
        },
        "body": {
          "t": "do",
          "op": "io/print_str",
          "args": [{ "t": "var", "name": "s" }]
        }
      }
    }
  ]
}
```

- [ ] **Step 3: Create `examples/str_clone_drop_rc.ail.json`**

Write a new file `examples/str_clone_drop_rc.ail.json` with this
exact content (clones the static-Str literal `"hello"`):

```json
{
  "schema": "ailang/v0",
  "name": "str_clone_drop_rc",
  "imports": [],
  "defs": [
    {
      "kind": "fn",
      "name": "main",
      "type": {
        "k": "fn",
        "params": [],
        "ret": { "k": "con", "name": "Unit" },
        "effects": ["IO"]
      },
      "params": [],
      "doc": "Iter 24.1: pin that `str_clone` participates in RC discipline AND emits correct bytes. Input is a static-Str literal; the clone produces a fresh heap-Str slab whose payload is byte-equal to the input. RC stats under --alloc=rc with AILANG_RC_STATS=1: allocs == 1 (the clone), frees == 1 (let-binder drop at scope close), live == 0.",
      "body": {
        "t": "let",
        "name": "s",
        "value": {
          "t": "app",
          "fn": { "t": "var", "name": "str_clone" },
          "args": [{ "t": "lit", "lit": { "kind": "str", "value": "hello" } }]
        },
        "body": {
          "t": "do",
          "op": "io/print_str",
          "args": [{ "t": "var", "name": "s" }]
        }
      }
    }
  ]
}
```

- [ ] **Step 4: Create `examples/str_clone_cross_realisation.ail.json`**

Write a new file `examples/str_clone_cross_realisation.ail.json`
that clones one heap-Str (output of `int_to_str 42`) and one
static-Str (literal `"abc"`) in sequence, printing both:

```json
{
  "schema": "ailang/v0",
  "name": "str_clone_cross_realisation",
  "imports": [],
  "defs": [
    {
      "kind": "fn",
      "name": "main",
      "type": {
        "k": "fn",
        "params": [],
        "ret": { "k": "con", "name": "Unit" },
        "effects": ["IO"]
      },
      "params": [],
      "doc": "Iter 24.1: cross-realisation invariant for str_clone. Clones a heap-Str (produced by int_to_str 42) AND a static-Str (literal `abc`); both clones produce fresh heap-Str slabs that print their input bytes. Pins the uniform-consumer-ABI claim — str_clone only reads the len-field at offset 0 plus the bytes plus the NUL; it never consults the (absent for static-Str) rc_header. RC stats under --alloc=rc: allocs == 3 (int_to_str output + two str_clone outputs), frees == 3, live == 0.",
      "body": {
        "t": "let",
        "name": "src_heap",
        "value": {
          "t": "app",
          "fn": { "t": "var", "name": "int_to_str" },
          "args": [{ "t": "lit", "lit": { "kind": "int", "value": 42 } }]
        },
        "body": {
          "t": "let",
          "name": "c1",
          "value": {
            "t": "app",
            "fn": { "t": "var", "name": "str_clone" },
            "args": [{ "t": "var", "name": "src_heap" }]
          },
          "body": {
            "t": "let",
            "name": "c2",
            "value": {
              "t": "app",
              "fn": { "t": "var", "name": "str_clone" },
              "args": [{ "t": "lit", "lit": { "kind": "str", "value": "abc" } }]
            },
            "body": {
              "t": "let",
              "name": "_a",
              "value": {
                "t": "do",
                "op": "io/print_str",
                "args": [{ "t": "var", "name": "c1" }]
              },
              "body": {
                "t": "do",
                "op": "io/print_str",
                "args": [{ "t": "var", "name": "c2" }]
              }
            }
          }
        }
      }
    }
  ]
}
```

- [ ] **Step 5: Append five new tests to `crates/ail/tests/e2e.rs`**

Edit `crates/ail/tests/e2e.rs:2657` — insert immediately after the
closing brace of `heap_str_repeated_print_balances_rc_stats` (which
ends at line 2657, the last `}` before the EOF):

```rust

/// Iter 24.1: `bool_to_str(true)` bound to a let, consumed by
/// `io/print_str`. The heap-Str slab from `ailang_bool_to_str`
/// rides the same rc_header + ailang_rc_dec path as int_to_str's
/// output — `allocs == 1, frees == 1, live == 0` and stdout is
/// `true\n`. Companion of `bool_to_str_emits_false_branch` which
/// covers the false-branch stdout.
#[test]
fn bool_to_str_drop_balances_rc_stats() {
    let (stdout, allocs, frees, live) =
        build_and_run_with_rc_stats("bool_to_str_drop_rc.ail.json");
    assert_eq!(stdout, "true\n");
    assert_eq!(allocs, 1, "expected exactly one heap-Str slab; got allocs={allocs}");
    assert_eq!(frees, 1, "expected exactly one free; got frees={frees}");
    assert_eq!(live, 0, "no leaked heap-Str slabs allowed; live={live}");
}

/// Iter 24.1: stdout-smoke for the true branch — same fixture as
/// `bool_to_str_drop_balances_rc_stats` but checked here without
/// the RC-stats overhead. Pins the byte content of `ailang_bool_to_str`'s
/// "true" slab.
#[test]
fn bool_to_str_emits_true_branch() {
    let out = build_and_run("bool_to_str_drop_rc.ail.json");
    assert_eq!(out, "true\n");
}

/// Iter 24.1: stdout-smoke for the false branch. Pins the byte
/// content of `ailang_bool_to_str`'s "false" slab.
#[test]
fn bool_to_str_emits_false_branch() {
    let out = build_and_run("bool_to_str_smoke_false.ail.json");
    assert_eq!(out, "false\n");
}

/// Iter 24.1: `str_clone("hello")` bound to a let, consumed by
/// `io/print_str`. The heap-Str clone allocates a fresh slab (via
/// str_alloc) and the let-binder drops it at scope close.
/// `allocs == 1, frees == 1, live == 0`; stdout is `hello\n` (puts
/// adds the newline) — confirming the memcpy preserved every byte.
#[test]
fn str_clone_drop_balances_rc_stats() {
    let (stdout, allocs, frees, live) =
        build_and_run_with_rc_stats("str_clone_drop_rc.ail.json");
    assert_eq!(stdout, "hello\n");
    assert_eq!(allocs, 1, "expected exactly one heap-Str clone slab; got allocs={allocs}");
    assert_eq!(frees, 1, "expected exactly one free; got frees={frees}");
    assert_eq!(live, 0, "no leaked heap-Str slabs allowed; live={live}");
}

/// Iter 24.1: cross-realisation invariant — `str_clone` works
/// uniformly on heap-Str input (`int_to_str 42`'s output) AND on
/// static-Str input (literal `"abc"`). Both clones print their
/// input bytes; RC stats account for three heap-Str slabs (one
/// from int_to_str, two from str_clone) and three matching frees.
/// Pins the "uniform consumer ABI" claim from DESIGN.md §"Str
/// ABI" — str_clone only reads len + bytes + NUL, never the
/// rc_header.
#[test]
fn str_clone_cross_realisation_uniform_abi() {
    let (stdout, allocs, frees, live) =
        build_and_run_with_rc_stats("str_clone_cross_realisation.ail.json");
    assert_eq!(stdout, "42\nabc\n");
    assert_eq!(allocs, 3, "expected one int_to_str slab + two str_clone slabs; got allocs={allocs}");
    assert_eq!(frees, 3, "expected three matching frees; got frees={frees}");
    assert_eq!(live, 0, "no leaked heap-Str slabs allowed; live={live}");
}
```

- [ ] **Step 6: Run the five new e2e tests**

Run: `cargo test --workspace -p ail bool_to_str_drop_balances_rc_stats bool_to_str_emits_true_branch bool_to_str_emits_false_branch str_clone_drop_balances_rc_stats str_clone_cross_realisation_uniform_abi 2>&1 | tail -30`
Expected: all five PASS.

- [ ] **Step 7: Full workspace test run — acceptance gate**

Run: `cargo test --workspace 2>&1 | tail -30`
Expected: all tests green, including the six new ones (two unit
IR-pins from Task 4, four E2E tests from Task 6 Step 5 — well, five
counting the smoke-false). No previously-passing tests regress.

- [ ] **Step 8: Bench scripts — acceptance gate**

Run: `bench/compile_check.py 2>&1 | tail -10`
Expected: exit 0, all metrics within tolerance. (Codegen additions
shouldn't move compile-time meaningfully; only two new declares
plus two arms.)

Run: `bench/cross_lang.py 2>&1 | tail -10`
Expected: exit 0, all metrics within tolerance. (Runtime additions
are unreached by any benchmark — no callers yet.)

- [ ] **Step 9: Grep verification — every new symbol is wired through every layer**

Run: `grep -rn "bool_to_str\|str_clone" runtime/str.c crates/ailang-check/src/builtins.rs crates/ailang-codegen/src/synth.rs crates/ailang-codegen/src/lib.rs | grep -v test | wc -l`
Expected: ≥ 10 hits (the eight code edits from Tasks 1-3 plus the
two whitelist entries in is_static_callee).

Run: `grep -n "ailang_bool_to_str\|ailang_str_clone" crates/ail/tests/snapshots/*.ll | wc -l`
Expected: 10 hits (2 declares × 5 snapshot files).

Run: `cargo build --workspace 2>&1 | grep -E "warning|error" | head`
Expected: empty (no warnings, no errors).