AILang/docs/specs/0005-floats.md

# Floats — Design Spec

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

## Goal

Introduce `Float` as a fourth zero-arity primitive type, alongside
`Int`, `Bool`, `Str`, `Unit`. `Float` is **IEEE-754 binary64**
(LLVM `double`). One float type ships, no `f32` variant.

Status quo (2026-05-10):

- `crates/ailang-core/src/primitives.rs:17` lists primitives as
  `Int | Bool | Str | Unit` — no Float.
- `crates/ailang-core/src/canonical.rs:14` doc comment explicitly
  says "no floats" because `serde_json::Number::to_string` is not
  bit-stable across versions for floating-point values.
- `docs/DESIGN.md:1625` mentions `Float` once in an annotation
  example — dead text with no implementation behind it.

After this milestone:

- An LLM-author can write `1.5`, `1.5e3`, `(fadd x y)`,
  `(int_to_float n)` in surface form (B); the canonical form (A)
  carries float literals as bit-pattern hex strings; codegen emits
  IEEE-754 binary64 ops via LLVM `double`.
- The eventual Post-22 Prelude milestone can ship `Show Float`,
  but **not** `Eq Float` or `Ord Float` — Float's IEEE-conformant
  equality (NaN ≠ NaN) and partial ordering are real and surface
  through builtins, not through total typeclass instances.

This milestone is **scoped to the primitive itself** — literal
shape, lexer/parser/printer, type, builtins, codegen, IO,
documentation. Typeclass wiring (`Show` / `Eq` / `Ord` instances,
`Num` polymorphism) is out of scope and lives in the next
milestone(s).

## Architecture

Five load-bearing decisions shape every component below.

### A1 — Form-A literal shape: bit-pattern hex string

```json
{ "kind": "float", "bits": "4014000000000000" }
```

`bits` is the lowercase 16-character hex representation of the
IEEE-754 binary64 bit pattern as a `u64` (big-endian byte
ordering). This is the *only* permitted form; serialising `1.5`
as a JSON number is forbidden.

Rationale:

- **Hash stability.** Form-A bytes feed `def_hash` /
  `module_hash` via `canonical::to_bytes`. Today's number path
  uses `serde_json::Number::to_string`, which is not bit-stable
  across `serde_json` versions for floats and which cannot
  represent NaN / ±Inf in JSON at all (they collapse to `null`).
  Routing floats through the *string* path preserves bit-exact
  determinism without changing `canonical.rs`'s number arm.
- **NaN / -0 / Inf are explicit.** `+0.0` is `0000000000000000`,
  `-0.0` is `8000000000000000`, the two are distinct bit
  patterns and therefore distinct Form-A literals; quiet NaN is
  `7ff8000000000000`; ±Inf are `7ff0000000000000` /
  `fff0000000000000`. All preserved bit-for-bit by hash.
- **No ambiguity.** `0.1` parsed in surface lex becomes
  `bits = "3fb999999999999a"` once; round-tripping back to
  surface `0.1` is the printer's job, but the canonical truth
  is always the bits.

The `canonical.rs:14` "no floats" comment will be updated to
"floats only via the string path (bit-pattern hex)".

### A2 — Surface lexer: decimal-point or exponent required

A float literal in form (B) is one of:

- `<digits>.<digits>` — e.g. `1.5`, `0.0`, `100.0`
- `<digits>.<digits>e[+-]?<digits>` — e.g. `1.5e3`, `2.0e-10`
- `<digits>e[+-]?<digits>` — e.g. `1e10`, `3e-5`

Out of scope (rejected at lex time):

- Hex floats `0x1.8p4` — adds lexer complexity for no LLM-author
  benefit (GPT/Claude don't reach for hex float literals
  unprompted).
- Bare leading/trailing dot: `.5`, `5.` — the unambiguous form
  (`0.5`, `5.0`) is one keystroke longer; rejecting the short
  forms removes a class of "is this a float or a member access?"
  ambiguity.
- NaN / Inf literals — these are bit patterns, not surface
  syntax. A future Float stdlib can expose `Float.nan` /
  `Float.infinity` constants; for now an LLM that needs a NaN
  literal in form-A can write the hex bits directly.

Negative float literals follow today's negative-int rule
(`crates/ailang-surface/src/lex.rs:175` accepts `-` followed by a
digit as part of a numeric token), so `-1.5` lexes as a single
`Tok::Float`.

### A3 — Builtin operators: polymorphic over `{Int, Float}` via codegen-dispatch

The arithmetic and comparison operators that today are
monomorphic-Int (`+`, `-`, `*`, `/`, `<`, `<=`, `>`, `>=`) are
**widened to polymorphic** with the same shape and dispatch
mechanism the existing `==` / `!=` already use:

```
+   : forall a. (a, a) -> a       -- Int|Float; reject otherwise
-   : forall a. (a, a) -> a       -- Int|Float
*   : forall a. (a, a) -> a       -- Int|Float
/   : forall a. (a, a) -> a       -- Int|Float
<   : forall a. (a, a) -> Bool    -- Int|Float
<=  : forall a. (a, a) -> Bool    -- Int|Float
>   : forall a. (a, a) -> Bool    -- Int|Float
>=  : forall a. (a, a) -> Bool    -- Int|Float
==  : forall a. (a, a) -> Bool    -- existing; Float arm added
!=  : forall a. (a, a) -> Bool    -- existing; Float arm added
%   : (Int, Int) -> Int            -- stays monomorphic (no fmod yet)
```

Codegen dispatches on the resolved argument type at the call
site, parallel to today's `==` path (`crates/ailang-codegen/src/
lib.rs:2244-2266`):

| Op | Int arm | Float arm |
|---|---|---|
| `+` | `add i64` | `fadd double` |
| `-` | `sub i64` | `fsub double` |
| `*` | `mul i64` | `fmul double` |
| `/` | `sdiv i64` | `fdiv double` |
| `==` | existing `icmp eq i64` / `i1` / `@strcmp` / `i1 1` | `fcmp oeq double` |
| `!=` | existing `icmp ne i64` etc. | `fcmp une double` |
| `<` | `icmp slt i64` | `fcmp olt double` |
| `<=` | `icmp sle i64` | `fcmp ole double` |
| `>` | `icmp sgt i64` | `fcmp ogt double` |
| `>=` | `icmp sge i64` | `fcmp oge double` |

**Note on `!=`:** the LLVM `fcmp` predicate for IEEE-`!=` is
`une` ("unordered or not equal"), **not** `one` ("ordered and
not equal"). `one` would return `false` for `nan != nan`, which
contradicts user-fixed constraint #2 (NaN ≠ NaN per IEEE).
`une` matches Rust's `f64::ne` and IEEE 754 `!=` exactly.

**Note on `==`:** `fcmp oeq` returns `false` whenever either
operand is NaN, which is the IEEE-`==` semantics we want.
Bit-level NaN-detection is separate and uses `is_nan` (below)
or `fcmp uno`.

Non-{Int,Float} resolutions for `+`/`-`/`*`/`/`/`<`/`<=`/`>`/`>=`
get rejected at codegen with the same diagnostic shape the `==`
path uses today (`"+ not supported for type X"`). The reject
keeps the polymorphism honest — there is no silent fallback,
no string-concatenation-via-`+`, no boolean-arithmetic-via-`+`.

Rationale:

- **Mainstream alignment.** Every LLM-relevant programming
  language (Rust, Java, C, Python, JavaScript, Haskell, Swift,
  OCaml-via-typeclass-like-extension) accepts `1.5 + 2.5`. An
  AILang where the LLM-author has to write `(fadd 1.5 2.5)` is
  a high-friction first-try-error surface. The user-facing
  decision (this conversation, 2026-05-10) chose Mainstream
  alignment over the explicit-naming purity of an earlier draft.
- **Precedent already in tree.** The `==` builtin is
  `forall a. (a, a) -> Bool` with a hardcoded Int|Bool|Str|Unit
  codegen dispatch and explicit reject for ADT/Fn equality
  (`builtins.rs:75-77`). The widening of `+`/`-`/etc. uses the
  *same* mechanism — no new architectural surface, just more
  arms in the existing dispatch helper.
- **Typeclass migration story.** When typeclasses ship
  (Post-22 Prelude + 22c), the hardcoded `Int|Float` spec-case
  in the typechecker can be cleanly replaced by a `Num a`
  constraint. Surface (`(+ 1.5 2.5)`) does not change. The
  spec-case is transitional, not load-bearing.
- **`%` stays monomorphic.** IEEE `frem` (LLVM op for `fmod`)
  has subtle semantics (sign-of-result-follows-dividend,
  ±0 / ±Inf edge cases) that deserve their own decision; out
  of scope for this milestone.

Other new builtins:

```
neg                   : forall a. (a) -> a       -- Int|Float; reject otherwise
int_to_float          : (Int) -> Float
float_to_int_truncate : (Float) -> Int
float_to_str          : (Float) -> Str
is_nan                : (Float) -> Bool          -- LLVM `fcmp uno double %x, %x`
```

The unary `neg` is widened the same way arithmetic ops are
(today there is no `neg` builtin — unary minus is desugared from
the surface lexer's `-<digits>` rule into a literal or via
`(- 0 x)`-style desugar; the spec adds an explicit `neg` so
Float negation has a name without the `(- 0.0 x)` workaround,
which is wrong for `-0.0`). The plan picks the desugar/builtin
boundary.

New builtin float constants (always-in-scope `Term::Var`
references, parallel to today's `__unreachable__`):

```
nan      : Float    -- bits 7ff8000000000000 (canonical quiet NaN)
inf      : Float    -- bits 7ff0000000000000
neg_inf  : Float    -- bits fff0000000000000
```

Rationale for the constants:

- Every Mainstream language exposes them (`f64::NAN`,
  `Double.NaN`, `float('nan')`, `NaN`, `Double.nan`).
  Withholding them while shipping the IEEE-conformant
  semantics that *make them necessary* is a pointless friction.
- Hex bits via Form-A still works as the ground truth, but
  surface-level `(var nan)` lets the LLM-author write code that
  reads like every other language's float code.
- Names are lowercase (`nan`, not `NaN`) so they're regular
  identifiers, no surface-lex special-case. `neg_inf` instead
  of `-inf` because `-` cannot start a value identifier (the
  surface-lex `-<digits>` rule applies to numeric literals
  only).

Effect ops (added):

```
io/print_float : (Float) -> Unit !IO    -- new
```

### A4 — Conversions: total, foot-gun-free

- `int_to_float : (Int) -> Float` — LLVM `sitofp double`. Exact
  for `|n| < 2^53`, round-to-nearest-even otherwise.
- `float_to_int_truncate : (Float) -> Int` — saturating
  truncation toward zero; `NaN → 0`. Matches Rust `as i64`
  semantics (since 1.45). Total, no UB, no `Maybe Int` wrapper.
  Lowered as LLVM `fptosi.sat.i64`.
- `float_to_str : (Float) -> Str` — shortest round-trippable
  decimal. The runtime C glue calls a `dtoa`-style routine (we
  link an existing `ryu`-equivalent implementation; vendoring vs
  upstream is a plan-time decision).

A hypothetical `float_to_int_checked : (Float) -> Maybe Int`
variant would be safer than an unchecked `fptosi`, but the
saturating truncate is *also* safe and is one less ADT
construction at the call site. If a future use case needs the
distinction (e.g. NaN-detection without a dedicated `is_nan`
builtin), revisit then.

### A5 — Determinism contract

Spec language for `docs/DESIGN.md` "Float semantics" section
(added by this milestone):

- **Guaranteed:** every individual builtin
  (`fadd`/`fsub`/`fmul`/`fdiv`/`fneg`/`flt`/...) lowers to a
  single LLVM IR instruction (`fadd double`, `fsub double`, ...).
  On a fixed `(target triple, LLVM version)` pair, the bit
  pattern of the result of any single op is reproducible.
- **Guaranteed:** NaN and ±Inf propagate per IEEE 754 (no
  silent collapse to zero, no trap).
- **Guaranteed:** -0 and +0 are distinct bit patterns at the
  literal / hash / equality-bit level (`==` returns `true`
  comparing `-0.0 == 0.0` per IEEE, but they hash distinctly in
  Form-A — this is the correct asymmetry).
- **Unspecified:** FMA contraction (LLVM may fold `fadd (fmul a
  b) c` into `fma a b c`); reassociation; subnormal flushing
  modes if the target enables FTZ/DAZ; the exact NaN bit
  pattern produced by an op (any qNaN bit pattern is
  conformant).

These are the Rust / Swift / standard-LLVM defaults, not
research-grade reproducibility guarantees. The stronger
guarantee (e.g. Pythonic `float.fromhex`-level bit
reproducibility across ops) would require LLVM
`-ffp-contract=off` plus per-op intrinsic selection — out of
scope; revisit only if a real use case appears.

## Components

Touched files, by crate. Sizes given for scope estimation; see
the plan for iteration boundaries.

### `crates/ailang-core/`

- `ast.rs` (785 LoC) — add `Literal::Float { bits: u64 }`
  variant. Serde `rename_all = "lowercase"` already gives us the
  `"kind": "float"` discriminator. The `bits` field needs a
  custom `Serialize`/`Deserialize` to emit/parse the
  16-character lowercase hex string (Serde's default for `u64`
  is decimal). Add `Type::float()` convenience constructor
  alongside `Type::int()`/`Type::bool_()`/`Type::unit()`.
- `primitives.rs` (52 LoC) — append `"Float"` to both
  `is_primitive_name` and `primitive_surface_name`. The
  lockstep test there enforces both are updated; extend the
  test sample to include `"Float"`.
- `canonical.rs` (200+ LoC) — **no logic change**. The float
  literal goes through the `String` path because `bits` is
  serialised as a hex string, not a JSON number. Update the
  module-level "no floats" doc comment to reflect the new
  reality ("floats encoded as bit-pattern hex strings; the
  number path is still int-only").
- `desugar.rs` (2889 LoC) — add `Literal::Float` branch to
  whatever match-arms handle `Literal::Int` for desugar
  passthrough (likely a small, mechanical change).
- `pretty.rs` (204 LoC) — add `Literal::Float` arm; render as
  shortest round-trippable decimal (mirrors what
  `float_to_str` will do at runtime).

### `crates/ailang-surface/`

- `lex.rs` (264 LoC) — extend the digit-lead lexer arm. Today
  it parses `<digits>` as `Tok::Int(i64)`. New: peek for `.` or
  `e`/`E` after the integer part; if present, parse the full
  float form (per A2), `f64::from_str`, then `f64::to_bits()`
  to produce `Tok::Float(u64)`. New error variant
  `LexError::InvalidFloat { literal, start }` parallel to the
  existing `InvalidInteger`.
- `parse.rs` (2406 LoC) — accept `Tok::Float(bits)` where a
  literal is allowed; wrap as `Term::Lit { lit:
  Literal::Float { bits } }`.
- `print.rs` (734 LoC) — `write_lit` arm for `Literal::Float`:
  reconstruct `f64::from_bits(bits)`, then write shortest
  round-trippable decimal. **Output must be unambiguously a
  float in the surface lexer** — the printer always emits at
  least one of `.` or `e`/`E`, so `1.0` prints as `"1.0"` (or
  `"1e0"`), never as `"1"`. Otherwise `lex(print(1.0))` would
  re-parse as `Tok::Int(1)` and the round-trip property breaks.
  Round-trip property: `lex(print(L)) == L` for every Float
  literal — this becomes a regression test.

  Special-case bit patterns:
  - `+inf`, `-inf`, NaN cannot be expressed in surface form (per
    A2 — no NaN/Inf surface literal). The printer for these
    cases emits a clear non-round-trippable token like
    `(float-bits "7ff0000000000000")` or panics; the milestone
    picks the panic path, since a Float literal that arrived in
    the AST as NaN/Inf must have come from Form-A directly
    (surface lex cannot produce it), and the printer's job is
    surface output, not a Form-A escape hatch. Plan-time
    refinement.

### `crates/ailang-check/`

- `lib.rs` (4457 LoC) — `Literal::Float` is well-typed at
  `Type::float()`. Add the one-arm extension to whatever
  `Term::Lit` typing helper exists.
- `builtins.rs` (183 LoC) — three classes of change:
  1. **Widen** the existing arithmetic and comparison entries
     `+`/`-`/`*`/`/`/`<`/`<=`/`>`/`>=` from monomorphic Int to
     `forall a. (a, a) -> a` (or `... -> Bool`) — same shape
     as today's `==` entry. Existing `==`/`!=` entries
     unchanged in signature; their dispatch arm gets extended
     codegen-side.
  2. **Install** the new builtins: `neg` (polymorphic),
     `int_to_float`, `float_to_int_truncate`, `float_to_str`,
     `is_nan`, plus the three constants `nan`, `inf`,
     `neg_inf` (each a `Term::Var`-resolvable global at
     `Type::float()`, parallel to `__unreachable__`).
  3. **Install** the new effect op `io/print_float`.

  Extend `list()` accordingly so `ail builtins` reflects every
  added entry. The `list()` strings serve as the LLM-author's
  contract — they must be accurate after this iteration.

### `crates/ailang-codegen/`

- `synth.rs` (218 LoC) — five sites mirroring the Float
  primitive into the codegen-side type/op tables:
  1. `llvm_type` (line 14): add `"Float" => Ok("double".into())`
     arm parallel to the existing Int/Bool/Str/Unit arms.
  2. `builtin_ail_type` (line 61): widen the `+`/`-`/`*`/`/`,
     `<`/`<=`/`>`/`>=`, `!=` entries from `int_int_int` /
     `int_int_bool` to the polymorphic `forall a. (a, a) -> a`
     / `forall a. (a, a) -> Bool` shape (mirrors what
     `check/builtins.rs` installs). Add new entries for `neg`
     (polymorphic), `int_to_float`, `float_to_int_truncate`,
     `float_to_str`, `is_nan`, `nan`/`inf`/`neg_inf` (the
     constants resolve as zero-arg "values", not fns — the
     branch returns the bare `Type::float()` like
     `__unreachable__` returns `forall a. a`).
  3. `builtin_effect_op_ret` (line 118): add
     `"io/print_float" => Type::unit()`.
  4. `type_descriptor` (line 129): add `"Float" => "Fl"` arm.
     Two letters because the single letter `F` is taken as
     the ADT-name prefix (`FList`, `FFoo`); `Fl` is unambiguous
     and short.
  5. `builtin_binop` (line 167): this monomorphic-Int table
     becomes a transitional artefact. Either convert it into a
     type-dispatched helper that takes the operand `Type` and
     returns the matching `(instr, llvm_ty)` pair, or remove
     the table entirely and let the new dispatch helper in
     `lib.rs` handle every site. Plan-time call.

- `lib.rs` (2877 LoC) — seven lowering changes:
  1. **Float literal** (`Literal::Float { bits }`) → emit
     a `double` constant. The idiomatic LLVM form for a
     bit-exact float constant is the hex-float literal
     `double 0x4014000000000000` (LangRef: "the only time
     hexadecimal floating point constants are required ...
     is when a floating point constant must be emitted but
     it cannot be represented as a decimal floating point
     number in a reasonable number of digits", which covers
     NaN, ±Inf, and any non-trivial decimal). Use this form
     uniformly so every Float literal in the IR has the same
     shape. Sites: every place `Literal::Int { value }` is
     matched today (lines 918, 1215).
  2. **Widen arithmetic dispatch.** `+`/`-`/`*`/`/` are
     today lowered as monomorphic Int instructions
     (line 1745 region) using the `synth::builtin_binop`
     table. Convert the lowering site into a type-dispatched
     helper analogous to the existing `==` dispatch
     (`lib.rs:2244-2266`): Int arm emits `add/sub/mul/sdiv
     i64`, Float arm emits `fadd/fsub/fmul/fdiv double`,
     anything else fails with `"<op> not supported for type
     X"`. The existing test at `lib.rs:2627-2630` (which
     pins `define i64 @ail_t_add(i64 %arg_a, i64 %arg_b)` and
     `add i64 %arg_a, %arg_b`) must stay GREEN.
  3. **Widen comparison dispatch.** `<`/`<=`/`>`/`>=`/`!=`
     get the same treatment: Int arm `icmp s{lt,le,gt,ge} i64`
     / `icmp ne i64`, Float arm `fcmp o{lt,le,gt,ge} double`
     / **`fcmp une double` for `!=`** (NOT `fcmp one` —
     `one` is "ordered and not equal" and returns `false`
     for `nan != nan`, which violates IEEE; `une` is
     "unordered or not equal" and matches IEEE / Rust).
  4. **`==` Float arm** in the existing dispatch
     (line 2263 region) → `fcmp oeq double` for the `Float`
     case, alongside the existing arms. (`!=` is handled
     under #3 above.)
  5. **`neg` polymorphic** — Int arm `sub i64 0, %x`, Float
     arm `fneg double %x`. The `fneg` instruction (LLVM 8+)
     correctly handles `-0.0` — `0.0 - 0.0` is `+0.0` per
     IEEE rounding, so a `fsub double 0.0, %x` desugar would
     wrongly produce `+0.0` for `neg(+0.0)` instead of
     `-0.0`. Reject other types with the dispatch's standard
     diagnostic.
  6. **Conversions and IO**:
     - `int_to_float` → `sitofp i64 ... to double`.
     - `float_to_int_truncate` → `@llvm.fptosi.sat.i64.f64`
       intrinsic (LLVM 12+; AILang targets clang 22, so
       always available). Spec semantics — NaN → 0,
       +∞ → i64::MAX, -∞ → i64::MIN, finite-out-of-range
       saturates, finite-in-range truncates toward zero —
       are exactly the intrinsic's documented semantics, no
       wrapping needed.
     - `is_nan` → `fcmp uno double %x, %x` (returns `i1`,
       which is AILang `Bool` directly per `synth.rs:18`).
     - `float_to_str` → call into runtime C glue
       `@ail_float_to_str`.
     - `io/print_float` → parallel to `io/print_int`
       (line 2150 region) → call into runtime C glue
       `@ail_print_float`.
  7. **Float constants** `nan`/`inf`/`neg_inf` lower as
     `Term::Var` references resolving directly to a `double`
     SSA constant at the use site (LLVM hex-float literal):
     - `nan` → `double 0x7FF8000000000000` (canonical qNaN)
     - `inf` → `double 0x7FF0000000000000`
     - `neg_inf` → `double 0xFFF0000000000000`

     This is **unlike** the `__unreachable__` lowering, which
     emits the `unreachable` *terminator instruction*.
     Constants are SSA *values*, so the dispatch arm in
     `lower_var` (or wherever `Var` resolution lives) returns
     `(value-string, "double")` directly without going through
     a global declaration.

- **ADT / container slot layout** — both `i64` and `double`
  occupy 8 bytes, but they are distinct LLVM types. Two cases:
  - **Monomorphisation produces concrete slot types.** If the
    mono pass (`crates/ailang-check/src/mono.rs`) lowers
    `List<Float>` to a concrete `List_Fl` whose field type is
    `double`, no bitcast is needed. The `type_descriptor`
    extension above (`Fl`) ensures the mangled name is
    distinct from `List<Int>` (`List_I`).
  - **Polymorphic / type-erased slots, if any.** If any
    container path uses `i64` or `ptr` as a generic 8-byte
    slot (e.g. an erased `Box<a>` that doesn't get
    monomorphised), Float values traversing it need
    `bitcast double to i64` going in and `bitcast i64 to
    double` coming out. The plan verifies which case applies
    by reading `mono.rs` and `lib.rs::lower_ctor` /
    `lower_field_access`. The expected outcome is "fully
    monomorphised, no bitcasts needed", but this is a
    *check*, not an assumption.

### `crates/ailang-prose/`

- `lib.rs` (2125 LoC) — Form-A ↔ Form-B prose mapping for
  `Literal::Float`. Form-B prose says e.g. "the number 1.5";
  Form-A round-trips through bits. Mirrors the existing
  `Literal::Int` prose treatment.

### `runtime/`

- New file `runtime/print_float.c` (or extend an existing C
  file) — two functions:
  - `void ail_print_float(double v)` — write shortest
    round-trippable decimal + newline.
  - `const char *ail_float_to_str(double v)` — return a
    heap-allocated AILang `Str` of the shortest
    round-trippable decimal (no newline). Refcounted as any
    other `Str` in the runtime.

  Implementation: vendor a small `ryu`-style routine, or — if
  simpler — use `snprintf("%.17g", v)` for the milestone and
  revisit if the redundancy is a problem. Plan-time call.
- The RC runtime (`rc.c`, `bump.c`) is **not touched** by the
  Float value path itself. Float is a value type with no heap
  allocation per literal. The `ail_float_to_str` glue allocates
  a `Str`, but uses the existing `Str` runtime path.

### `crates/ail/` (CLI)

- `ail builtins` automatically picks up the twelve new entries
  via `builtins::list()` — no CLI-level change needed.

### `docs/DESIGN.md`

- §"Data model" `Literal` enumeration: add the `float` kind
  with the `bits` hex-string field documented.
- §"Data model" — extend the §"Type constructors" / primitives
  list to include `Float`.
- §"Float semantics" — new top-level subsection (~50-80 lines)
  containing A5 (determinism contract) and pointers to the
  builtins for arithmetic / comparison / conversion / IO.
- §"Form-B surface" — extend the literal grammar production to
  include the float forms from A2.
- §"Built-in operations" — add the twelve new entries.

### `docs/JOURNAL.md`

- Per-iteration entries during implementation.
- Milestone-close entry summarising what landed.

## Data flow

The path of a float literal through the pipeline, end-to-end:

```
surface text:   1.5
                  ↓ ailang-surface/lex.rs
Tok::Float(0x3ff8000000000000)
                  ↓ ailang-surface/parse.rs
Term::Lit { lit: Literal::Float { bits: 0x3ff8000000000000 } }
                  ↓ ailang-surface/print.rs (round-trip)
surface text:   1.5
                  ↓ ailang-core/canonical.rs
Form-A bytes:   {"lit":{"bits":"3ff8000000000000","kind":"float"},"t":"lit"}
                  ↓ ailang-core/hash.rs
def_hash:       <16-hex stable>
                  ↓ ailang-check/lib.rs
Type::float()
                  ↓ ailang-codegen/lib.rs
LLVM IR:        store double 0x3FF8000000000000, ptr %slot
                  ↓ clang -O2
machine code:   movsd xmm0, qword ptr [rip + .LCPI...]
```

Every stage observable; every stage round-trippable; every
canonical-JSON byte stable across runs and `serde_json` versions.

For an arithmetic op `(fadd a b)`:

```
surface text:   (fadd a b)
                  ↓ Term::App { fn: Var "fadd", args: [a, b] }
                  ↓ ailang-check resolves "fadd" → builtin (Float, Float) -> Float
                  ↓ ailang-codegen sees builtin "fadd" → emit `%r = fadd double %a, %b`
```

No magic dispatch — the builtin name is the dispatch key, like
`int_add` aka `+` is today.

## Error handling

Lexer errors:

- `LexError::InvalidFloat { literal, start }` — raised when a
  digit-lead token contains `.` or `e/E` but `f64::from_str`
  rejects it (e.g. `1..5`, `1.5e`, `1.5e++3`). Message:
  `"invalid float literal `<literal>`"`.

Type errors:

- Float operators on non-Float arguments: standard "expected
  Float, got X" unification error from the existing typechecker
  — no new diagnostic needed.

Codegen errors:

- A Float literal whose `bits` cannot fit in 16 hex characters
  is impossible by construction (`u64` is exactly 16 hex
  characters), so no runtime check is added.
- Form-A deserialisation rejects malformed hex (length ≠ 16,
  non-hex characters) at the serde layer; the resulting
  `serde_json::Error` propagates up the existing `ail check`
  error path.

Runtime errors:

- None per literal. Arithmetic operations follow IEEE: division
  by zero produces `±Inf` or `NaN`; overflow produces `±Inf`;
  invalid ops produce NaN. **No traps**, no Rust-style panics.
  This is the IEEE-conformant choice committed in user-fixed
  constraint #2.

## Testing strategy

Per-iteration RED-first tests in `tests/` (unit) and
`bench/`-adjacent E2E. The plan will sequence these; the spec
fixes the *property set* that must be covered.

### Round-trip properties (lex/parse/print/hash)

- `lex(print(L)) == L` for every Float literal — covers
  shortest-round-trippable decimal output.
- Form-A bytes for `Literal::Float { bits }` are exactly
  `{"bits":"<16-hex>","kind":"float"}` — string-encoded, never
  JSON-number-encoded.
- `def_hash` of a module containing a Float literal is stable
  across runs and across `serde_json` patch versions (mirrors
  the existing Int regression test).

### IEEE-conformance properties

- `(+ 0.1 0.2)` produces the exact `bits` of
  `0.1_f64 + 0.2_f64` (i.e. `bits == 0x3fd3333333333334`, not
  `0x3fd3333333333333`). A single `fadd` cannot be FMA-contracted
  (no `c` operand to absorb), so the result is bit-stable per A5.
- `(== nan nan)` returns `false`. `(!= nan nan)` returns `true`.
- `<`, `<=`, `>`, `>=` all return `false` when either
  argument is NaN (ordered comparisons via `fcmp o*`).
- `(/ 1.0 0.0)` produces `+inf` (bits `7ff0000000000000`);
  `(/ -1.0 0.0)` produces `-inf` (bits `fff0000000000000`);
  `(/ 0.0 0.0)` produces *some* NaN (test asserts
  `(is_nan result) == true`, **not** specific NaN bits —
  A5 leaves the qNaN payload unspecified).
- `(is_nan nan) == true`. `(is_nan 1.0) == false`.
  `(is_nan inf) == false`. `(is_nan neg_inf) == false`.
- `+0.0` and `-0.0` hash distinctly in Form-A but compare equal
  via `==`.

### Conversion properties

- `int_to_float` exact for `|n| < 2^53`, rounds half-to-even
  beyond.
- `float_to_int_truncate` total: `nan → 0`, `+inf → i64::MAX`,
  `-inf → i64::MIN`, finite values truncate toward zero.

### Codegen / runtime smoke

- An `examples/floats.ail.json` fixture that exercises
  literal, arithmetic, comparison, conversion, and
  `io/print_float`; runs through the full
  `ail build → executable → stdout-check` chain.

### Bench regression

- `bench/check.py`, `bench/compile_check.py`,
  `bench/cross_lang.py` must stay GREEN. Float doesn't touch
  the Int code paths, so regressions are not expected; running
  the harnesses is a sanity gate.

### Spec-drift test

- `crates/ailang-core/tests/design_schema_drift.rs` — extend
  the anchor list to include the new `"kind":"float"` and
  `"Float"` primitive name. The drift test guards against
  removing them silently from `DESIGN.md`.

## Acceptance criteria

The milestone is closeable when **all** of the following hold:

1. `crates/ailang-core/src/primitives.rs::is_primitive_name`
   returns `true` for `"Float"`. The lockstep test passes.
2. `Literal::Float { bits: u64 }` is serialised as
   `{"bits":"<16-hex>","kind":"float"}` in canonical JSON. The
   round-trip test passes.
3. `ail builtins` output reflects:
   (a) widened signatures for `+`, `-`, `*`, `/`, `<`, `<=`,
       `>`, `>=` (now `forall a. (a, a) -> a` /
       `forall a. (a, a) -> Bool`);
   (b) new builtins: `neg`, `int_to_float`,
       `float_to_int_truncate`, `float_to_str`, `is_nan`;
   (c) new constants: `nan`, `inf`, `neg_inf`;
   (d) new effect op: `io/print_float`.
4. `examples/floats.ail.json` builds, runs, and produces the
   expected stdout (printed floats round-trip the literal
   forms).
5. `cargo test --workspace` is GREEN.
6. `bench/check.py`, `bench/compile_check.py`,
   `bench/cross_lang.py` exit 0.
7. `docs/DESIGN.md` carries the new §"Float semantics"
   subsection, the extended `Literal` enumeration, the
   extended primitives list, and the twelve builtin signatures.
   The `design_schema_drift.rs` test extends to cover the new
   anchors.
8. `cargo doc --no-deps` warning count does not increase from
   the milestone-open baseline (16 warnings; this is the
   queued rustdoc-sweep baseline).
9. JOURNAL milestone-close entry written.
10. `docs/roadmap.md` Floats entry flipped from `[~]` to `[x]`;
    Post-22 Prelude unblocked (its `depends on: Floats` line
    can be removed in the same commit or in the Prelude's
    brainstorm step — orchestrator call).

Out of scope, explicitly:

- `Show Float` / `Eq Float` / `Ord Float` instances. (Float
  gets `Show` in the next milestone; `Eq` and `Ord` will
  *intentionally* not exist for `Float` because of A5 +
  user-fixed constraint #2.)
- Polymorphic numeric class (`Num`). The hardcoded
  `{Int, Float}` spec-case in the typechecker is transitional
  scaffolding; replaced by a proper `Num a` constraint when
  typeclass machinery picks up arithmetic in 22c.
- `f32`.
- `fmod` / IEEE-`remainder`. `%` stays Int-only this milestone.
- `print` rewiring through `Show.show` — that is Post-22
  Prelude.
- Pattern-matching on Float literals (`Pattern::Lit { lit:
  Literal::Float { ... } }`). Semantically dubious — IEEE `==`
  semantics mean `NaN` never matches any literal pattern, and
  `0.1` in a pattern matches *only* the parsed bit pattern
  `0x3fb999999999999a`, not "approximately 0.1". The plan
  decides between (a) hard-reject Float in `Pattern::Lit` at
  the typechecker (recommended), or (b) allow it with an
  IEEE-`==` semantics, which the LLM-author has to remember.
  Either way: this milestone explicitly does NOT introduce a
  Float-pattern *idiom* — the documented way to discriminate
  Floats is via the comparison operators (`<`/`>`/...) and
  `(is_nan x)`.

## Notes for the plan

The plan should sequence iterations roughly:

- **Iteration 1**: AST + canonical + primitives (the schema
  layer). Pure schema, RED-first by canonical-bytes test for
  `Literal::Float`.
- **Iteration 2**: Surface lex + parse + print round-trip.
  RED-first by `lex(print(L)) == L` property.
- **Iteration 3**: Type + builtins install. Two distinct
  sub-tasks:
  (a) **widen** existing `+`/`-`/`*`/`/`/`<`/`<=`/`>`/`>=` to
      polymorphic; **don't break** existing Int-only fixtures;
  (b) install new builtins (`neg`, conversions, `is_nan`,
      constants) and `io/print_float`.
  RED-first by typecheck unit test on `(+ 1.0 2.0) : Float`
  AND `(+ 1 2) : Int` (regression).
- **Iteration 4**: Codegen widening + Float lowering paths.
  Same widen-vs-add split as iteration 3 — codegen for
  `+`/`-`/`*`/`/` becomes type-dispatched, plus Float arms for
  comparison, conversion, IO, and constants. RED-first by E2E
  `examples/floats.ail.json` AND existing Int E2E fixtures
  staying GREEN (regression gate).
- **Iteration 5**: Prose + DESIGN.md + drift-test extension +
  rustdoc.

Note the regression-gate emphasis on iterations 3 and 4: this
milestone *widens* operators that are today monomorphic. Every
existing Int-using fixture must keep working bit-identical.
The plan should pin a "no Int regression" property explicitly.

Iteration boundaries are the plan's call. The five-cluster
shape above is the spec's scope estimate, not a binding
sequence.