# Frozen value layout (M3 — one-way commitment)

## Frozen value layout (M3 — one-way commitment)

For a single-constructor `data T` whose `n` fields are each `Int`
or `Float`, a value of `T` crossing the
[embedding C boundary](0003-embedding-abi.md) is a
bare payload pointer `p`:

| bytes | content |
|---|---|
| `p - 8 .. p` | `uint64_t` refcount header (`HEADER_SIZE = 8`) |
| `p + 0 .. p + 8` | `int64_t` constructor tag (written; `0` for the single ctor — no elision) |
| `p + 8 + i*8` | field `i`, declaration order: `int64_t` for `Int`, IEEE-754 `double` bit-pattern for `Float` |

Total box payload size = `8 + n*8`. This is the same layout
`lower_ctor` (`match_lower.rs`) emits internally; for an exported
type the host encodes and decodes these exact offsets itself, so
they are **frozen** — a compiler change MUST NOT move them for an
exported type, which permanently constrains codegen's freedom to
repack exported records.

**Construction (host → kernel input).** The host MUST obtain an
input record's storage from `ailang_rc_alloc(8 + n*8)` (returns the
payload pointer with the refcount header pre-set to `1`, payload
zeroed), then write the tag (`0`) and the scalar fields at the
offsets above. A raw `malloc` is a contract violation:
`own`-consume and `ailang_rc_dec` both require the runtime's 8-byte
header at `p - 8` initialised to `1`.

**Ownership follows the declared mode** (the
[Mode metadata is load-bearing for codegen](0008-memory-model.md)
contract, as the C ABI): a `(own (con
T))` parameter transfers ownership in — the kernel consumes it
(Iter-B drop-at-return); the host MUST NOT touch or `dec` it after
the call. A `(borrow (con T))` parameter is retained by the host —
the kernel does not consume it; the host frees it. The return value
is always owned by the host.

**Free (host side).** `ailang_rc_dec(payload)`. Leak-free for an M3
record because every field is a scalar — `ailang_rc_dec` is
header-only and an M3 record has no boxed children. A record with
boxed fields (`Str`/`List`/nested record) is **not** an M3
embedding type — the export gate rejects it, so the boundary
never crosses a value that would need a recursive typed-free. The
freeze covers exactly the all-scalar single-constructor record.

Ratified by: `crates/ailang-codegen/tests/embed_record_layout_pin.rs`.