Brummel
176821c2e7
The 3020-line docs/DESIGN.md is replaced by the design/ ledger:
design/INDEX.md (sole addressable spine, typed Contracts+Models tables,
polymorphic links — prose file OR authoritative source //!), 14
design/contracts/*.md test-linked invariants + 3 source-link-only
contracts (mangling/env-construction/qualified-xref, no prose file —
code is SoT), 5 design/models/*.md whitepapers, and
docs/journals/2026-05-19-design-decision-records.md (the
relitigation-guard archive — every why/rejected/does-not-do/rollback/
empirical ### moved out at ###-granularity). Clean cut: git rm
docs/DESIGN.md, no stub.
RED-first crates/ailang-core/tests/design_index_pin.rs — the 4-clause
anti-regrowth spine (DESIGN.md-gone / every-INDEX-link-resolves /
every-contract-names-a-resolvable-ratifier /
contracts-carry-no-decision-record-prose) — demonstrably RED before,
GREEN after. Build-atomic by task ordering: design_schema_drift.rs's
include_str! (the only compile-time consumer) retargeted to
design/contracts/data-model.md BEFORE the deletion; its
## Data model/## Pipeline slicer dropped (a simplification the split
enables). 2 NoInstance diagnostics + 2 lockstep E2Es retargeted to
design/contracts/{float-semantics,typeclasses}.md. ~12 agent reading
lists + 5 SKILL bodies + CLAUDE.md + skills/README.md + ~25
code/C/.ail/spec comment xrefs retargeted; OQ7 dangling 'Iter 13b'
cite deleted (no forward target — a pointer would be fiction).
honesty-rule.md rewritten so the rule names the new home
(rationale->journals), resolving the recon-found internal
contradiction; the two docs_honesty_pin.rs:70,72 pinned phrases kept
verbatim+contiguous.
Boss-verified independently: cargo test --workspace 646 passed /
0 failed; design_index_pin 4/4; acceptance grep CLEAN of live
DESIGN.md refs (residuals = only the spec-mandated clause-4
deletion-enforcer). 2 DONE_WITH_CONCERNS routed to the mandatory
milestone-close audit: (a) str-abi.md:23 '(iter str-concat,
2026-05-13)' provenance stamp trips advisory architect_sweeps Sweep-1
— Boss-confirmed byte-identical to DESIGN.md@deeffb1:2062-2065, a
faithfully-migrated PRE-EXISTING anchor (regexes verbatim, only path
retargeted), NOT split-introduced — RATIFY-or-tidy at audit; (b) a
now stale-direction intra-prose 'see Str ABI below' cross-ref in
float-semantics.md — audit-adjudication candidate. Plan defect noted:
Task 9 Step 4's verbatim acceptance grep used a ^./ anchor not
matching the system's grep -rIn output; substance re-verified CLEAN.
Spec grounding-check PASS x2. Journals INDEX + decision-records
pointer appended (Boss-only).
87 lines
4.5 KiB
Markdown
87 lines
4.5 KiB
Markdown
# Str ABI
|
|
|
|
## Heap-Str primitives
|
|
|
|
The runtime ships a small family of operations that produce or
|
|
transform heap-allocated `Str` values uniformly across static-Str
|
|
and heap-Str inputs (the consumer ABI is identical between
|
|
realisations — see §"Str ABI"). All take their input(s) by `borrow`
|
|
and return an owned `Str`. Each is registered as a builtin in
|
|
`crates/ailang-check/src/builtins.rs`, lowered inline in
|
|
`crates/ailang-codegen/src/lib.rs::lower_app` to a `call ptr @ailang_<name>`,
|
|
and backed by a `runtime/str.c` C helper.
|
|
|
|
- `int_to_str : (borrow Int) -> Str` (iter 24.1) — decimal rendering
|
|
of an `Int`. Backs `Show Int` in the prelude.
|
|
- `bool_to_str : (borrow Bool) -> Str` (iter 24.1) — `"true"`/`"false"`.
|
|
Backs `Show Bool` in the prelude.
|
|
- `float_to_str : (borrow Float) -> Str` (iter 24.1) —
|
|
type-installed; codegen is reserved and not yet shipped.
|
|
- `str_clone : (borrow Str) -> Str` (iter 24.1) — allocates a fresh
|
|
heap-Str copy of the input's bytes. Backs `Show Str` in the prelude.
|
|
- `str_concat : (borrow Str, borrow Str) -> Str` (iter str-concat,
|
|
2026-05-13) — combines two `Str` values into a single owned `Str`.
|
|
General-purpose; commonly used in Show bodies for labelled output
|
|
(`(app str_concat "label=" (app int_to_str x))`).
|
|
|
|
The four Show-backers above are not directly observable to the
|
|
LLM-author writing a `Show <T>` instance — the prelude's instance
|
|
bodies dispatch into them. `str_concat` IS directly observable
|
|
because the LLM-author calls it explicitly when authoring an
|
|
instance body that wants to combine fragments.
|
|
|
|
Primitive output for `Str` values goes through `io/print_str`
|
|
directly; values of other primitive types route through the
|
|
polymorphic `print` helper (§"Polymorphic print"), which feeds
|
|
the heap-Str result of `show x` into `io/print_str`.
|
|
|
|
`==`, `<`, `<=`, `>`, `>=` REMAIN primitive operators (unchanged
|
|
from the original draft). Class methods are accessed by name (`eq x y`,
|
|
`lt x y`, …), not via these operators. Routing operators through
|
|
classes is deliberately deferred — it would require migrating every
|
|
existing fixture and would re-baseline the bench corpus, which is a
|
|
new-baseline decision rather than an iter detail.
|
|
|
|
`Num` is NOT in milestone 22. Arithmetic operators (`+`, `-`, `*`,
|
|
`/`) stay primitive and per-type. Class-based numeric overloading
|
|
would invoke literal-defaulting which axis-7 already excluded.
|
|
|
|
**Str ABI.** A `Str` is a pointer to a structure with `i64 len` at
|
|
offset 0 followed by `len` bytes plus a trailing `NUL` at offset 8.
|
|
Two realisations share this consumer ABI:
|
|
|
|
| Realisation | Origin | rc_header | Memory |
|
|
|-------------|-------------------------------------------------|-----------|-----------------------------------------|
|
|
| static-Str | string literals (`@.str_*` LLVM globals) | none | `.rodata`, packed-struct `<{ i64, [N+1 x i8] }>` |
|
|
| heap-Str | runtime allocations (`int_to_str`, `float_to_str`, ...) | yes, at `payload - 8` | `malloc`'d via `ailang_rc_alloc(8 + len + 1)` |
|
|
|
|
Every consumer (`@puts`, `@strcmp`, `@ail_str_eq`,
|
|
`@ail_str_compare`) GEPs `+8` from the Str pointer to reach the
|
|
bytes, regardless of realisation. The byte-comparison semantics
|
|
are inherited from libc `strcmp` — locale-independent, NUL-
|
|
terminated.
|
|
|
|
The heap-Str realisation participates in standard RC: the
|
|
`rc_header` slot eight bytes before the `len` field is managed
|
|
by `ailang_rc_alloc` / `ailang_rc_inc` / `ailang_rc_dec` exactly
|
|
like any other RC-allocated cell. The static-Str realisation has
|
|
no `rc_header` slot at all; the bytes at `payload - 8` belong to
|
|
the previous global in `.rodata` and reading them is undefined.
|
|
|
|
**The static-Str non-RC invariant is enforced at codegen.** Two
|
|
mechanisms keep static-Str pointers out of `ailang_rc_dec` along
|
|
every shipping execution path: (1) the non-escape lowering pass
|
|
(iter 18b) and the move-tracking partial-drop logic (iter 18d.3)
|
|
prevent let-binders or pattern-binders for static-Str literals
|
|
from reaching scope-close drop emission; (2) the `Type::Con { name: "Str" }`
|
|
carve-outs in `field_drop_call` and in the `Term::App` arm of
|
|
`drop_symbol_for_binder` (both in `crates/ailang-codegen/src/drop.rs`)
|
|
route the rare case that *does* reach drop emission through
|
|
`ailang_rc_dec`, which itself only fires for heap-Str at runtime
|
|
(static-Str pointers never carry a live rc_header; if codegen ever
|
|
let one through, the runtime would corrupt `.rodata`-adjacent
|
|
memory). No runtime guard backs the invariant up; the codegen
|
|
proof is the protection.
|
|
|
|
Ratified by: `crates/ail/tests/e2e.rs`.
|