Brummel
832375f2ac
All 176 files in the four accumulating directories now use a zero-padded 4-digit counter prefix that reflects creation order (`NNNN-slug.md`). The counter is assigned per directory in strict git-log creation order; ties broken alphabetically by original name. The old `YYYY-MM-DD-` prefix on docs/specs/ and docs/plans/ files is dropped — the date is recoverable from git log and the counter carries the ordering. A file's counter is stable for the life of the file: never reassigned, never reused, never compacted. Deleted files retire their counter; subsequent files do not fill the gap. This is the property that lets cross-references stay literal — refs use the full filename including the counter (`design/contracts/0007-honesty-rule.md`) so they grep cleanly and resolve directly without a glob step. 313 cross-references updated across .md/.rs/.toml/.c/.json files (test pins, include_str! paths, design-INDEX entries, baseline notes, runtime C comments, inter-contract markdown links incl. bare basename and `../models/foo.md` forms). CLAUDE.md gets a new "File-naming convention" section spelling out the rule and rationale. skills/brainstorm/SKILL.md and skills/planner/SKILL.md updated so new spec/plan creation produces counter-prefixed names from the start. The full test suite (cargo test --workspace) passes.
49 lines
2.3 KiB
Markdown
49 lines
2.3 KiB
Markdown
# 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`.
|