Files

T

Brummel 625fe849be docs(contracts): reconcile contracts + honesty-pin with shipped reality

First tranche of a contracts-against-code audit (the inverse of the
usual direction: testing the ledger's claims against the code). Each
fix here is a verified factual divergence between a contract and the
code; the direction of the fix follows which side actually drifted.

Code drifted from the stated goal -> fix the code:

- 0014's claim 6 ("`cargo doc --no-deps` runs warning-free") was the
  design goal; reality had 6 warnings. Demote the offending intra-doc
  links to plain code spans so the docs match the goal:
  - ailang-core: `[`load_workspace`]` cannot resolve from core (the
    fn lives in ailang-surface, which core may not depend on) — three
    sites in workspace.rs.
  - ailang-check: three public-item docs linked the `pub(crate)`
    helpers `qualify_local_types` / `qualify_workspace_types`.
  `cargo doc --no-deps --workspace` is now warning-free.

Contract stale, code legitimately advanced -> fix the contract:

- 0011 stated `float_to_str` "codegen is reserved and not yet
  shipped". It is shipped: lowers to `@ailang_float_to_str(double)`,
  green under the codegen `float_to_str_no_longer_errors_internal`
  unit test and the e2e `float_to_str_smoke`. The docs_honesty_pin
  anchor that protected the stale "reserved" wording moved in lockstep
  to assert the present-tense lowering instead — the pin had been
  guarding a claim the code already falsified.
- 0013 named the diagnostic `ConstraintReferencesUnboundTypeVar`; the
  variant is `UnboundConstraintTypeVar` (workspace.rs), and its scope
  is a class-method signature whose constraint mentions a tyvar bound
  neither by the method's `forall` nor by the class `param`.
- 0017 called the primitive Eq/Ord bodies "placeholder lambdas"; they
  carry the `(intrinsic)` marker — the lockstep partner to the
  INTERCEPTS registry, not a placeholder.
- 0009 said "seven" `.ail.json` carve-outs and described the inventory
  test as pinning seven; the test pins twelve (7 subject-matter + 4
  recur + 1 loop-binder, per carve_out_inventory.rs).

Verified separately: 0001's "pretty-printer code in pretty.rs was
deleted, leaving only diagnostic helpers" is factually correct (an
audit agent misread it as "pretty.rs was deleted"); its only issue is
history phrasing, deferred to the honesty-prose tranche.

Deferred to later tranches: honesty-rule prose (history/rationale that
is not a protected honest-reserved/tiebreaker anchor), stale/mislinked
ratifying-tests (0014's `architect_sweeps.sh`, 0015's uniqueness
in-source tests), 0014's never-existent `tests/expected/`, 0012's
non-exhaustive tail-context list, and the 0016<->0013 redundancy.

2026-06-02 11:14:01 +02:00

5.0 KiB

Raw Blame History

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 the Str ABI table below). 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 — decimal rendering of an Int. Backs Show Int in the prelude.
bool_to_str : (borrow Bool) -> Str — "true"/"false". Backs Show Bool in the prelude.
float_to_str : (borrow Float) -> Str — renders a Float to its decimal string via libc %g. Lowers to call ptr @ailang_float_to_str(double).
str_clone : (borrow Str) -> Str — allocates a fresh heap-Str copy of the input's bytes. Backs Show Str in the prelude.
str_concat : (borrow Str, borrow Str) -> Str — 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 (see prelude classes), which feeds the heap-Str result of show x into io/print_str.

Equality on Str dispatches via prelude.Eq.eq (Str instance, lowered by try_emit_primitive_instance_body::eq__Str to a call into @ail_str_eq with the alwaysinline attribute). Ordering on Str dispatches via prelude.Ord.compare (Str instance, lowered by try_emit_primitive_instance_body::compare__Str to a call into @ail_str_compare then a three-way branch ladder constructing LT/EQ/GT). The polymorphic helpers ne / lt / le / gt / ge resolve via the class layer on top of eq / compare. There are no primitive operator names == / < / != / etc. in the language.

Arithmetic operators (+, -, *, /, %) stay primitive and per-type.

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 (@fputs, @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 print path uses @fputs(bytes, @stdout) so that (do io/print_str s) writes exactly the bytes of s with no implicit trailing newline (Gitea #29; the earlier @puts lowering appended a newline per call).

The heap-Str realisation participates in standard RC (see memory model): 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 and the move-tracking partial-drop logic 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.

5.0 KiB Raw Blame History

Str ABI

Heap-Str primitives

5.0 KiB

Raw Blame History