AILang/docs/plans/hs.2.md

# hs.2 — Heap-Str ABI: runtime sentinel + Str-in-ADT drop safety — 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:** Make `ailang_rc_inc` and `ailang_rc_dec` short-circuit on
a `UINT64_MAX` sentinel header, so the static-`Str` slabs emitted
by hs.1's packed-struct layout (whose first slot is `i64 -1`) flow
safely through generic RC paths instead of attempting to write
back to `.rodata` memory. Add the load-bearing safety test
`str_field_in_adt_drops_static_str_noop`, which is the first test
in the project to exercise the path "ADT with a `Str` field,
instantiated with a static literal, dropped under `--alloc=rc`".

**Architecture:** Pure runtime-side change plus one new fixture
and one new e2e test. The hs.1 codegen change emits static-Str
globals whose first `i64` slot is `-1` (= `UINT64_MAX` when read
as `uint64_t`). The hs.1 IR-Str-pointer convention places the
flowing pointer at the `len`-field of the struct, so
`header_of(payload) = payload - 8` lands on that sentinel slot.
Pre-hs.2, `ailang_rc_dec(static_str_field_ptr)` reads
`*hdr = UINT64_MAX` (passes the underflow check at `runtime/rc.c:166`
since `UINT64_MAX != 0`), then `*hdr -= 1` attempts to write
`UINT64_MAX - 1` to the read-only data section → SIGSEGV. hs.2
inserts a sentinel check that short-circuits both functions
before either reads or writes the header value any further, making
the static-`Str` case a defined no-op. `ailang_rc_alloc`'s counters
are untouched on the short-circuit path (`g_rc_alloc_count` only
fires inside `ailang_rc_alloc` itself; `g_rc_free_count` only fires
on the to-zero branch in `ailang_rc_dec`, after the sentinel check)
— so `AILANG_RC_STATS`-based tests continue to report accurate
allocs/frees for the heap path while seeing zero traffic from
static `Str` literals.

**Tech Stack:** C runtime (`runtime/rc.c`), AILang fixture
(`examples/`), Rust e2e harness (`crates/ail/tests/e2e.rs`).

---

## Files this plan creates or modifies

- **Create:** `examples/rc_str_field_in_adt_static.ail.json` — new
  fixture mirroring `examples/rc_box_drop.ail.json` shape with a
  `Str` field in place of an `Int` field. Exercises the
  static-`Str`-in-ADT drop path under `--alloc=rc`.
- **Modify:** `runtime/rc.c:132-145` — add sentinel-header
  short-circuit to `ailang_rc_inc`.
- **Modify:** `runtime/rc.c:161-177` — add sentinel-header
  short-circuit to `ailang_rc_dec`.
- **Test:** `crates/ail/tests/e2e.rs` (append at end of file, after
  current line 2561) — new test `str_field_in_adt_drops_static_str_noop`
  using the existing `build_and_run_with_rc_stats` helper at
  `crates/ail/tests/e2e.rs:2093-2150`.

---

## Task 1: Author the static-Str-in-ADT fixture and confirm it builds

The new test in Task 2 requires a `.ail.json` fixture exercising
`type StrBox = | MkStrBox(Str)` with a static-`Str` payload under
`--alloc=rc`. This task creates that fixture and confirms it
typechecks and builds without errors (running the binary is
deferred to Task 2 — pre-hs.2 the binary would crash under
`--alloc=rc`).

**Files:**
- Create: `examples/rc_str_field_in_adt_static.ail.json`

- [ ] **Step 1: Create the fixture.**

Write the file at `examples/rc_str_field_in_adt_static.ail.json`
with this exact content, modelled verbatim on
`examples/rc_box_drop.ail.json` with `Int` → `Str` and
`io/print_int` → `io/print_str`:

```json
{
  "schema": "ailang/v0",
  "name": "rc_str_field_in_adt_static",
  "imports": [],
  "defs": [
    {
      "kind": "type",
      "name": "StrBox",
      "vars": [],
      "doc": "Single-cell ADT around a Str. Iter hs.2 RC fixture: exercises the static-Str-in-ADT drop path under --alloc=rc. Pre-hs.2 the binary segfaults at drop time because `ailang_rc_dec(static_str_payload_ptr)` reads UINT64_MAX from the sentinel header slot and attempts to write UINT64_MAX-1 to .rodata. Post-hs.2 `ailang_rc_dec` short-circuits on the sentinel; the drop is a defined no-op and the outer StrBox cell frees normally.",
      "ctors": [
        {
          "name": "MkStrBox",
          "fields": [{ "k": "con", "name": "Str" }]
        }
      ]
    },
    {
      "kind": "fn",
      "name": "main",
      "type": {
        "k": "fn",
        "params": [],
        "ret": { "k": "con", "name": "Unit" },
        "effects": ["IO"]
      },
      "params": [],
      "doc": "Bind a heap-allocated MkStrBox(\"hello\") to `b`, read its Str via match, print it. Under --alloc=rc the let-scope close calls drop_t_StrBox(b), which in turn calls ailang_rc_dec on the Str field — that pointer is the static-Str literal global from hs.1, so the sentinel-header short-circuit must make this safe.",
      "body": {
        "t": "let",
        "name": "b",
        "value": {
          "t": "ctor",
          "type": "StrBox",
          "ctor": "MkStrBox",
          "args": [{ "t": "lit", "lit": { "kind": "str", "value": "hello" } }]
        },
        "body": {
          "t": "match",
          "scrutinee": { "t": "var", "name": "b" },
          "arms": [
            {
              "pat": {
                "p": "ctor",
                "ctor": "MkStrBox",
                "fields": [{ "p": "var", "name": "s" }]
              },
              "body": {
                "t": "do",
                "op": "io/print_str",
                "args": [{ "t": "var", "name": "s" }]
              }
            }
          ]
        }
      }
    }
  ]
}
```

- [ ] **Step 2: Confirm the fixture typechecks.**

Run: `cargo run --bin ail --quiet -- check examples/rc_str_field_in_adt_static.ail.json`
Expected: exit 0, no diagnostics on stderr. The fixture follows
the canonical-form schema verbatim; any diagnostic would indicate
a copy-paste error.

- [ ] **Step 3: Confirm the fixture builds under `--alloc=rc`.**

Run: `cargo run --bin ail --quiet -- build examples/rc_str_field_in_adt_static.ail.json --alloc=rc -o /tmp/hs2_fixture_build_check`
Expected: exit 0; a binary appears at `/tmp/hs2_fixture_build_check`.
**Do NOT execute the binary in this step** — pre-hs.2 it segfaults
on the static-Str field drop. The Task 2 RED-test step runs it.

---

## Task 2: Sentinel-header short-circuit in `ailang_rc_inc` and `ailang_rc_dec` (TDD)

This is the heart of the iter. The RED test is the
spec's load-bearing `str_field_in_adt_drops_static_str_noop`
safety gate — until hs.2's runtime change lands, no test in the
project exercises this path, and the path is latent UB.

**Files:**
- Modify: `runtime/rc.c:132-145, 161-177`
- Test: `crates/ail/tests/e2e.rs` (append after current line 2561)

- [ ] **Step 1: Write the failing test `str_field_in_adt_drops_static_str_noop`.**

Append to `crates/ail/tests/e2e.rs` at the end of the file:

```rust
/// Iter hs.2 load-bearing safety gate. The hs.1 layout migration
/// turned the path "ADT-with-Str-field instantiated with a static
/// literal, dropped under --alloc=rc" into latent UB: the
/// per-type drop fn calls `ailang_rc_dec(field_ptr)` on the
/// static-Str payload pointer, which under hs.1 lands on the
/// `len`-field of the packed-struct global; `header_of(ptr) =
/// ptr - 8` reads the sentinel slot (= UINT64_MAX); the
/// underflow check `*hdr == 0` passes (UINT64_MAX != 0); then
/// `*hdr -= 1` attempts to write to the read-only data section.
/// hs.2 short-circuits both `ailang_rc_inc` and `ailang_rc_dec`
/// on the sentinel before the header is mutated, making the
/// path a defined no-op. This test is the first in the project
/// to exercise it: pre-hs.2 the binary segfaults; post-hs.2 it
/// reports `live=0` and exits cleanly.
#[test]
fn str_field_in_adt_drops_static_str_noop() {
    let (stdout, allocs, frees, live) =
        build_and_run_with_rc_stats("rc_str_field_in_adt_static.ail.json");
    assert_eq!(
        stdout.trim(),
        "hello",
        "fixture must print the matched Str payload"
    );
    assert_eq!(
        live, 0,
        "static-Str-in-ADT drop must not leak; live={live} \
         (allocs={allocs} frees={frees}). The sentinel short-circuit \
         in ailang_rc_dec for static-Str field pointers must not \
         increment g_rc_free_count, and the outer StrBox cell must \
         drop normally."
    );
}
```

- [ ] **Step 2: Run the test to verify it fails.**

Run: `cargo test --workspace -p ail str_field_in_adt_drops_static_str_noop`
Expected: FAIL. The most likely failure mode is the assertion
`output.status.success()` inside `build_and_run_with_rc_stats`
at `crates/ail/tests/e2e.rs:2119-2123` panicking with
`binary <path> (--alloc=rc, AILANG_RC_STATS=1) exited non-zero`,
because the binary either SIGSEGVs writing to `.rodata` or
gets caught by `ailang_rc_dec`'s `abort()` on a write attempt.
A secondary possible failure mode is the rc-stats line being
absent from stderr because the program crashed before the
`atexit` handler ran — in that case the panic is at
`crates/ail/tests/e2e.rs:2129-2131`
(`missing ailang_rc_stats line in stderr`). Either failure
shape is the expected RED state; both go GREEN once Step 3
lands.

- [ ] **Step 3: Add the sentinel-header short-circuit to `ailang_rc_inc`.**

Modify `runtime/rc.c:132-145`. The current body is:

```c
void ailang_rc_inc(void *payload) {
    if (payload == NULL) {
        return;
    }
    /* Static closure-pair env pointers (Iter 8b) live in the LLVM data
     * segment, not in heap memory we allocated. Codegen elides inc/dec
     * for known-static pointers (the `@`-prefix gate added in 18c.3),
     * so this path is not reached for them in practice. The runtime
     * itself has no header-bit flag distinguishing static from heap;
     * if codegen ever loses the elision, inc on a static pointer is
     * undefined behaviour. */
    ailang_rc_header_t *hdr = header_of(payload);
    *hdr += 1;
}
```

Replace with:

```c
void ailang_rc_inc(void *payload) {
    if (payload == NULL) {
        return;
    }
    /* Static closure-pair env pointers (Iter 8b) live in the LLVM data
     * segment, not in heap memory we allocated. Codegen elides inc/dec
     * for known-static pointers (the `@`-prefix gate added in 18c.3),
     * so this path is not reached for them in practice. The runtime
     * itself has no header-bit flag distinguishing static from heap;
     * if codegen ever loses the elision, inc on a static pointer is
     * undefined behaviour. */
    ailang_rc_header_t *hdr = header_of(payload);
    /* Iter hs.2: static-Str literal slabs (emitted by the codegen as
     * packed-struct globals in iter hs.1) carry the sentinel header
     * value UINT64_MAX in the slot at `payload - 8`. Such slabs live
     * in the `.rodata` section; their refcount must never be mutated.
     * Codegen does not elide inc/dec on static-Str field pointers
     * (the `@`-prefix elision in 18c.3 covered only closure-pair
     * env pointers, not Str payload pointers materialised via
     * constexpr GEP). The sentinel-header short-circuit makes inc
     * a defined no-op for such pointers. The same convention
     * applies to `ailang_rc_dec` below. */
    if (*hdr == UINT64_MAX) {
        return;
    }
    *hdr += 1;
}
```

- [ ] **Step 4: Add the sentinel-header short-circuit to `ailang_rc_dec`.**

Modify `runtime/rc.c:161-177`. The current body is:

```c
void ailang_rc_dec(void *payload) {
    if (payload == NULL) {
        return;
    }
    ailang_rc_header_t *hdr = header_of(payload);
    if (*hdr == 0) {
        fprintf(stderr,
                "ailang_rc_dec: refcount underflow at %p (already zero)\n",
                payload);
        abort();
    }
    *hdr -= 1;
    if (*hdr == 0) {
        free(hdr);
        g_rc_free_count++;
    }
}
```

Replace with:

```c
void ailang_rc_dec(void *payload) {
    if (payload == NULL) {
        return;
    }
    ailang_rc_header_t *hdr = header_of(payload);
    /* Iter hs.2: static-Str literal slabs carry the sentinel
     * UINT64_MAX in the header slot and live in `.rodata`.
     * Short-circuit before the underflow check (UINT64_MAX != 0
     * would otherwise pass the underflow guard and reach the
     * read-modify-write at `*hdr -= 1`, segfaulting on `.rodata`).
     * See the matching comment in `ailang_rc_inc` above. */
    if (*hdr == UINT64_MAX) {
        return;
    }
    if (*hdr == 0) {
        fprintf(stderr,
                "ailang_rc_dec: refcount underflow at %p (already zero)\n",
                payload);
        abort();
    }
    *hdr -= 1;
    if (*hdr == 0) {
        free(hdr);
        g_rc_free_count++;
    }
}
```

- [ ] **Step 5: Confirm `UINT64_MAX` is reachable in `runtime/rc.c`.**

Run: `grep -n '#include <stdint.h>' runtime/rc.c`
Expected: a single line `48:#include <stdint.h>` (or equivalent).
`UINT64_MAX` is provided by `<stdint.h>`, which is already
included by `runtime/rc.c:48`. No new include is needed.
If for some reason the include is missing, add `#include <stdint.h>`
to the include block at the top of the file.

- [ ] **Step 6: Run the test to verify it passes.**

Run: `cargo test --workspace -p ail str_field_in_adt_drops_static_str_noop`
Expected: PASS. The fixture's binary runs cleanly, prints
`hello`, the atexit handler reports `allocs=N frees=N live=0`
for the heap-side StrBox cell (one alloc for the StrBox outer,
one matching free at let-scope close), and the test's
`assert_eq!(live, 0, ...)` succeeds.

---

## Task 3: Full regression sweep

Confirm the runtime change broke nothing else. The sentinel
short-circuit adds one early-return branch in two hot-path
functions; in principle the only behavioural effect is on
pointers whose header equals `UINT64_MAX`, which today is only
the static-Str case. Belt-and-braces verify against every other
RC-discipline test and against the cross-language reference
corpus.

**Files:**
- (none — read-only verification)

- [ ] **Step 1: Run the full cargo test workspace.**

Run: `cargo test --workspace`
Expected: PASS, all tests green. Specifically, the existing
`alloc_rc_*` tests (12 fixtures exercising heap allocations
of various ADTs under `--alloc=rc`) continue to report
matching allocs/frees because none of them carry a `Str`
field and therefore none of them ever calls
`ailang_rc_dec(static_str_ptr)`.

- [ ] **Step 2: Run `bench/compile_check.py`.**

Run: `python3 bench/compile_check.py`
Expected: every `examples/` program — including the new
`rc_str_field_in_adt_static.ail.json` — compiles without
errors or warnings; the script exits 0.

- [ ] **Step 3: 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. None of these fixtures carries an
ADT-with-`Str`-field today, so the sentinel short-circuit
is not exercised; the test confirms no orthogonal regression
crept in.

---

## Notes for the implementer

- The hs.1 packed-struct globals emit `i64 -1` for the sentinel
  slot. When read as `uint64_t` this is bit-for-bit equivalent to
  `UINT64_MAX` (`0xFFFFFFFFFFFFFFFF` in both signed twos-complement
  -1 and unsigned UINT64_MAX representations). The codegen-side
  emits `-1`; the runtime-side checks against `UINT64_MAX`. Both
  refer to the same 64-bit pattern.

- Beyond the sentinel-Str case, the only way a real refcount could
  reach `UINT64_MAX` is via `2^64` independent references — which
  would consume more memory than exists on any machine. The
  collision-with-real-refcount case is structurally impossible,
  not just unlikely.

- The block-comment at `runtime/rc.c:136-142` describes a different
  static-pointer case (closure-pair env pointers in the `.data`
  segment, which have no header at all and rely entirely on
  codegen-side elision). It is NOT outdated by hs.2 — the
  closure-pair case still relies on codegen-side elision, and the
  sentinel guard is orthogonal additional protection for a
  different kind of static pointer (Str literals). Do not edit
  that comment.

- No `git commit` step. The Boss commits the working-tree diff at
  iter end after audit-level inspection.