Who Frees What in Emitted Code (internals)

This guide is for contributors who change how the compiler allocates or releases memory in direct-style emitted C, and for anyone reading a LeakSanitizer report against a tur build binary. It describes the code as it stands.

Out of scope, with where to go instead:

• CPS-lowered functions and the DK machine (the reap list, early hand-backs, continuation copies): cps-dk-internals-guide.md.
• Regions (with-region, the escape note, rewind vs retire): regions-internals-guide.md and gc-guide.md.
• The rc runtime and the cycle collector themselves: gc-guide.md.
• Which ownership strategy a library should pick: ownership-guide.md.
• What each feature costs in bytes: memory-usage-guide.md.
• The interpreter, which reclaims by pool and sweep, not by drop: turi-interpreter-internals-guide.md.

Trust the code over the header comments. Comments in this area name the report that introduced each rule, and many still describe the state just before a later fix (an archived report calls the spine drop drop_recspine_<T>; the emitted name is drop_localowned_<T>). Where a comment and this guide disagree, read the code. If the code disagrees with this guide, fix the guide.

---

The short version

1. There is no general "drop at scope exit" pass. Each heap shape has its own owner rule, decided either by the elaborator (which injects a defer into the let body) or by the emitter (which writes a trailing free after the let body). Anything no rule claims leaks.
2. Every rule's polarity is "prove it, or leak". A wrong "owned" is a use-after-free or double free; a missed one is a leak. So every predicate only ever greenlights a free, and refusal is the default.
3. Drop glue (drop_glue_tur_adt_<T>) exists only for types that needs_drop_glue. Having it makes the type move-only, and that move discipline is what makes a single owner -- and so a free -- sound.
4. By-value recursive spines are freed at three points: the owning local's scope exit, right after a lend of a fresh temporary, and inside a consuming callee (own-discharge, shallow or deep). A whole-program provenance analysis decides which values own their spine.
5. Trailing frees are trailing. A return, throw or panic that leaves the scope early skips them -- and, today, skips the elaborator's injected drops too (see Early exits). The tail path is handled separately (The tail path).
6. Fixture programs are not leak-checked by tests/run.sh. Opt a fixture into tests/run-leak-check.sh with a requires.leak-check marker.

---

Source map

---

The ownership model

The emitter has no ownership type. It works from four facts the elaborator leaves on each Binding and function, plus one analysis of its own.

Owned, lent, borrowed

Function results are owned by the caller. That is a convention the elaborator enforces where it can: elab_own_byval_copy clones the rc fields of a by-value product copied out of a shared view (a ^borrow, a global, a container element, or a match binder of one) where it becomes an owner, and rejects one holding a borrowed ref field with TUR-E0108.

How moves are tracked

Binding carries the state (src/compiler/expr.h):

• is_moved -- the static poison the move checker reads (TUR-E0201 on a later use). Set by both of the next two.
• moved_owning -- set by binding_mark_moved. Sticky: it is never rolled back with the per-branch move-state snapshots, so a lend in one arm and a real move in the other reads as moved.
• lent_to_nonretaining -- set by binding_mark_lent when the callee's mask says it keeps nothing. The binding is poisoned exactly as by a move, but the scope-exit drop still fires.
• is_binding_consumed(body, b) -- not a flag but a walk: an explicit (rc/drop b), (drop! b) or (ref/from-rc b) anywhere in the body. It suppresses the auto-drop on every path, including paths that do not consume (see Declined shapes).
• binding_moved_during_init[k] -- a local moved by a later sibling initializer of the same let.

The drop decisions read these; the type checker reads only is_moved.

Parameters: ^borrow and the inferred masks

A ^borrow parameter (Binding.is_borrow) is never owned by the callee: the callee frees nothing it is handed. For an unannotated parameter the elaborator infers, per function, whether the body can keep it. The answer is a bitmask on the function's binding:

Bits past 31 are left unset (no free). A body with inline C gets no bits in the sum mask: a C body can stash the pointer.

Ownership provenance (by-value recursive ADTs)

For the spine-owning types (below), the elaborator's flags are not enough: a by-value copy out of a ^borrow, a global or vec-get shares its boxes with an owner that will free them. So emit_core.c:own_compute runs a whole-program greatest fixed point before either spine consumer frees anything. A value is owned when it is:

• a constructor call whose recursive-type arguments are owned;
• a let-local or match binder proven owned (binders inherit from an owned scrutinee), or a parameter every caller passes owned (OwnFn.owned);
• the result of a direct call to a function whose every returned value is owned (OwnFn.fresh);
• an if / match / do / let whose value positions are all owned.

Everything starts assumed. A function is knocked out of owned when its address is taken (EX_VAR of the function), and never gets it when it is external: an instance method, a C export, a #[used] defn, a lifted lambda, main, or an exported function under separate compilation. If the fixed point does not settle in 64 rounds, nothing is claimed. The walk enumerates operands through cps_visit_children, so a new expression kind is not silently skipped.

The design history, including the use-after-free that made the analysis necessary, is in byvalue-recursive-adt-boxes-are-never-freed.

---

Two families of release

Every scope-exit release is one of two kinds, and they behave differently on an early exit.

Elaborator-injected defers. elab_let (elab_forms.c) appends EX_DEFER items, flagged is_drop_glue, to the end of the let body's do:

Each is skipped when the local is moved, moved during init, or consumed.

Emitter trailing frees. emit_expr.c:emit_let_value collects, per binding, the frees that need the binding's emitted C type to decide, and writes them after the body, in this order:

The last two flags are set by the elaborator but emitted here, not as defers, so that a CPS-colored function stays admissible: a defer reading a fat-fn field is a continuation-capture shape the CPS backend refuses. CPS-lowered functions never run emit_let_value, so these frees do not happen there.

---

Drop glue

What makes a type need it

AdtDef.needs_drop_glue is set in elab_structs.c when some constructor field is:

needs_drop_glue makes the type move-only. That is the soundness line for :copy: under :copy, (let [t (Cons 3 (Nil)) a (Cons 1 t) b (Cons 2 t)] ...) compiles and two boxes carry the same tail pointer, so a per-spine free would free it twice. :copy recursive types therefore get no glue and leak per value; the answer for them is a region bracket.

What gets emitted

emit_module.c:emit_adt_byval_drop_glue writes, for each such type:

Per field, emit_adt_glue_field_drops releases in reverse field order:

A multi-constructor type switches on s->tag and releases only the live variant's fields. For (defdata Lst [] (Cons [hd : int tl : Lst]) (Nil)) the glue is (from tur emit-c, trimmed):

static void drop_glue_tur_adt_Lst(void *ptr) {
    if (!ptr) return;
    tur_adt_Lst *s = (tur_adt_Lst *)ptr;
    switch (s->tag) {
    case 0:
    if (s->as.Cons._1) drop_glue_tur_adt_Lst((void *)(intptr_t)s->as.Cons._1);
        break;
    case 1:
        break;
    }
    tur_region_free(ptr);
}

The boxed-fn arm. A capturing closure is allocated with an 8-byte header and its handle points past it (see Closure environments), so a fn field is released with TUR_CLOSURE_DROP, never a bare free -- in drop_fnfields_<T> and in emit_adt_glue_field_drops alike. The latter emitted a bare free until 2026-10-17, so rc/of of such a struct, or a recursive ADT with a fn field going out of scope, aborted with free(): invalid pointer (adt-fn-field-drop-glue-bare-free; pinned by closure-field-drop-glue-rc-struct and closure-field-drop-glue-defdata).

Regions vs drop glue

A node is allocated with tur_region_alloc_or_malloc and released with region_free_fn(), which is tur_region_free by default and free under TUR_REGIONS=0. tur_region_free refuses region memory (a process-wide registry says who owns a word), so drop glue is safe to run on a node built inside a bracket. A :heap node has no glue at all: outside a region it lives until exit; inside one it goes at the rewind. See regions-internals-guide.md.

---

By-value recursive spines

A by-value recursive ADT (or one with an any field) is a stack value whose recursive field holds a pointer to a heap copy of the next link: a by-value product cannot ride the int64 carrier and cannot contain itself inline. The types in scope are exactly emit_own_adt_of / elab_byval_localowned_adt: by-value, non-generic, needs_drop_glue, with a self-recursive or any field. Their spine is freed at one of three points.

1. Scope exit of the owning local

elab_let sets Binding.drops_local_owned when the local:

• was not moved for real (is_moved && !(lent_to_nonretaining && !moved_owning)),
• was not moved during init and is not consumed, and
• is confined: localowned_binding_is_confined walks every match binder and field read rooted at the local as an alias, and refuses if any alias reaches a store, a closure, a let, a retaining callee, or the scope's value (unless that value is a non-pointer scalar).

emit_let_value then also asks emit_own_binding_owned. Both must agree.

2. A lent temporary

(llen (build 3)) hands a fresh spine straight to a non-retaining parameter. No local names it, so emit_core.c:emit_call_arg_temp_is_lent_fresh_spine spills it to a temp and queues it on the vsp_pending channel, drained after the call as drop_localowned_tur_adt_<T>((void *)&__tN); /* lent temporary: nothing else owns it */. It requires a static, non-tail call, a non-pointer scalar result, and an owned argument.

3. Own-discharge in a consuming callee

A callee that returns part of its argument cannot be non-retaining, so the caller moves the spine into it for real. The callee then frees what it did not pass on. emit_own_match_discharges admits a match when:

• the scrutinee is a parameter, and emit_own_param_owned says every caller passes it owned;
• the match is on the body's straight-line spine (own_on_spine: evaluated once per call, as the body's value);
• the parameter is used exactly once (own_uses == 1);
• the match is not being emitted on the tail path (emit_match_in_tail);
• TUR_NO_OWN_DISCHARGE is unset in the compiler's environment.

Then, after each arm computes its value, emit_own_arm_discharges decides per recursive field (emit_own_arm_field_discharge):

The parameter's own storage is the caller's (a by-value ADT argument is passed as const T *) and is never touched. For (defn tail [xs : Lst] : Lst (match xs (Cons h t) t (Nil) (Nil))) the Cons arm emits (trimmed):

case 0: {
    const tur_adt_Lst *t_11 = (const tur_adt_Lst *)(intptr_t)(__scrut->as.Cons._1);
    __t202 = *(t_11);
    tur_region_free((void *)(intptr_t)__scrut->as.Cons._1);  /* moved out: free its box */
    break;
}

A move into a tail call is declined because a free after the call costs the C compiler the jump a recursive walker relies on.

What still leaks -- a consuming callee reached through a borrow, and spines in a container -- is byvalue-recursive-shared-copies-leak.

---

Scope-exit frees in detail

Early exits

emit_let_value checks expr_contains_return_or_throw(body) first. When the body can leave early, it collects no trailing frees except any drops, which it also pushes on the any_scope_drops channel so every return inside the body fires them. Every other trailing free is a leak on that path, never a use-after-free. The emitted if (tur_panicking) return ...; after each call skips them as well.

The injected defers are covered on a return. emit_do_value registers a defer with tur_frame_push_defer when control reaches it, and the auto-drops (is_drop_glue) sit after the body's value, so the frame chain an early return fires does not hold them yet. Each do-emitter (emit_do_value, emit_stmt's EX_DO arm, emit_tail_drop_hoist_do) therefore notes its trailing drop-glue run against its frame (emit_frame_note_pending_drops) while it emits the items ahead of it, and clears the note once it pushes them. The return emitter computes its value first, fires the frame chain, then emits every noted drop along that chain inline, innermost first (emit_frame_run_pending_drops) -- except a binding the value moves out, so (return x) on an owned rc still hands it over. The note is keyed by frame, so a lambda body, which starts with no frame, never sees its enclosing function's. Pinned by ref-auto-drop-early-return (leak-checked) and rc-auto-drop-early-return (gc-live-blocks around the calls).

The tail path

A let on the tail path of a function with a backedge is emitted by emit_tail's inline arm, which has no trailing code. tco_let_refusal (emit_fns.c) admits a binding that let_binding_may_need_scope_free only when every use of it is a plain scalar read (tco_drop_use_ok); its release is then pushed onto the any drop channel (let_binding_push_scope_frees) and fires at the backedge or return, after the arguments are in temps. Otherwise the let leaves the tail grammar (TC_LET_DROP).

A body with injected drop-glue defers keeps a tail position only for a backedge, and only when tco_drop_glue_refusal finds the captured locals dead at the call (TC_DROP_LIVE) and no return sharing the block (TC_DROP_EXIT). A non-self call under an open frame is not a C tail call.

Declined shapes

These are deliberate leaks, not oversights. Each is a place where the free could be wrong.

---

Closure environments

Layout

Every capturing closure is a heap block with an 8-byte drop-glue header (emit_expr.c, the EX_CLOSURE arm):

void *__t204 = malloc(sizeof(void *) + sizeof(struct __env_12));
*(void (**)(void *))__t204 = drop_glue___env_12;
struct __env_12 *__t203 = (struct __env_12 *)((char *)__t204 + sizeof(void *));
__t203->__fn = (tur_thunk_int64_t_int64_t_t)__fn_10;
__t203->k = k;

The handle is the pointer past the header, so dispatch (TUR_CLOSURE_FN, TUR_APPLYn) reads __fn at offset 0. Never free a closure handle. Release it with TUR_CLOSURE_DROP(h), i.e. tur_closure_drop, which reads env[-1] and calls the glue (or frees the base when the slot is NULL).

drop_glue_<env> is emitted twice in lockstep -- emit_fns.c (the authoritative pre-pass) and emit_expr.c:emit_closure_env_struct_and_glue -- and releases, in reverse capture order:

• an rc capture: rc_strong_decrement + drain (the env fill retained it);
• an owned ^fat capture: TUR_CLOSURE_DROP (the capture was moved in), except a letrec self-capture;
• a capture whose type has a Drop instance: that instance's drop;

then frees the base. Other owning captures (a raw nested closure, a ref) are not walked: recursing blind would double-free a capture another owner also drops.

When an env is freed

The {shim, orig} fat box a bare named defn is wrapped in is allocated once at file scope; per-call shim boxes are the subject of fn-param-at-type-variable-slot-boxed-per-call. Which fn representation crosses which boundary is in value-representations-guide.md. The design history is closure-drop-glue-plan.

---

Boxes

Three rules carry most of the weight:

1. A declared Option/Result result from inline C is a transfer. The body must return a fresh box. A borrowed box needs a borrow-shaped signature: vec-get [A] (v : (Vec A)) : A returns an element box the vector owns, and (:: (vec-get v 0) (Option int)) is still a borrow. Keying on the call's resolved type instead of the declaration is a double free. See inline-c-results-guide.md.
2. Boxing and freeing ask one predicate. The element push bridge, the read-back, and the ownership folds all call type_is_boxed_container_elem (itself repr_of's answer), so they cannot drift. When they did, (Vec (Option int)) leaked a box per push.
3. __tur_any_drop reads the minting TU's registry row, not a local switch, so it frees only boxes a widen allocated -- across modules too.

---

rc<T> and weak<T>, from the emitter's side

The mechanics are in gc-guide.md; this is what the emitter writes and what to watch for.

• rc/of allocates the payload and a control block (rc_cb_alloc, or rc_cb_alloc_struct with the type's drop_glue_ and walk_glue_ for a struct with owning fields).
• rc/drop is rc_strong_decrement(cb); rc_free_queue_drain();. rc/clone is rc_strong_increment(cb);. src/passes/rc_elision.c marks a last-use clone and its matching drop elide; the emitter then writes a comment instead of either call.
• A local rc<T> gets the injected (defer (rc/drop b)); a set! on it releases the overwritten value (elab_set_rc_release), gated on exactly the auto-drop predicate.
• A let initialized from a bare rc field read is wrapped in EX_RC_CLONE, because the source still owns that field.
• A weak<T> in a struct field is released by the owner's glue; in a local it is not.

LeakSanitizer cannot see an rc leak. Every control block is reachable from the collector's registry, so a leaked rc block reads as live. Count instead: (gc-live-blocks) before and after the shape.

---

Workflow: confirm and pin a leak

1. Reproduce it outside the suite

tests/run.sh builds fixture programs without sanitizers and runs them with detect_leaks=0 (test-suite-portability-guide.md). Build one program the way tests/run-leak-check.sh does:

TUR_RUNTIME=source \
TUR_CC_FLAGS="-O1 -g -std=c99 -Wall -fno-strict-aliasing -fsanitize=address -L./build/src" \
  ./build/tur build repro.tur -o /tmp/repro
ASAN_OPTIONS="detect_leaks=1:exitcode=23" \
LSAN_OPTIONS="use_stacks=0:use_registers=0" /tmp/repro

Every flag is there for a reason the harness records:

• TUR_CC_FLAGS replaces the default flags, so the -L must be restated.
• -O1, not -O2: -O2 inlines the allocation site out of the trace.
• TUR_RUNTIME=source compiles the runtime into the program. The prebuilt archive is not instrumented, so a use-after-free inside rc_strong_decrement passed the gate until this was added.
• use_stacks=0:use_registers=0: a stale pointer in a dead frame keeps a leaked block "reachable". The default roots hid 127 bytes across one sweep.
• exitcode=23 separates a leak from the program's own failure exit.

2. Read the report against the emitted C

The frames name C functions in /tmp/tur-build/<mangled-path>.c, at line numbers in that file. tur emit-c repro.tur > repro.c produces the same text, so read the allocation site there. The allocator in the top frame says what leaked:

"Direct leak" is the first unowned allocation; "Indirect leak" is what hangs off it. Fix the direct one first.

3. A/B the mechanism

• TUR_NO_OWN_DISCHARGE=1 ./build/tur build ... turns own-discharge off (read at compile time, in emit_own_match_discharges). On the tail example above it turns a clean run into a 24-byte, one-allocation leak.
• TUR_REGIONS=0 restores plain malloc/free for nodes. In a build tree with no libturi.a (the runtime is then compiled from source), it currently fails to link: hamt.c calls tur_region_note_escape, and emit_region_runtime_bodies embeds region.c only when regions are on. Build all targets first, or A/B with the archive.

4. Pin it

Add a fixture with a requires.leak-check marker; tests/run-leak-check.sh then requires both a clean LSan run and expected.stdout. If the leak is real and filed but not fixed, add a known-leak file whose first line names the open report: the gate prints KNOWN instead of FAIL. When the fix lands, the gate fails while the marker remains ("marked known-leak but ran clean"), so delete it in the same change. Four fixtures carry one today.

A clean run means "nothing was orphaned", not "nothing was retained". For retention -- rc blocks, DK reap entries -- count it.

---

Open leak reports, by mechanism

Check docs/reported/ for the current list.

By-value recursive spines

• byvalue-recursive-shared-copies-leak -- a spine reaching a consuming callee through a borrow, or held in a container.

Option/Result boxes

• carrier-sum-option-boxes-have-no-owner -- carrier cells behind consumers the compiler cannot see through (dictionary dispatch, HKT-constrained generics).
• sum-closure-payload-never-dropped -- a closure in an Option/Result local beyond the simplest shapes.

Closure envs and fn boxes

• async-capturing-body-env-never-freed -- a capturing async body's env in the shapes the spawn cannot own.
• fn-param-at-type-variable-slot-boxed-per-call -- a fn parameter boxed into a type-variable slot per call.

Structs on the carrier ABI

• cps-byvalue-struct-with-closure-field -- a defstruct with a defopaque field beside a closure field stays on the carrier ABI, and boxes per construction, until the CPS backend can take such a struct by value. (Without a closure field it is by value and leaks nothing: opaque-field-struct-box-never-freed, archived.)

Continuations (DK)

• effect-nontail-resume-copies-held-until-outer-entry -- retention, not a leak: copies held until the outermost entry returns.
• cloneable-cont-escaped-chain-leaks -- an escaped cloneable continuation's wrapper and chain.

Dynamic dialects

• saffron-static-ownership-residue -- any boxes no static owner reaches, with the Saffron collector off.

---

Reading the archive

Each rule above was added by one report. The ones that explain why a rule has the shape it has:

• byvalue-recursive-adt-boxes-are-never-freed -- spine drops, the :copy line, lends, own-discharge, provenance.
• closure-drop-glue-plan -- the env header, TUR_CLOSURE_DROP, non-retaining fn params.
• any-struct-box-leak-per-widen and any-widen-stored-in-an-adt-field-has-no-owner -- any drops and the deep __tur_any_drop.
• reclamation-plan -- RM1, the accessor-whitelist sum-cell drop.
• inline-c-option-carrier-box-leaks -- the inline-C transfer contract.
• value-struct-payload-sum-monomorph-box-has-no-owner and sum-payload-box-leaks-at-match -- payload boxes.
• mut-cell-is-never-freed, rc-of-sum-type-drops-no-glue, history/drop-glue-shallow-nested-owning-aggregate.

---

Bugs found while writing this guide

Each was reproduced against the compiler this guide describes and filed in docs/reported/. When one is fixed and archived, update the passage above that describes it and drop it from this list.

• regions-off-source-runtime-link-failure -- TUR_REGIONS=0 fails to link when the runtime comes from source

Maintenance

Update this guide in the same change when you:

• add a heap allocation site in emitted code -- it needs an owner rule here and a requires.leak-check fixture;
• add a let_binding_*_freeable predicate, an injected auto-drop, or a field kind to emit_adt_glue_field_drops;
• change what sets needs_drop_glue, drop_inner_def, or one of the ownership masks;
• change the closure env layout or tur_closure_drop;
• close or file a leak report listed above.

A new store into memory that outlives a region bracket also needs a TUR_REGION_NOTE (CLAUDE.md, "Region Store Hooks"). The emitted-C excerpts here come from tur emit-c; refresh them when the shape they show changes. Cite functions, not line numbers.