AILang/docs/specs/2026-05-18-embedding-abi-m3.md

Embedding ABI — M3: frozen value layout + single ADT/record crossing + RC ownership contract — Design Spec

Date: 2026-05-18 Status: Draft — awaiting user spec review Authors: Brummel (orchestrator) + Claude

Boss spec-consistency repair (2026-05-18, M3.1 implement BLOCKED adjudication — M2.1-precedent class). The M3.1 implement dispatch correctly BLOCKED on Task 5: the original §"Testing strategy" items 3/4 + §"Coherent stop" specified the proof instrument as "ailang_ctx_free reports allocs == frees", assuming the single ctx readback observes every RC op. That assumption is false by M2's shipped design: the ctx is bound to __ail_tls_ctx only for the duration of the synchronous forwarder call, so host-side ailang_rc_dec calls (which borrow mode legitimately requires every iteration, and own mode uses for the initial make_state + final return) are attributed to the g_rc_* atexit line, not the ctx line. The substantive invariant is sound and was empirically confirmed globally leak-free + value-correct for both modes (own: ctx live=0 + g_rc live=0; borrow: ctx live=+N + g_rc live=−N; both Σlive=0, exit 0). The proof model below is corrected to global leak-freedom (sum across all ailang_rc_stats: lines: Σallocs == Σfrees, equivalently Σlive=0, plus exit 0), for both modes — strictly stronger and honest about the M2-TLS cross-attribution (which is correct behaviour, not a leak). Spec-consistency repair, not a redesign: what M3 delivers is unchanged; no fresh grounding-check (this removes an over-strong measurement assumption and adds no new assumption about current compiler/checker/codegen behaviour).

Goal

Let a single-constructor record of Int/Float fields cross the embedding C boundary in and out, with the RC ownership-transfer contract at the call boundary specified, tested, and frozen. M1 made one scalar fn callable (@<sym>(scalars…)); M2 threaded a per-thread ailang_ctx_t* through it (@<sym>(ctx, scalars…)) and de-globalised RC accounting. Both M1 and M2 explicitly label that C signature scalar-only and provisional until M3 (DESIGN.md §"Embedding ABI", :2280, :2293–2295). M3 delivers the value crossing the arc exists for — the State of a (State, Sample) -> State streaming fold — and converts "provisional until M3" into a one-way freeze: from M3 on, the value/memory layout and the ownership rule are a stability promise an external host (M5's ail-embed adapter, data-server) compiles against and the compiler must not silently break.

M3 has no new authoring surface: no new Form-A modifier, no new schema field, no new CheckError variant. The .ail an LLM author writes is the direct, minimal evolution of the M1/M2 scalar kernel into a record State (existing data + existing (own (con T)) mode

• existing (export "…")). The deliverable is a widened export gate, a transparent record-as-ptr forwarder, a frozen layout documented as the single source of truth and pinned by a byte test, and an alloc==free proof harness. This is the M1/M2-style honest framing: a strategic capability/safety gate per the user-made direction call in the roadmap, not the standard authoring-utility metric. No pretence otherwise.

Coherent stop: the (State, Sample) -> State record fold is callable from a C host that constructs the input State via the runtime allocator, calls the kernel N times, reads and frees each returned State, and ailang_ctx_free reports allocs == frees — for both the (own (con State)) and the (borrow (con State)) declared modes, each behaving exactly as the declared mode promises; with the frozen layout pinned by a byte test that goes RED if codegen moves an offset, and every M1/M2-arc invariant audited.

Position in the M1–M5 arc (load-bearing — the freeze is here)

The arc is a one-way stability progression. M1 and M2 deliberately kept the value/ABI layout provisional and decoupled the author-chosen C symbol from the internal ail_<module>_<def> mangling, precisely so the internal calling convention could keep changing while the external symbol stayed stable. M3 is where the value layout itself stops moving:

• M3 freezes the record memory layout (8-byte refcount header at payload-8, an i64 constructor tag at offset 0, scalar fields i64-strided from offset 8) and the ownership rule (follows the declared own/borrow mode). After M3, an already-compiled host that hand-builds and reads a State per this layout must keep working across compiler changes — a recompiled AILang must not move those bytes or invert the free rule. runtime/rc.c:25–26 already anticipates exactly this: "The ABI defined here is stable … will not require runtime changes unless the layout itself shifts." M3 makes "unless the layout itself shifts" a closed door for the embedding-ABI record shape.
• M4 (sequence crossing via List) and M5 (ail-embed adapter + data-server wiring) bind against the M3-frozen layout. The freeze must therefore already carry the M2 ctx parameter shape — it does (M2 shipped it); M3 adds only the record value to the already-ctx-shaped, now-frozen ABI.
• The internal @ail_<module>_<fn> calling convention and the _adapter/_clos closure pair remain byte-unchanged (the M1 decision M2 preserved, preserved again): the forwarder is a transparent ptr pass-through; all mode-driven RC stays inside the internal fn. M3 freezes the external shape without touching the internal convention — exactly the decoupling M1 built for.

Architecture

Three layers change, in pipeline order. None of ailang-core, ailang-codegen, or runtime/ gains any data-server/finance knowledge or dependency (Invariant 1; audited at close). No ailang-core schema change, no Form-A surface change, no new CheckError variant (explicit contrast with M1; same as M2).

1. Check (ailang-check). The export-gate scalar predicate is_c_scalar (crates/ailang-check/src/lib.rs:1921–1924) widens to is_c_abi_type: a type is permitted at the embedding boundary iff it is a C scalar (Int/Float, bare Type::Con, the M1 rule) or a Type::Con resolving to a data definition with exactly one constructor whose every field type is itself a permitted C-ABI type (recursive, but M3 scope bottoms out at scalar fields — a record field that is itself a record is out of scope and rejected; that is M4's recursion to open). Multi- constructor sums, Str fields, List fields, and effectful exports stay RED. The two existing diagnostics (CheckError::ExportNonScalarSignature :453, ExportHasEffects :459) are reused; only their message text widens to name "a single-constructor record of Int/Float" as permitted and, for a rejected single-ctor record, to name the offending field and that nested/Str/List fields are a future (M4) layer rather than "unsupported". No new variant, no code()-registry (:712–713) change.

2. Codegen (ailang-codegen). The forwarder signature extraction fn_scalar_sig (crates/ailang-codegen/src/lib.rs:659–669) and the LLVM scalar mapper llvm_scalar (:673–678) widen so an M3 record type maps to ptr. The M2 forwarder body (:604–651 — leading ptr %ctx, __ail_tls_ctx save/store/ restore around the internal call) is byte-unchanged: a record parameter and a record return are each a single ptr (recon confirmed ADTs already cross as a bare ptr; there is no sret/byval/aggregate convention anywhere in codegen or runtime, and none is introduced). All RC behaviour stays inside the internal @ail_<module>_<fn>: the existing mode-driven machinery — Iter-B own-param drop-at-return (lib.rs:1287–1335), the match_lower.rs:651–657 scrutinee-Own arm-close dec, the drop.rs:445–490 synth_callee_ret_mode ret-mode trackability — already realises own (kernel consumes) vs borrow (kernel does not) for the internal fn. The forwarder inherits that transparently; it performs no RC op itself.

3. Docs + pins. DESIGN.md §"Embedding ABI" (:2266–2317) gains a frozen value-layout subsection that becomes the single source of truth for: the record memory layout (header/tag/fields, offsets and sizes), the host-construction contract (input records are allocated via ailang_rc_alloc, normative MUST), the host-free contract (ailang_rc_dec, leak-free because M3 fields are scalar — no child boxes — with the non-scalar case explicitly flagged as M4-additive), and the ownership rule (follows the declared own/borrow mode). The "scalar-only and provisional until M3" / "provisional until M3" wording (:2280, :2293–2295) becomes one-way-freeze language. A new layout byte-pin test asserts the offsets/sizes/tag-word as codegen emits them today; the three sites that currently encode the layout independently (runtime/rc.c:28–44 comment, match_lower.rs lower_ctor, drop.rs) gain a lockstep comment pointing at the DESIGN.md SSOT.

What is frozen (the permanent commitment, stated exactly)

For a single-constructor data T whose n fields are each Int or Float, a value of type T crossing the embedding C boundary is:

  payload pointer  p   (this is what the C ABI passes/returns — a bare `ptr`)
  p - 8 .. p        :  uint64_t  refcount header   (HEADER_SIZE = 8; rc.c:54-56)
  p + 0  .. p + 8   :  int64_t   constructor tag   (always written; 0 for the
                                                    single ctor — no elision)
  p + 8  .. p + 16  :  field 0   (int64_t for Int; IEEE-754 double bit-pattern
                                  in 8 bytes for Float, declaration order)
  p + 16 .. p + 24  :  field 1
  …                     (field i at p + 8 + i*8;  total box size = 8 + n*8)

Frozen rules, permanent from M3:

• Layout as above — the actual layout codegen emits today (match_lower.rs lower_ctor: size_bytes = 8 + n*8, tag at offset 0 written unconditionally, fields i64-strided from offset 8). Frozen as-is, tag word included — M3 does not elide the single-ctor tag (a hot-path codegen change touching every single-ctor ADT tree-wide for ABI cosmetics; rejected — see Out of scope).
• Construction (host → kernel input). The host MUST obtain an input record's storage from ailang_rc_alloc(8 + n*8) (an already-public runtime symbol; it returns the payload pointer with the refcount header pre-set to 1 and the payload zeroed — rc.c:144–159), then write the tag word (0) and the scalar fields at the frozen offsets. A raw host malloc is a host-side contract violation: own-consume and ailang_rc_dec both require the runtime's 8-byte refcount header at p-8 initialised to 1.
• Ownership follows the declared mode (no new rule — the existing DESIGN.md §"Mode metadata is load-bearing for codegen" contract, :1413–1508, as the C ABI): a (own (con T)) parameter transfers ownership into the kernel — the kernel/RC consumes it (the existing Iter-B drop-at-return path), the host must not touch or dec that pointer after the call. A (borrow (con T)) parameter is retained by the host — the kernel does not consume it, the host frees it with ailang_rc_dec after the call. The return value is always owned by the host: the host reads it and frees it with ailang_rc_dec.
• Free (host side). ailang_rc_dec(payload) — an already-public runtime symbol. Leak-free for an M3 record because every field is a scalar: ailang_rc_dec is header-only (it does not recurse into fields — rc.c:193–210), and an M3 record has no child boxes to recurse into. The frozen subsection states this scoping honestly and names the non-scalar case (records with boxed fields, M4) as requiring an additive mechanism then — not a contradiction of the freeze, an extension at a layer M3 does not cover.

Why the ownership contract is mechanically almost free

The roadmap's "RC ownership-transfer contract" is not new RC code. AILang already compiles own vs borrow into the internal @ail_<module>_<fn>: an own parameter that the body consumes is dropped before return by Iter-B (lib.rs:1287–1335); a borrow parameter is not. The forwarder calls that internal fn and passes the record ptr straight through. So "the C ABI ownership follows the declared mode" is true by construction the moment the forwarder is allowed to pass a record ptr — there is nothing to implement at the boundary beyond widening the type predicate. M3's real work is to specify, prove, and freeze that already-true behaviour, not to build it. (Recon's open question — fn_scalar_sig strips param_modes/ret_mode — is a non-issue for the forwarder: the forwarder needs no mode info because it does no RC; the modes are already baked into the internal fn it calls. The forwarder only needs to know a record maps to ptr.)

Concrete code shapes

The AILang program M3 delivers (headline — clause-1 evidence)

examples/embed_backtest_step_record.ail — the (State, Sample) -> State streaming fold the embedding boundary exists for, the direct minimal evolution of the M1/M2 scalar kernel into a record State (running accumulator + count — the natural shape of a streaming fold's state, the SMA-shaped kernel from the Stateful-islands motivation, now expressible because M3 lets State cross the boundary):

(module backtest

  (data State
    (ctor State (con Float) (con Int)))

  (fn step
    (export "backtest_step")
    (type
      (fn-type
        (params (own (con State)) (con Float))
        (ret (con State))))
    (params st sample)
    (body
      (match st
        (case (pat-ctor State acc n)
          (app State (app + acc sample) (app + n 1)))))))

No new Form-A modifier, no new schema field — exactly like M2. (data State (ctor State (con Float) (con Int))), (own (con State)), (con State), (match … (case (pat-ctor State acc n) …)), and (app State …) as the constructor application are all existing surface (grounded against examples/borrow_own_demo.ail, examples/box.ail, examples/embed_export_adt_ret_rejected.ail). Asked "make this AILang fold with real State callable from a Rust host", an LLM author writes exactly this — the worked .ail is the clause-1 evidence, not a prose assertion.

A second delivered fixture pins the borrow half of the frozen contract — examples/embed_backtest_step_record_borrow.ail, identical but (params (borrow (con State)) (con Float)): the kernel reads st without consuming it; the host retains and frees the input. This fixture exists so the "ownership follows the declared mode" freeze is proven in both directions, not asserted for one.

The changed C host (the actual M3 deliverable surface)

#include <stdint.h>
#include <assert.h>
#include <string.h>

typedef struct ailang_ctx ailang_ctx_t;
extern ailang_ctx_t *ailang_ctx_new(void);
extern void          ailang_ctx_free(ailang_ctx_t *);
extern void *ailang_rc_alloc(size_t);     /* runtime: header=1, payload zeroed */
extern void  ailang_rc_dec(void *);       /* runtime: header-only dec + free@0  */

/* @backtest_step(ailang_ctx_t*, State*, double sample) -> State*  — FROZEN at M3 */
extern void *backtest_step(ailang_ctx_t *ctx, void *st, double sample);

/* construct an input State per the frozen layout: {tag@0, Float acc@8, Int n@16} */
static void *make_state(double acc, int64_t n) {
    void *p = ailang_rc_alloc(8 + 2 * 8);            /* header=1 set by runtime  */
    *(int64_t *)((char *)p + 0)  = 0;                /* single-ctor tag = 0      */
    memcpy((char *)p + 8,  &acc, 8);                 /* Float field, double bits */
    *(int64_t *)((char *)p + 16) = n;                /* Int field                */
    return p;
}

int main(void) {
    ailang_ctx_t *ctx = ailang_ctx_new();
    void *st = make_state(0.0, 0);
    for (int i = 0; i < 1000000; i++) {
        void *next = backtest_step(ctx, st, (double)(i & 7));
        /* (own (con State)): the kernel consumed `st`. Do NOT touch/dec st.    */
        st = next;                                   /* return is host-owned    */
    }
    double acc; memcpy(&acc, (char *)st + 8, 8);
    int64_t n = *(int64_t *)((char *)st + 16);
    assert(n == 1000000);
    ailang_rc_dec(st);                               /* host frees the return    */
    ailang_ctx_free(ctx);                            /* AILANG_RC_STATS: allocs==frees */
    return 0;
}
/* cc host.c libbacktest.a libailang_rt.a -o t && AILANG_RC_STATS=1 ./t */

The borrow variant differs only in the loop body: the kernel does not consume st, so the host owns it and must ailang_rc_dec(st) before overwriting it with next (and the input of the next iteration is a freshly make_state'd record, or the returned one threaded as the new input — the fixture uses the returned one as the next input, so each iteration frees exactly the previous host-owned input). Both variants end at allocs == frees.

The must-fail axis (clause-3 discriminator — sharper, not removed)

examples/embed_export_adt_ret_rejected.ail is, today, the M1 must-fail fixture for "an ADT return is rejected" — but its Pair is single-constructor with two Int fields, i.e. exactly M3-shaped. Under M3 it would no longer be a valid must-fail. M3 therefore re-points it (and its asserting test) to an ADT that is genuinely still rejected, so the clause-3 teeth stay non-vacuous. The re-pointed fixture rejects on a multi-constructor sum and a non-scalar field — two independent reasons, the sharpened M3 boundary:

(module embed_export_adt_ret_rejected
  (data Reading
    (ctor Missing)
    (ctor Sample (con Int) (con Str)))        ; 2 ctors AND a Str field
  (fn f
    (export "f")
    (type
      (fn-type
        (params (con Int))
        (ret (con Reading))))
    (params n)
    (body (app Sample n "tick"))))

The body is trivially well-typed (n : Int, "tick" : Str match Sample's (con Int) (con Str)), so — exactly as the M1 spec took care to ensure — the only reason ail check fails is the export gate: Reading has two constructors and Sample has a Str field. Both rejection reasons are independent and the M3 boundary rejects on either.

Plus narrower single-reason must-fail fixtures isolating each clause (see Testing strategy): a single-ctor record with a Str field (scalar-field rule), a single-ctor record with a List field, a multi-ctor sum of all-scalar ctors (single-ctor rule), and the unchanged effectful export (ExportHasEffects). Each fails ail check with a precise, self-correcting diagnostic; the positive single-ctor Float+Int fixture passes.

Implementation shape (secondary — supporting, not the point)

Check gate, crates/ailang-check/src/lib.rs:1921 (schematic — exact bytes are the planner's job):

before (M1/M2):
  fn is_c_scalar(t: &Type) -> bool {
      matches!(t, Type::Con { name, args }
          if args.is_empty() && (name == "Int" || name == "Float"))
  }

after (M3):
  fn is_c_abi_type(t: &Type, /* type-def lookup */ …) -> Result<(), Reason> {
      // C scalar (M1 rule) → ok
      // Type::Con resolving to a data def with exactly 1 ctor
      //   whose every field is_c_abi_type (M3: fields bottom out at
      //   Int/Float — a record-typed field is rejected, that is M4)
      //   → ok
      // else → Err(reason: multi-ctor | non-scalar-field | …)
  }
  // gate (lib.rs:1925-1940): param/ret loop unchanged in shape,
  //   calls is_c_abi_type; on Err emits the *reused*
  //   CheckError::ExportNonScalarSignature with the widened message.
  // effect check (lib.rs:1941-1946): unchanged.

Codegen forwarder signature extraction, crates/ailang-codegen/src/lib.rs:659 / :673:

before (M1/M2):  llvm_scalar(t): Float -> "double", else -> "i64"
                 fn_scalar_sig matches flat Type::Fn/Forall, scalars only

after (M3):      a record type (Type::Con → single-ctor data) -> "ptr"
                 scalars unchanged. fn_scalar_sig accepts a record
                 param/ret as "ptr". The forwarder body (lib.rs:604-651)
                 is BYTE-UNCHANGED — it already emits
                   define {ret} @sym(ptr %ctx, {params}) { … }
                 with {ret}/{params} now possibly "ptr"; the internal
                   call ptr @ail_<mod>_<fn>(...) and the TLS
                   save/store/restore are identical to M2.
                 @ail_<mod>_<fn> + _adapter/_clos: byte-unchanged.

DESIGN.md §"Embedding ABI" (docs/DESIGN.md:2266–2317):

before:  "M1 ABI is scalar-only and provisional until M3"
         "Only the value/record layout remains provisional until M3"
after :  + a "Frozen value layout (M3 — one-way commitment)" block:
           the layout table above; ailang_rc_alloc construction MUST;
           ailang_rc_dec free (scalar-field leak-free, M4 non-scalar
           flagged); ownership follows declared own/borrow mode.
         "provisional until M3" → "frozen as of M3; a future compiler
           change MUST NOT move these offsets or invert the free rule".
         rc.c:28-44 / lower_ctor / drop.rs each gain:
           // FROZEN ABI — see DESIGN.md §"Embedding ABI" frozen layout

Components

Component	Crate / file	Change
is_c_scalar → is_c_abi_type	ailang-check/src/lib.rs:1921	+ single-ctor-all-scalar record (recursive, bottoms out at Int/Float); returns a reason
ExportNonScalarSignature message	ailang-check/src/lib.rs:452	widened text: names single-ctor Int/Float record as permitted; rejected-record reason names the field + M4
CheckError variants / code() registry	ailang-check/src/lib.rs:453,459,712-713	unchanged (no new variant — explicit M2-style contrast)
fn_scalar_sig / llvm_scalar	ailang-codegen/src/lib.rs:659/673	a record type → ptr; scalars unchanged
M2 forwarder body	ailang-codegen/src/lib.rs:604-651	byte-unchanged (regression pin: record crosses as ptr, no RC at the forwarder)
internal @ail_<mod>_<fn> + _adapter/_clos	ailang-codegen	byte-unchanged (M1/M2 decision held)
§"Embedding ABI" frozen-layout SSOT	docs/DESIGN.md:2266-2317	new frozen-layout block; "provisional until M3" → one-way freeze
layout-byte pin	crates/ailang-codegen/tests/ (new)	asserts header/tag/field offsets + sizes + tag-word as emitted today; codegen offset shift → RED
lockstep pointers	runtime/rc.c:28-44, match_lower.rs lower_ctor, drop.rs	comment → DESIGN.md frozen SSOT
North-star fixture	examples/embed_backtest_step_record.ail (new)	the shown (own (con State)) (State,Float)->State
borrow fixture	examples/embed_backtest_step_record_borrow.ail (new)	(borrow (con State)) variant — proves "follows mode" both ways
M1 must-fail re-pointed	examples/embed_export_adt_ret_rejected.ail + asserting test	from single-ctor Pair (now M3-valid) → multi-ctor + Str-field ADT (genuinely still rejected)
narrower must-fail fixtures	examples/ (new)	single-ctor Str-field, single-ctor List-field, multi-ctor all-scalar — one rejection reason each
E2E record round-trip harness	crates/ail/tests/ (M1/M2 style)	host builds State via ailang_rc_alloc, N-loop, reads + ailang_rc_dec, ctx_free asserts allocs==frees; own and borrow variants

No design_schema_drift.rs movement (no schema field — explicit M2-style contrast). No ailang-core change, no Form-A change, no round-trip-invariant movement (no surface addition). Only the tests whose observed behaviour M3 changes are touched: the export-gate test (a single-ctor scalar record now passes; the re-pointed fixture still fails) and the forwarder-IR test (a record param/ret now lowers to ptr through the unchanged forwarder body). embed_e2e.rs (M1 scalar), the M2 swarm/rc-accounting harness, embed_export_hash_stable.rs, print_no_leak_pin.rs, and the e2e.rs leak-stat helper stay green unmodified.

Data flow

embed_backtest_step_record.ail   (no schema/surface change)
  → ail check        is_c_abi_type: (con State) ok [single-ctor, fields Float+Int];
                     (own (con State)) ok; effect set empty
  → desugar / lift / monomorphise        (unchanged)
  → lower_workspace_staticlib [--alloc=rc enforced, M2 guard]
        @backtest_step(ptr %ctx, ptr %st, double %sample) -> ptr
          %saved = load @__ail_tls_ctx ; store %ctx           (M2, byte-identical)
          %r = call ptr @ail_backtest_step(ptr %st, double %sample)
                 ; internal fn: Iter-B drops the `own` %st before ret
          store %saved @__ail_tls_ctx ; ret ptr %r            (M2, byte-identical)
  → backtest.ll → clang -c → backtest.o → ar → libbacktest.a
  ( rc.c / str.c → libailang_rt.a )                           (M2-unchanged)

host (1 thread, 1 ctx — M3 is single-record; concurrency is M2's, unchanged):
  ctx = ailang_ctx_new()
  st  = ailang_rc_alloc(8+2*8); write tag@0, acc@8, n@16        (alloc #1..)
  loop N×:  next = backtest_step(ctx, st, sample)
            ; (own): kernel consumed st (Iter-B drop = free #k); st = next
            ; (borrow): kernel kept st; ailang_rc_dec(st) (free #k); st = next
  read st[acc@8], st[n@16];  ailang_rc_dec(st)                  (final free)
  ailang_ctx_free(ctx)  →  AILANG_RC_STATS: allocs == frees     ← the proof
                            (M2 per-ctx counters are the instrument; no new one)

Error handling

• Multi-constructor data as an export type (Maybe, List, any 2+-ctor sum): ExportNonScalarSignature, RED — message names the constructor count and that the embedding ABI accepts a single-constructor record.
• Single-ctor record with a non-scalar field (Str, a nested record, List): ExportNonScalarSignature, RED — message names the offending field and position, and that nested/Str/List fields are a future (M4) layer (not "unsupported", per the verbose-diagnostic philosophy).
• Effectful record export: ExportHasEffects, unchanged RED.
• Host allocates the input with raw malloc instead of ailang_rc_alloc: outside the language boundary (a host-side contract violation) — the frozen SSOT states ailang_rc_alloc as a normative MUST (the refcount header at p-8 initialised to 1 is the precondition for correct own-consume and ailang_rc_dec). Not a checker concern; a documented ABI precondition.
• --emit=staticlib --alloc=gc|bump: unchanged M2 RED (the swarm artefact is RC-only).
• --emit=staticlib with zero (export) fns: unchanged M1 CLI error.

Testing strategy

RED-first throughout (skills/debug / TDD discipline).

0. Baseline pins (prerequisite — fixed first task, the 2026-05-11 failure class pre-empted in order; same shape as M1's/M2's fixed task 1). (a) Pin that embed_export_adt_ret_rejected.ail fails ail check today — this is the regression pin M3 deliberately re-points (not silently inverts: the pin's meaning changes from "any ADT rejected" to "non-M3-shaped ADT rejected", and the change is the explicit, reviewed content of an M3 task — not a test rewritten to dodge a behaviour change). (b) Pin the box layout as codegen emits it today — a new byte-offset test (size = 8 + n*8, tag i64 at offset 0, fields from offset 8, header at p-8) green before the freeze lockstep is attached, so the freeze rests on a baseline pinned at its own layer.
1. Gate RED trio + positive. (a) multi-ctor sum return, (b) single-ctor record with a Str field, (c) single-ctor record with a List field — each fails ail check with ExportNonScalarSignature naming the precise reason; plus the re-pointed combined fixture (multi-ctor and Str); plus the unchanged effectful ExportHasEffects fixture. The positive single-ctor Float+Int fixture passes ail check.
2. Forwarder shape pin. The forwarder for a record export is define ptr @backtest_step(ptr %ctx, ptr %st, double %sample) with the __ail_tls_ctx save/store/restore byte-identical to M2 around an unchanged call ptr @ail_backtest_step(ptr %st, double %sample); no @main; _adapter/_clos byte-identical to M1/M2 (regression pin on the "untouched" decision). No sret/byval emitted (pin: record crosses as a bare ptr).
3. E2E record round-trip — own (coherent-stop proof). The §"changed C host" harness on examples/embed_backtest_step_record.ail: host builds State via ailang_rc_alloc, calls N times, the kernel consumes each own input (Iter-B), the host frees the final return with ailang_rc_dec. Global leak-freedom proof model: the harness parses every ailang_rc_stats: line the run emits (the ailang_ctx_free ctx readback and the g_rc_* atexit line) and asserts Σallocs == Σfrees (equivalently Σlive = 0) and exit_code == 0 (the C host's assert(n == N) held). Per- ctx-line balance is not asserted: by M2's TLS-ctx design the host's make_state/final-dec run outside the forwarder call and land on g_rc_*, so only the global sum is the invariant.
4. E2E record round-trip — borrow. examples/embed_backtest_step_record_borrow.ail: the host retains and ailang_rc_decs each input itself; the kernel does not consume it (correct borrow, ratified by e2e.rs::alloc_rc_borrow_only_recursive_list_drop). Same global proof model as item 3 — Σallocs == Σfrees, exit 0. In borrow mode the kernel allocs every return box on ctx while the host's balancing decs land on g_rc_* (the ctx line shows live=+N, the g_rc line live=−N, summing to 0): this split attribution is correct M2-TLS-window behaviour, not a leak. Items 3+4 together prove "ownership follows the declared mode" in both directions, globally leak-free — tested, not asserted.
5. Layout byte-pin is enforcing. The item-0(b) pin is green; a deliberate one-off offset perturbation in lower_ctor (local experiment, reverted) turns it RED — demonstrating the freeze is enforceable, not aspirational.
6. Schema / hash invariance, unmodified. embed_export_hash_stable.rs and design_schema_drift.rs green unmodified — M3 adds no schema field (explicit M2-style contrast).
7. Executable path unchanged. print_no_leak_pin.rs + the e2e.rs leak-stat helper green unmodified; M1 embed_e2e.rs (scalar) + the M2 swarm/rc-accounting harness green unmodified (M3 is additive to the gate/forwarder; the scalar path is byte-preserved).
8. Clean-core invariant. No new dependency in ailang-core / ailang-codegen / runtime/; architect audits Invariant 1 at close.
9. Bench regression trio. No runtime change, no codegen change on the benched (non-embed, executable) hot path — bench/check.py / compile_check.py / cross_lang.py carry-on, with the byte-identical-binary causal-exoneration method if a tracked-noise metric fires. Not hand-waved.

Acceptance criteria

Feature-acceptance criterion (DESIGN.md §"Feature-acceptance criterion"), applied honestly to a strategic infra/capability milestone with no authoring surface:

1. LLM author naturally produces it. The worked .ail (examples/embed_backtest_step_record.ail, shown above) is the direct minimal evolution of the M1/M2 scalar kernel into a record State; asked to make a stateful fold callable from a Rust host, an LLM author writes exactly this (existing data + existing (own (con T)) + existing (export …)). The worked .ail is the clause-1 evidence, not a prose assertion. Recorded honestly: the justification is strategic (the language's target deployment, the user-made roadmap direction call), not the standard authoring-utility metric. No pretence otherwise.
2. Measurably improves correctness / removes redundancy. A capability + correctness gate, recorded honestly (as M1's/M2's clause 2 were): today a stateful fold cannot cross the embedding boundary at all (M1/M2 are scalar-only) — the entire (State, Chunk) -> State backtest the arc exists for is unbuildable as an embedded kernel without M3. The correctness delta is that the record crossing becomes memory-safe by a specified, tested, frozen contract (alloc==free proven for both modes; layout byte-pinned) rather than undefined.
3. Reintroduces no bug class the core eliminates. The export gate still makes wrong code fail to typecheck (clause-3 in code, not documentation): multi-ctor / Str-field / nested- record / effectful exports stay RED. M3 narrows the gate precisely along the single-ctor-all-scalar boundary — it opens no hole; the discriminator is sharper (the re-pointed must-fail rejects on two independent reasons). Decision 10 ("single-threaded; non-atomic refcounts") stays true: M2's per-thread ctx ⇒ no cell crosses a thread; an M3 record is per-thread by the same construction (built by the host thread that owns the ctx, freed by it) — Invariant 2 (no value crosses a thread boundary) holds, strengthened. The ownership contract follows the existing declared-mode machinery (DESIGN.md §"Mode metadata is load-bearing for codegen") — no new RC rule. The host-free choice (ailang_rc_dec) is leak-free by construction for M3-shaped records; the non-scalar case is explicitly flagged as M4-additive, not a hidden hole. The frozen commitment freezes the actual current layout (tag-included, as-is), byte-pinned and enforceable. Invariant 1 (clean core), Invariant 3 (native-AOT only) hold and are audited.

Milestone-close ("coherent stop") is met when all hold:

• examples/embed_backtest_step_record.ail builds with ail build --emit=staticlib; the C host builds the input State via ailang_rc_alloc, calls backtest_step N times, reads and ailang_rc_decs the return, and the run is globally leak-free — Σallocs == Σfrees across every ailang_rc_stats: line (Σlive = 0), exit 0 (own variant — coherent-stop proof).
• The borrow variant (embed_backtest_step_record_borrow.ail, host-retained input freed by the host) is likewise globally leak-free (Σallocs == Σfrees, exit 0; ctx live=+N / g_rc live=−N summing to 0 — correct M2-TLS cross-attribution, not a leak) — "follows the declared mode" proven both ways.
• The gate RED trio + the re-pointed combined must-fail + the effectful fixture all fail ail check with precise, self-correcting diagnostics; the positive single-ctor Float+Int fixture passes.
• Forwarder / internal @ail_<mod>_<fn> / _adapter/_clos / executable path / schema-hash all byte-unchanged (embed_export_hash_stable.rs, design_schema_drift.rs, print_no_leak_pin.rs, M1 embed_e2e.rs, M2 swarm harness green unmodified).
• The layout byte-pin is green and demonstrably enforcing (a deliberate offset perturbation turns it RED).
• DESIGN.md §"Embedding ABI" carries the frozen value-layout SSOT; "provisional until M3" → one-way-freeze wording; the three encoding sites carry the lockstep pointer.
• Architect audit confirms Invariant 1; bench trio carry-on (no hot-path change; byte-identical-binary causal exoneration if a tracked-noise metric fires).

Iteration sequencing (prerequisite-first)

The planner decomposes M3 into bite-sized tasks, but task 1 is fixed: the Testing-strategy item-0 baseline pins — (a) pin that embed_export_adt_ret_rejected.ail fails ail check today (the pin M3 deliberately re-points, made explicit and reviewed, not silently inverted), and (b) pin the box layout as codegen emits it today before the freeze lockstep attaches. Rationale, same shape as M1's/M2's fixed task 1: M3 is defined as (i) widening the gate exactly along the single-ctor-all-scalar boundary the existing must-fail corpus brackets, and (ii) converting the provisional layout into a frozen, byte-pinned commitment. Both load-bearing changes must rest on a baseline pinned at their own layer before the change is introduced (the 2026-05-11 failure class, pre-empted in order). Only after task 1 is green does the check/codegen/docs work proceed. No other inter-task ordering is mandated; the planner owns the rest.

Out of scope (explicit)

• More than one record type crossing the boundary in a single signature beyond the (State, Sample) -> State shape's needs; the milestone's coherent stop is the single State round-trip.
• List / sequence crossing — M4.
• Str in/out — M4+ (a Str field is a non-scalar field, rejected by the M3 gate).
• Nested records (a record field whose type is itself a record) — M4; the M3 recursive scalar check bottoms out at Int/Float and rejects a record-typed field.
• A typed host-free symbol (@<sym>_free, a generic ailang_record_free) — explicitly not introduced; M3 leans on the scalar-field restriction so ailang_rc_dec is leak-free, and names the non-scalar recursive-free as M4's additive concern (the build-ahead-of-consumer trap, refused as in M1/M2).
• Single-ctor tag elision — a hot-path codegen change touching every single-ctor ADT tree-wide for ABI cosmetics (human ergonomics, not LLM-author utility; disfavoured by the feature-acceptance criterion); the frozen layout includes the tag word as-is.
• Any change to the internal @ail_<module>_<fn> calling convention or the _adapter/_clos closure pair (M1/M2 decision held).
• The ail-embed adapter crate + data-server wiring + the real thread-swarm record backtest — M5.
• Tree-wide Boehm retirement — the separate standing P2 todo, untouched.