# eob.1 — Effect-op arguments borrow — Implementation Plan

> **Parent spec:** `docs/specs/0020-effect-op-borrow.md`
>
> **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement`
> to run this plan. Steps use `- [ ]` checkboxes for tracking.

**Goal:** Land the language rule that `Term::Do.args[*]` are walked
in `Position::Borrow` by the uniqueness and linearity passes,
together with the two heap-Str-specific shape fixes (`ret_mode: Own`
for `int_to_str` / `float_to_str`; Str carve-out in the App arm of
`drop_symbol_for_binder`) that make the existing RED tests at
`crates/ail/tests/e2e.rs` flip to GREEN under `--alloc=rc`. Close
the heap-str-abi milestone in the same iter via DESIGN anchor +
WhatsNew + roadmap update.

**Architecture:** Five layers, one iteration.
(1) Two analyser walkers + their shared doc-comment flip the
`Term::Do` arm from Consume to Borrow.
(2) Four signature sites (`builtins.rs` + `synth.rs`, lockstep
pairs for `int_to_str` and `float_to_str`) switch `ret_mode` from
`Implicit` to `Own`.
(3) One drop-fn-symbol picker site adds a `Type::Con { name: "Str", .. }`
carve-out in the App arm, symmetric to the existing carve-out in
`field_drop_call`.
(4) The two existing RED tests at `e2e.rs` (commit `592d87b`) flip
to GREEN unchanged; two new positive tests pin (a) a primitive Int
effect-op arg (no RC bookkeeping) and (b) a repeated Str borrow
through two `io/print_str` calls (linearity allows; RC balances).
(5) `DESIGN.md` anchors both arg-position rules (Ctor = Consume,
Do = Borrow) under Decision 10; `WhatsNew.md` gets the milestone
entry; `roadmap.md` checks off the heap-`Str` ABI P1 entry.

**Tech Stack:** `ailang-check` (uniqueness + linearity passes),
`ailang-codegen` (synth-replay table + drop machinery),
`ail` (E2E tests), `runtime/str.c` already in place from hs.3.

**Files this plan creates or modifies:**

- Modify: `crates/ailang-check/src/uniqueness.rs:289-292` — Term::Do arg-walk Consume → Borrow.
- Modify: `crates/ailang-check/src/linearity.rs:506-510` — Term::Do arg-walk Consume → Borrow.
- Modify: `crates/ailang-check/src/linearity.rs:42` — module doc-comment: split Ctor + Do bullet.
- Modify: `crates/ailang-check/src/builtins.rs:193-202` — `float_to_str` `ret_mode: Implicit` → `Own`.
- Modify: `crates/ailang-check/src/builtins.rs:203-212` — `int_to_str` `ret_mode: Implicit` → `Own`.
- Modify: `crates/ailang-codegen/src/synth.rs:167-172` — `float_to_str` synth replay `ret_mode: Implicit` → `Own`.
- Modify: `crates/ailang-codegen/src/synth.rs:174-180` — `int_to_str` synth replay `ret_mode: Implicit` → `Own`.
- Modify: `crates/ailang-codegen/src/drop.rs:534-549` — App arm of `drop_symbol_for_binder` gets `Str` carve-out.
- Modify: `crates/ail/tests/e2e.rs` — append two new positive tests near `:2624`.
- Create: `examples/int_to_print_int_borrow.ail.json` — fixture for primitive-Int effect-op-arg test.
- Create: `examples/heap_str_repeated_print_borrow.ail.json` — fixture for repeated-Str-borrow test.
- Modify: `docs/DESIGN.md` — anchor `Term::Ctor.args[*] = Consume` + `Term::Do.args[*] = Borrow` under Decision 10.
- Modify: `docs/WhatsNew.md` — append milestone entry (newest at bottom).
- Modify: `docs/roadmap.md:41-56` — close `[milestone] Heap-Str ABI` (check off, then remove); update the dependent `[milestone] Post-22 Prelude` entry's `depends on:` line accordingly.
- Test: existing `crates/ail/tests/e2e.rs::int_to_str_drop_balances_rc_stats` and `::str_field_in_adt_drops_heap_str_correctly` — verify GREEN unchanged after Tasks 1-3 land.

---

### Task 1: Term::Do arg-walks flip Consume → Borrow

**Files:**
- Modify: `crates/ailang-check/src/uniqueness.rs:289-292`
- Modify: `crates/ailang-check/src/linearity.rs:506-510`
- Modify: `crates/ailang-check/src/linearity.rs:42` (doc comment)

The three sites are atomic — analyser code paths and their
documentation must stay in sync. Flip all three in one task.

- [ ] **Step 1: Confirm RED status of the leak's pinned tests.**

Run: `cargo test --workspace -p ail --test e2e int_to_str_drop_balances_rc_stats str_field_in_adt_drops_heap_str_correctly`

Expected: both tests FAIL. `int_to_str_drop_balances_rc_stats` fails on
`assert_eq!(allocs, frees)` with `allocs=1, frees=0`.
`str_field_in_adt_drops_heap_str_correctly` fails on the same assert
with `allocs=2, frees=1`. These two failures are the RED pin from
commit `592d87b`.

- [ ] **Step 2: Flip uniqueness.rs Term::Do arm.**

In `crates/ailang-check/src/uniqueness.rs`, at the `Term::Do { args, .. }` arm
near line 289, change:

```rust
Term::Do { args, .. } => {
    for a in args {
        self.walk(a, Position::Consume);
    }
}
```

to:

```rust
Term::Do { args, .. } => {
    for a in args {
        self.walk(a, Position::Borrow);
    }
}
```

- [ ] **Step 3: Flip linearity.rs Term::Do arm.**

In `crates/ailang-check/src/linearity.rs`, at the `Term::Do { args, .. }` arm
near line 506, change `Position::Consume` to `Position::Borrow` in the
same shape as Step 2. The Ctor arm immediately above (`:500-505`) stays
on `Position::Consume` — the asymmetry is the rule.

- [ ] **Step 4: Update linearity.rs:42 doc comment.**

Find the bullet at `crates/ailang-check/src/linearity.rs:42`:

```text
//! - `Term::Ctor.args[*]`, `Term::Do.args[*]` — Consume.
```

Replace with two bullets that match the new code structure:

```text
//! - `Term::Ctor.args[*]` — Consume (the new value owns them).
//! - `Term::Do.args[*]` — Borrow (effect-op observes; ownership
//!   stays with the caller).
```

The Borrow bullet sits alongside `Term::Match.scrutinee` (`:37-38`)
and `Term::Clone.value` (`:35-36`) as the other Borrow-position sites.

- [ ] **Step 5: Build the check crate to confirm no compile errors.**

Run: `cargo build -p ailang-check`

Expected: clean build. (At this point, the heap-Str-specific shape
fixes from Tasks 2-3 are still missing, so the RED tests stay RED.
That's the design — Tasks 1, 2, 3 are mutually dependent for the
RED→GREEN flip.)

- [ ] **Step 6: Workspace-wide regression on the analyser layer.**

Run: `cargo test --workspace -p ailang-check`

Expected: all green. If any test fires (likely a `use-after-consume`
case that previously triggered on a binder passed twice into an
effect-op), inspect: the test's old behaviour was wrong (effect-ops
do not consume), and the test should be retired or updated. Do not
revert Steps 2-4.

---

### Task 2: int_to_str / float_to_str ret_mode Implicit → Own

**Files:**
- Modify: `crates/ailang-check/src/builtins.rs:193-202` (float_to_str)
- Modify: `crates/ailang-check/src/builtins.rs:203-212` (int_to_str)
- Modify: `crates/ailang-codegen/src/synth.rs:167-172` (float_to_str synth)
- Modify: `crates/ailang-codegen/src/synth.rs:174-180` (int_to_str synth)

Four lockstep edits. The checker side and the codegen-synth side
must agree byte-for-byte on each builtin's `Type::Fn`.

- [ ] **Step 1: Flip builtins.rs float_to_str ret_mode.**

In `crates/ailang-check/src/builtins.rs`, at the `float_to_str`
`env.globals.insert` near line 193, change:

```rust
ret_mode: ailang_core::ast::ParamMode::Implicit,
```

to:

```rust
ret_mode: ailang_core::ast::ParamMode::Own,
```

(The literal sits at line 200 inside the surrounding insert block at
lines 193-202.)

- [ ] **Step 2: Flip builtins.rs int_to_str ret_mode.**

In `crates/ailang-check/src/builtins.rs`, at the `int_to_str`
`env.globals.insert` near line 203, change the `ret_mode: Implicit`
literal (line 210) to `ret_mode: Own` in the same shape as Step 1.

- [ ] **Step 3: Flip synth.rs float_to_str ret_mode.**

In `crates/ailang-codegen/src/synth.rs`, at the `"float_to_str"` arm
near line 167, change the `ret_mode: ParamMode::Implicit` literal
(line 172) to `ret_mode: ParamMode::Own`.

- [ ] **Step 4: Flip synth.rs int_to_str ret_mode.**

In `crates/ailang-codegen/src/synth.rs`, at the `"int_to_str"` arm
near line 174, change the `ret_mode: ParamMode::Implicit` literal
(line 179) to `ret_mode: ParamMode::Own`.

- [ ] **Step 5: Workspace build to confirm symmetry.**

Run: `cargo build --workspace`

Expected: clean build. If a divergence between the two layers exists
(e.g. one site flipped but not its partner), the type-replay machinery
at the codegen-side fires an `internal: type mismatch` error at any
fixture that exercises int_to_str / float_to_str.

- [ ] **Step 6: Confirm the two RED tests now report a different shape.**

Run: `cargo test --workspace -p ail --test e2e int_to_str_drop_balances_rc_stats`

Expected: still FAILS, but now likely on a LINK error or a wrong
drop-fn symbol — because the let-binder is now trackable
(`is_rc_heap_allocated` succeeds on `ret_mode == Own`), but
`drop_symbol_for_binder`'s App arm currently emits `drop_<m>_Str`
which is undefined. This is the gap Task 3 closes; observe and
move on.

(If the test now fails for a different reason — e.g. compile error,
or unexpected stdout — stop and investigate. The expected failure
shape is link-time / runtime "undefined symbol drop_<m>_Str" or a
similar drop-fn-not-found.)

---

### Task 3: drop_symbol_for_binder App arm gets Str carve-out

**Files:**
- Modify: `crates/ailang-codegen/src/drop.rs:534-549`

- [ ] **Step 1: Read the current App arm.**

`crates/ailang-codegen/src/drop.rs:534-549`:

```rust
Term::App { .. } => {
    if let Ok(ret_ty) = self.synth_arg_type(value) {
        if let Type::Con { name, .. } = ret_ty {
            if name.matches('.').count() == 1 {
                let (prefix, suffix) =
                    name.split_once('.').expect("checked");
                if let Some(target) = self.import_map.get(prefix) {
                    return format!("drop_{target}_{suffix}");
                }
                return format!("drop_{prefix}_{suffix}");
            }
            return format!("drop_{m}_{name}", m = self.module_name);
        }
    }
    "ailang_rc_dec".to_string()
}
```

The unqualified-name path at the inner `return format!("drop_{m}_{name}")`
generates `drop_<current_module>_Str` for `name == "Str"`, which is
undefined.

- [ ] **Step 2: Insert the Str carve-out before the unqualified-name return.**

Change the `Type::Con` body to special-case `Str` before the qualified
/ unqualified routing. The cleanest shape mirrors `field_drop_call`'s
Str arm at `drop.rs:392-394`:

```rust
Term::App { .. } => {
    if let Ok(ret_ty) = self.synth_arg_type(value) {
        if let Type::Con { name, .. } = ret_ty {
            // Symmetric to `field_drop_call`'s Str arm: Str is a
            // built-in pointer type with no per-type drop fn. Both
            // heap-Str (rc_header at payload-8) and static-Str
            // (codegen-elision keeps static pointers out of this
            // path) consume via `ailang_rc_dec`.
            if name == "Str" {
                return "ailang_rc_dec".to_string();
            }
            if name.matches('.').count() == 1 {
                let (prefix, suffix) =
                    name.split_once('.').expect("checked");
                if let Some(target) = self.import_map.get(prefix) {
                    return format!("drop_{target}_{suffix}");
                }
                return format!("drop_{prefix}_{suffix}");
            }
            return format!("drop_{m}_{name}", m = self.module_name);
        }
    }
    "ailang_rc_dec".to_string()
}
```

- [ ] **Step 3: Build the codegen crate.**

Run: `cargo build -p ailang-codegen`

Expected: clean build.

---

### Task 4: Verify existing RED tests flip to GREEN

**Files:** none modified — this task is observational.

After Tasks 1-3, the two pre-existing RED tests at
`crates/ail/tests/e2e.rs:2601, :2617` should pass with strict
`allocs == frees && live == 0` invariants.

- [ ] **Step 1: Run the two target tests.**

Run: `cargo test --workspace -p ail --test e2e int_to_str_drop_balances_rc_stats str_field_in_adt_drops_heap_str_correctly`

Expected: both PASS. Concrete numbers:
- `int_to_str_drop_balances_rc_stats`: `allocs == 1, frees == 1, live == 0`, stdout `"42\n"`.
- `str_field_in_adt_drops_heap_str_correctly`: `allocs == 2, frees == 2, live == 0`, stdout `"42\n"`.

If either is still RED, stop and inspect. The most likely failure
modes:
- One of Tasks 1-3 was not fully applied (re-check files).
- The two analyser-walkers diverged (Task 1 only flipped uniqueness,
  not linearity, or vice versa).
- A pattern-binder-drop interaction in `match_lower.rs:740-848`
  fires a double-free under the new rule. Trace via `ail emit-ir`
  on the failing fixture.

- [ ] **Step 2: Full e2e regression.**

Run: `cargo test --workspace -p ail --test e2e`

Expected: every test PASS. If any other E2E fires (a fixture whose
behaviour relied on the old Consume semantics), inspect — likely a
fixture where a let-bound pointer was previously NOT freed because
it was double-counted as consumed-by-effect-op, and is now freed
correctly. Such tests need re-baselining, not reversion of Tasks 1-3.

---

### Task 5: Two new positive tests + fixtures

**Files:**
- Create: `examples/int_to_print_int_borrow.ail.json`
- Create: `examples/heap_str_repeated_print_borrow.ail.json`
- Modify: `crates/ail/tests/e2e.rs` (append two tests near line 2624)

- [ ] **Step 1: Write the primitive-Int fixture.**

Create `examples/int_to_print_int_borrow.ail.json`:

```json
{
  "schema": "ailang/v0",
  "name": "int_to_print_int_borrow",
  "imports": [],
  "defs": [
    {
      "kind": "fn",
      "name": "main",
      "type": {
        "k": "fn",
        "params": [],
        "ret": { "k": "con", "name": "Unit" },
        "effects": ["IO"]
      },
      "params": [],
      "doc": "Iter eob.1: primitive Int passed to io/print_int. The rule that Term::Do args are Borrow has no observable RC effect here because Int is unboxed; the test pins that no spurious bookkeeping appears (allocs == 0, frees == 0, live == 0).",
      "body": {
        "t": "let",
        "name": "n",
        "value": { "t": "lit", "lit": { "kind": "int", "value": 7 } },
        "body": {
          "t": "do",
          "op": "io/print_int",
          "args": [{ "t": "var", "name": "n" }]
        }
      }
    }
  ]
}
```

- [ ] **Step 2: Write the repeated-Str-borrow fixture.**

Create `examples/heap_str_repeated_print_borrow.ail.json`:

```json
{
  "schema": "ailang/v0",
  "name": "heap_str_repeated_print_borrow",
  "imports": [],
  "defs": [
    {
      "kind": "fn",
      "name": "main",
      "type": {
        "k": "fn",
        "params": [],
        "ret": { "k": "con", "name": "Unit" },
        "effects": ["IO"]
      },
      "params": [],
      "doc": "Iter eob.1: heap-Str passed to io/print_str twice in sequence. Under the new rule (Term::Do args = Borrow), the second call no longer triggers use-after-consume; the linearity check accepts the program. Under --alloc=rc + AILANG_RC_STATS=1 the slab allocates once and is freed once at scope close (allocs == 1, frees == 1, live == 0).",
      "body": {
        "t": "let",
        "name": "s",
        "value": {
          "t": "app",
          "fn": { "t": "var", "name": "int_to_str" },
          "args": [{ "t": "lit", "lit": { "kind": "int", "value": 42 } }]
        },
        "body": {
          "t": "seq",
          "lhs": {
            "t": "do",
            "op": "io/print_str",
            "args": [{ "t": "var", "name": "s" }]
          },
          "rhs": {
            "t": "do",
            "op": "io/print_str",
            "args": [{ "t": "var", "name": "s" }]
          }
        }
      }
    }
  ]
}
```

- [ ] **Step 3: Append the two e2e tests.**

In `crates/ail/tests/e2e.rs`, append after the existing
`str_field_in_adt_drops_heap_str_correctly` test (currently the file
ends at line 2624):

```rust
/// Iter eob.1: primitive-Int arg passed to an effect-op. Under the
/// new "Term::Do args = Borrow" rule, the let-binder `n` is not
/// consumed by `io/print_int`; but Int is unboxed, so there is no
/// pointer to RC-track. Pin: zero allocs / zero frees / zero live —
/// the rule introduces no spurious bookkeeping on primitives.
#[test]
fn int_arg_to_effect_op_does_not_rc_track() {
    let (stdout, allocs, frees, live) =
        build_and_run_with_rc_stats("int_to_print_int_borrow.ail.json");
    assert_eq!(stdout, "7\n");
    assert_eq!(allocs, 0, "Int arg should not trigger any RC alloc; got allocs={allocs}");
    assert_eq!(frees, 0, "Int arg should not trigger any RC free; got frees={frees}");
    assert_eq!(live, 0, "no leaked RC slabs allowed; live={live}");
}

/// Iter eob.1: heap-Str let-binder consumed by two `io/print_str`
/// calls in sequence. Pins the linearity-side consequence of the new
/// rule: under the old Position::Consume walk for Term::Do args, the
/// second print would have triggered `use-after-consume`. Under the
/// new Position::Borrow walk, both calls are borrows and the program
/// typechecks. Under --alloc=rc the slab is allocated once by
/// int_to_str, lives through both prints, and is freed exactly once
/// at scope close — allocs == 1, frees == 1, live == 0.
#[test]
fn heap_str_repeated_print_balances_rc_stats() {
    let (stdout, allocs, frees, live) =
        build_and_run_with_rc_stats("heap_str_repeated_print_borrow.ail.json");
    assert_eq!(stdout, "42\n42\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}");
}
```

- [ ] **Step 4: Run the two new tests.**

Run: `cargo test --workspace -p ail --test e2e int_arg_to_effect_op_does_not_rc_track heap_str_repeated_print_balances_rc_stats`

Expected: both PASS.

If `heap_str_repeated_print_balances_rc_stats` fails with the wrong
allocs/frees numbers, the most likely cause is that one of the two
analyser walkers in Task 1 was not flipped — the linearity walker
would still reject the second print as `use-after-consume`, and the
program would not typecheck.

---

### Task 6: DESIGN.md anchor for both arg-position rules

**Files:**
- Modify: `docs/DESIGN.md` (under Decision 10)

The spec mandates anchoring `Term::Do.args[*] = Borrow`. The existing
symmetric Ctor rule (`Term::Ctor.args[*] = Consume`) is documented
only in `crates/ailang-check/src/linearity.rs:42`. The Boss decision
recorded at brainstorm-close is: anchor BOTH rules together to avoid
codifying asymmetry in DESIGN.md.

- [ ] **Step 1: Locate Decision 10's body.**

Run: `grep -n "Decision 10\|RC + uniqueness" /home/brummel/dev/ailang/docs/DESIGN.md | head -5`

Expected: a line near or after the canonical Decision 10 header (a
bullet such as "Decision 10: RC + uniqueness inference" or similar).
Read the surrounding section to find the right anchor location —
typically near the existing param-mode / borrow-mode discussion.

- [ ] **Step 2: Append the arg-position-table subsection.**

Under Decision 10, add a small subsection that names both rules:

```markdown
#### Arg-position policy for compound AST nodes

The uniqueness and linearity passes walk arguments of compound
nodes with a fixed Position policy. For ownership-bearing nodes:

| Node              | Arg position | Reason                                                                |
|-------------------|--------------|----------------------------------------------------------------------|
| `Term::Ctor.args[*]` | Consume   | constructor packs values into the cell; the cell owns them afterwards |
| `Term::Do.args[*]`   | Borrow    | effect-op observes its arguments; the caller still owns whatever pointer it passed in |

The two policies are language rules, not per-op annotations. They
do not appear as fields on `EffectOpSig` or `Ctor`; the AST node
kind itself carries the default. The walkers that read this policy
live at `crates/ailang-check/src/uniqueness.rs` and
`crates/ailang-check/src/linearity.rs` (matched arms in both).
```

The exact wording / placement is a Boss judgement call — adapt if
Decision 10's existing structure suggests a better fit. The
non-negotiable elements: both rules are named together, both as
language rules not per-op fields, with code-location references.

- [ ] **Step 3: Verify DESIGN.md still validates structurally.**

Run: `cargo test --workspace`

Expected: any DESIGN-md-shape tests (if present) stay green. The
contents of DESIGN.md are not parsed by the toolchain; this is just
a final regression safety net.

---

### Task 7: WhatsNew.md entry + roadmap close

**Files:**
- Modify: `docs/WhatsNew.md` (append at bottom)
- Modify: `docs/roadmap.md:41-56` (close Heap-Str ABI entry)

- [ ] **Step 1: Append a WhatsNew entry.**

In `docs/WhatsNew.md`, append at the end (newest at bottom per
chronological convention):

```markdown
## 2026-05-12 — Strings produced at runtime now release cleanly

`int_to_str`, `float_to_str`, and similar built-in primitives that
produce a freshly allocated string at runtime now participate in
reference counting like every other heap value. A string passed
into a print call is now treated as borrowed, not consumed, so
it is freed exactly once when it leaves scope. Earlier programs
that converted a number to a string and printed it leaked the
string buffer at program exit; that no longer happens.

A side effect: a function parameter declared `(own T)` whose only
in-body use was passing it into a print call will now correctly
be flagged as over-strict — that annotation should be relaxed to
`(borrow T)` (or removed). No current example programs are
affected.
```

(Exact prose may shift slightly; the constraint is: no internal
identifiers, no iter codes, lead with the user-visible change.)

- [ ] **Step 2: Close the Heap-Str ABI roadmap entry.**

In `docs/roadmap.md` at the P1 milestone bullet (lines 41-56),
check off the entry:

Change `- [ ] **\[milestone\]** Heap-`Str` ABI — ...`
to    `- [x] **\[milestone\]** Heap-`Str` ABI — ...`

Per roadmap convention, a finished entry may stay briefly with
the `[x]` marker before being removed. For this iter, leave the
`[x]` line in place; the Boss may remove it during commit-shape
or in a follow-up edit once it stops being load-bearing context.

- [ ] **Step 3: Update the dependent `Post-22 Prelude` entry's depends-on.**

Run: `grep -n 'depends on: Heap' /home/brummel/dev/ailang/docs/roadmap.md`

For each match (recon found at least one at `:69`), update the
`depends on:` line to reflect that the dependency has shipped —
either:
- Remove the `depends on:` line entirely (preferred if no other
  dependency remains), or
- Replace with `depends on: <something>` if another live
  dependency exists.

The Post-22 Prelude entry has only the Heap-Str dependency; remove
the line.

- [ ] **Step 4: Final full-workspace regression.**

Run: `cargo test --workspace && bench/cross_lang.py && bench/compile_check.py && bench/check.py`

Expected: every gate green. If any bench script fails on a fixture
whose RC trace shifted (a previously-leaking program now reaches
`live == 0`), update the baseline in the same iter — it is the
intended consequence of the milestone.
