AILang/docs/plans/0020-floats-5-prose-design.md

# Floats Iteration 5 — Prose + DESIGN.md + Milestone Close (Implementation Plan)

> **Parent spec:** `docs/specs/0005-floats.md` (committed
> `e37366f`, approved 2026-05-10) — section A5 (determinism
> contract) + the `crates/ailang-prose/` Components subsection.
>
> **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement`
> to run this plan. Steps use `- [ ]` checkboxes for tracking.

**Goal:** Replace the iter-1 prose `unimplemented!("Floats milestone
iter 5: prose")` arm with a Float renderer matching the surface-print
shape from iter 2; add §"Float semantics" to DESIGN.md per spec A5;
update DESIGN.md's "supported primitive types" line and the builtins
list to include Float entries; mark Floats `[x]` in roadmap; write
the milestone-close JOURNAL entry.

**Architecture:** Prose render is one-way (Form-A AST → Form-B text).
The Float arm in `write_lit` reuses the same `to_string + .0-suffix-
fallback` shape as `crates/ailang-surface/src/print.rs::write_float_lit`
from iter 2 — except non-finite bits render as the Mainstream-language
spellings `NaN` / `+Inf` / `-Inf` rather than panicking, because prose
is a one-way render and CAN handle Form-A values that surface lex
cannot produce. DESIGN.md additions sit alongside the existing
"What is supported" list and add a new §"Float semantics" subsection.

**Tech Stack:** `crates/ailang-prose/src/lib.rs`, `docs/DESIGN.md`,
`docs/roadmap.md`, `docs/JOURNAL.md`. No code outside the prose
crate.

**No-regression invariant:** `cargo test --workspace` GREEN. The
iter-1 spec_drift / design_schema_drift anchors for `Float`
(`` `FLOAT` `` in form_a.md, `"kind": "float"` in DESIGN.md JSON-
schema block) are already in place since iter 1.1 — they stay
unchanged. The new DESIGN.md additions do not perturb the existing
anchors.

---

## Files this plan creates or modifies

- Modify: `crates/ailang-prose/src/lib.rs` — replace the
  `Literal::Float { .. } => unimplemented!(...)` arm at line 917
  with a real renderer; add `mod tests` Float coverage.
- Modify: `docs/DESIGN.md` — line 2034 (primitive types list) +
  lines 2038-2059 (builtins list) + insert new §"Float semantics"
  subsection before §"What is not (yet) supported".
- Modify: `docs/roadmap.md` — flip Floats `[~]` → `[x]`; drop
  `depends on: Floats` from Post-22 Prelude.
- Modify: `docs/JOURNAL.md` — append iter-5 close entry AND
  separate milestone-close entry summarising the whole 5-iteration
  arc.

No file outside this list is touched.

---

## Task 1: Prose renderer for `Literal::Float`

**Files:**
- Modify: `crates/ailang-prose/src/lib.rs:911-919` (write_lit) +
  add a private helper `write_float_lit(out, bits)`; add a `mod
  tests` block (or extend the existing one — verify which).

- [ ] **Step 1: Find the test mod or confirm absence**

Run: `grep -n "^#\[cfg(test)\]\|^mod tests" crates/ailang-prose/src/lib.rs`
Determine where to add the test. If a `mod tests` already exists at
EOF, append to it. If not, create one.

- [ ] **Step 2: Write the RED test**

In the test mod, append:

```rust
/// Floats milestone iter 5.1: prose renders Float literals as
/// surface-style decimal text. Finite values use shortest
/// round-trippable decimal with `.0` suffix when neither `.` nor
/// `e`/`E` is in the rendered string (parallel to surface print).
/// Non-finite (NaN, ±Inf) render as the Mainstream-language
/// spellings — `NaN`, `+Inf`, `-Inf` — because prose is a one-way
/// render and the surface lex grammar's no-NaN/Inf restriction
/// does not apply to it.
#[test]
fn renders_float_literal_finite() {
    use ailang_core::ast::*;
    let t = Term::Lit { lit: Literal::Float { bits: 0x3ff8_0000_0000_0000u64 } };
    let s = render_term(&t);
    assert_eq!(s, "1.5");

    let t = Term::Lit { lit: Literal::Float { bits: 0x4024_0000_0000_0000u64 } };
    let s = render_term(&t);
    assert_eq!(s, "10.0");
}

#[test]
fn renders_float_literal_signed_zero() {
    use ailang_core::ast::*;
    let pos = Term::Lit { lit: Literal::Float { bits: 0x0u64 } };
    assert_eq!(render_term(&pos), "0.0");
    let neg = Term::Lit { lit: Literal::Float { bits: 0x8000_0000_0000_0000u64 } };
    assert_eq!(render_term(&neg), "-0.0");
}

#[test]
fn renders_float_literal_non_finite() {
    use ailang_core::ast::*;
    let nan = Term::Lit { lit: Literal::Float { bits: 0x7ff8_0000_0000_0000u64 } };
    assert_eq!(render_term(&nan), "NaN");
    let pos_inf = Term::Lit { lit: Literal::Float { bits: 0x7ff0_0000_0000_0000u64 } };
    assert_eq!(render_term(&pos_inf), "+Inf");
    let neg_inf = Term::Lit { lit: Literal::Float { bits: 0xfff0_0000_0000_0000u64 } };
    assert_eq!(render_term(&neg_inf), "-Inf");
}
```

If `render_term` is private or absent, look for the equivalent
helper at the top of `mod tests` (the existing tests use it per
the `grep` from earlier surveying — `render_term(&Term::Lit { lit:
Literal::Int { value: 42 } })` returned `"42"`).

- [ ] **Step 3: Verify RED**

Run: `cargo test -p ailang-prose --lib renders_float_literal`
Expected: PANIC at the iter-1 `unimplemented!("Floats milestone
iter 5: prose")` arm in `write_lit`.

- [ ] **Step 4: Add the `write_float_lit` helper + replace the arm**

In `crates/ailang-prose/src/lib.rs`, immediately BEFORE `write_lit`
(around line 911), add:

```rust
/// Floats milestone iter 5: render a Float literal's bit pattern
/// as surface-style decimal text. Finite values use Grisu3
/// (`f64::to_string`) with a `.0` suffix when neither `.` nor
/// `e`/`E` appears, parallel to
/// `crates/ailang-surface/src/print.rs::write_float_lit`. Non-finite
/// values render as `NaN` / `+Inf` / `-Inf` — these are valid in
/// Form-A (the canonical bytes carry the bit pattern) but cannot
/// be expressed in surface lex; prose is one-way render, so naming
/// them after the Mainstream-language spellings is more useful
/// than a panic or a `(float-bits hex)` placeholder.
fn write_float_lit(out: &mut String, bits: u64) {
    let f = f64::from_bits(bits);
    if f.is_nan() {
        out.push_str("NaN");
        return;
    }
    if f == f64::INFINITY {
        out.push_str("+Inf");
        return;
    }
    if f == f64::NEG_INFINITY {
        out.push_str("-Inf");
        return;
    }
    let s = f.to_string();
    out.push_str(&s);
    if !s.contains('.') && !s.contains('e') && !s.contains('E') {
        out.push_str(".0");
    }
}
```

Then replace the iter-1 arm at `write_lit` (line 917):

```rust
        Literal::Float { bits } => write_float_lit(out, *bits),
```

- [ ] **Step 5: Verify RED tests now GREEN**

Run: `cargo test -p ailang-prose --lib renders_float_literal`
Expected: all 3 tests PASS.

- [ ] **Step 6: Verify no `unimplemented!` arm with the iter-5 string remains**

Run: `grep -rn "Floats milestone iter 5: prose" crates/`
Expected: zero hits.

- [ ] **Step 7: Verify no workspace regression**

Run: `cargo test --workspace`
Expected: all 402+ tests pass (= 402 prior + 3 new), 0 failed.

- [ ] **Step 8: Commit**

```bash
git add crates/ailang-prose/src/lib.rs
git commit -m "floats iter 5.1: prose renders Float literals (finite + NaN/Inf)"
```

---

## Task 2: DESIGN.md — extend supported primitives + builtins lists

**Files:**
- Modify: `docs/DESIGN.md:2034` (primitive types list) +
  lines 2038-2059 (builtins list).

- [ ] **Step 1: Update line 2034 to include Float**

In `docs/DESIGN.md`, line 2034, replace:

```
- Int, Bool, Unit, **Str** as primitive types.
```

with:

```
- Int, Bool, Unit, **Str**, **Float** as primitive types.
```

- [ ] **Step 2: Refresh the builtins list at lines 2038-2059**

In `docs/DESIGN.md`, replace the `**Builtins.**` block at lines
2038-2059 with the post-Floats current shape:

```
- **Builtins.** Arithmetic operators (`+`, `-`, `*`, `/`) of type
  `forall a. (a, a) -> a` (codegen-restricted to `{Int, Float}`);
  `%` of type `(Int, Int) -> Int` (Int-only — `fmod` semantics for
  Float deferred); ordering operators and `!=` (`!=`, `<`, `<=`,
  `>`, `>=`) of type `forall a. (a, a) -> Bool` (codegen-restricted
  to `{Int, Float}`); polymorphic `neg : forall a. (a) -> a`
  (codegen-restricted to `{Int, Float}`; Float arm uses LLVM
  `fneg double` for correct `-0.0` handling); logical
  `not : (Bool) -> Bool`; conversions
  `int_to_float : (Int) -> Float`,
  `float_to_int_truncate : (Float) -> Int` (saturating, NaN → 0),
  `float_to_str : (Float) -> Str` (codegen lowering deferred —
  symbol installed but errors at codegen pending runtime Str
  allocation); inspection `is_nan : (Float) -> Bool` (LLVM
  `fcmp uno`); Float bit-pattern constants `nan : Float`,
  `inf : Float`, `neg_inf : Float` (resolved as bare values, lower
  to direct hex-float `double` SSA constants at use site); the IO
  effect ops (`io/print_int|bool|str|float`); **`==` : forall a.
  (a, a) -> Bool**; and **`__unreachable__ : forall a. a`**.
  - **`==` is polymorphic.** The typechecker accepts
    `==` at any type whose two sides agree (the rigid `a` of the
    `Forall` is unified by HM at the use site). Codegen
    monomorphises and dispatches on the resolved AIL arg type:
    `Int` → `icmp eq i64`; `Bool` → `icmp eq i1`;
    `Str` → `call @strcmp(ptr, ptr)` then `icmp eq i32 0`
    (`@strcmp` is declared in the LLVM IR header alongside
    `@printf` / `@GC_malloc`); `Unit` → constant `i1 true`
    (Unit has a single inhabitant; both sides are still
    evaluated for any side effects); `Float` → `fcmp oeq double`.
    ADT and `Fn` arg types are rejected at codegen with a
    `CodegenError::Internal` mentioning `==` and the offending
    type — neither has a canonical structural-equality scheme
    yet, and the language deliberately does not silently elide
    the check. **`!=` for Float uses `fcmp UNE double` (NOT
    `one`)** — `one` is "ordered and not equal" and would return
    false for `nan != nan`, violating IEEE-`!=`.
  - **`__unreachable__`** is a polymorphic bottom value: a use of
    `__unreachable__` typechecks against any expected type at
    the use site and codegens to the LLVM `unreachable`
    instruction (UB if ever executed). It is the chain
    machinery's deepest fall-through for matches that the
    typechecker proved exhaustive, and it is available to user
    code as an explicit panic primitive
    (`(if cond __unreachable__ ...)` for assertions or
    impossible branches). Reference site is
    `Term::Var { name = "__unreachable__" }` / form-A bare
    `__unreachable__`.
```

The widening + new entries are folded in; the existing prose about
`==` polymorphism gains a `Float → fcmp oeq double` line; the
`!=` UNE-not-one note is added; the existing `__unreachable__`
prose is preserved verbatim.

- [ ] **Step 3: Verify DESIGN.md still parses (markdown render)**

Run: `cargo test -p ailang-core --test design_schema_drift`
Expected: GREEN — the `"kind": "float"` anchor (added in iter 1)
is still present in the JSON-schema block, unchanged. The new
prose only adds; nothing is removed.

- [ ] **Step 4: Commit**

```bash
git add docs/DESIGN.md
git commit -m "floats iter 5.2: DESIGN.md — Float in primitive types + refreshed builtins list"
```

---

## Task 3: DESIGN.md — add §"Float semantics" subsection

**Files:**
- Modify: `docs/DESIGN.md` — insert new top-level section
  immediately BEFORE `## What is not (yet) supported` (line 2006).

- [ ] **Step 1: Insert the new subsection**

In `docs/DESIGN.md`, immediately before `## What is not (yet) supported`
(line 2006), insert:

```markdown
## Float semantics

`Float` is IEEE-754 binary64 (LLVM `double`). One float type ships;
no `f32` variant. The runtime / codegen contract:

**Guaranteed:**

- Every individual builtin (`+`/`-`/`*`/`/`/`neg`/`<`/`==`/...) lowers
  to a single LLVM IR instruction on the Float arm:
  `fadd/fsub/fmul/fdiv double`, `fneg double`, `fcmp olt/ole/ogt/oge
  double`, `fcmp oeq double`, `fcmp une double` (for `!=`). On a
  fixed `(target triple, LLVM version)` pair, the bit pattern of
  the result of any single op is reproducible.
- NaN and ±Inf propagate per IEEE 754 — no silent collapse to zero,
  no trap. Arithmetic on a NaN operand produces NaN; division by
  zero produces ±Inf; `0.0 / 0.0` produces NaN.
- `-0.0` and `+0.0` are distinct bit patterns at the canonical-JSON
  hash level (`{"bits":"0000000000000000",...}` vs
  `{"bits":"8000000000000000",...}` — distinct `def_hash`s) but
  compare equal via `==` per IEEE (`fcmp oeq double` returns true
  for `+0 == -0`). This asymmetry is the correct IEEE behaviour;
  it does mean `def_hash`-equality is finer than `==`-equality on
  Float.
- `==` returns `false` whenever either operand is NaN
  (`fcmp oeq` is the ordered-equal predicate; ordered = both
  operands non-NaN).
- `!=` returns `true` whenever either operand is NaN (`fcmp une`
  is the unordered-or-not-equal predicate). This matches Rust
  `f64::ne` and IEEE-`!=` exactly.
- `is_nan` (`fcmp uno double %x, %x`) returns `true` iff `x` is
  NaN. Bit-pattern-based NaN detection without dependence on the
  payload bits.
- `int_to_float` (`sitofp`) is exact for `|n| < 2^53`,
  round-to-nearest-even otherwise.
- `float_to_int_truncate` (`@llvm.fptosi.sat.i64.f64`) is total:
  NaN → 0, +Inf → i64::MAX, -Inf → i64::MIN, finite-out-of-range
  saturates, finite-in-range truncates toward zero. Matches Rust
  `as i64` semantics (since 1.45).

**Unspecified:**

- FMA contraction. LLVM may fold `fadd (fmul a b) c` into
  `fma a b c`. Bit results may differ between an op-emitted-in-
  isolation pattern and an op-folded-into-FMA pattern.
- Reassociation. The compiler may reorder a chain like
  `(a + b) + c` into `a + (b + c)`, producing a bit-different
  result on numerically sensitive inputs.
- Subnormal flushing modes. If the target enables FTZ (flush-to-
  zero) or DAZ (denormals-are-zero), subnormal results round to
  zero; AILang does not enable these flags but does not forbid the
  target from doing so.
- The exact NaN bit pattern produced by an op. Any quiet NaN bit
  pattern is conformant; `0.0 / 0.0` may produce `0x7ff8_0000_
  0000_0000` on one target and a different qNaN on another.

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 `-ffp-contract=off` plus per-op intrinsic
selection — out of scope for the milestone; revisit only if a real
use case appears.

**Form-A serialisation:** Float literals carry the IEEE-754
bit pattern as a 16-character lowercase hex string in the canonical
JSON: `{"kind":"float","bits":"<16-hex>"}`. Routing through the
JSON *string* path (not `serde_json::Number`) preserves bit
stability across `serde_json` versions and lets NaN / ±Inf
round-trip through Form-A — JSON numbers cannot represent them.

**Pattern matching:** `Pattern::Lit` on `Literal::Float` is hard-
rejected at typecheck (`CheckError::FloatPatternNotAllowed`). IEEE
semantics make Float patterns semantically dubious — NaN never
matches via IEEE-`==`, and bit-exact equality is rarely what an
LLM-author wants. Use ordering operators (`<`, `>`, ...) and
`is_nan` to discriminate Floats.

`float_to_str` (Float → Str) is **type-installed but codegen-
deferred** to a follow-up milestone: it requires runtime-allocated
`Str` (the current Str path uses only static `@.str_*` globals;
no malloc-backed dynamic-Str infrastructure). Calling it
typechecks but produces a structured `CodegenError::Internal`.
```

- [ ] **Step 2: Verify markdown still parses cleanly**

Run: `cargo doc --no-deps -p ailang-core 2>&1 | head -10`
Expected: no new warnings (rustdoc doesn't see DESIGN.md, but the
test sweeps any markdown-formatting glitches that might have been
introduced; a clean output here is reassurance, not a hard test).

- [ ] **Step 3: Verify the drift test still passes**

Run: `cargo test -p ailang-core --test design_schema_drift`
Expected: GREEN. The new section adds prose; no anchor is removed.

- [ ] **Step 4: Commit**

```bash
git add docs/DESIGN.md
git commit -m "floats iter 5.3: DESIGN.md — new §Float semantics subsection (A5 determinism contract)"
```

---

## Task 4: Roadmap — mark Floats `[x]`, drop Post-22 Prelude dependency

**Files:**
- Modify: `docs/roadmap.md` — Floats entry P0 → mark `[x]`;
  Post-22 Prelude P1 → drop `depends on: Floats` line.

- [ ] **Step 1: Mark the Floats milestone done**

In `docs/roadmap.md`, line 36 currently reads:

```
- [~] **\[milestone\]** Floats — introduce `Float` as IEEE-754
```

Change to:

```
- [x] **\[milestone\]** Floats — introduce `Float` as IEEE-754
```

(Just the `~` → `x` swap; the rest of the entry stays for now —
will be removed in a follow-up tidy once the milestone-close
JOURNAL entry is enough context.)

- [ ] **Step 2: Drop the Post-22 Prelude dependency line**

In `docs/roadmap.md`, locate the Post-22 Prelude entry (P1, around
line 53). Remove the lines:

```
  - depends on: Floats (the partial-Eq/Ord story for Float must be
    settled before the Prelude classes ship, so the Prelude can
    decide what's instanced and what isn't)
```

The Prelude is now unblocked; the Floats commitment (no `Eq` /
`Ord` for Float, only `Show`) is settled and documented in DESIGN.md
§"Float semantics".

- [ ] **Step 3: Commit**

```bash
git add docs/roadmap.md
git commit -m "floats iter 5.4: roadmap — mark Floats [x] + unblock Post-22 Prelude"
```

---

## Task 5: JOURNAL — iter-5 close + milestone-close

**Files:**
- Modify: `docs/JOURNAL.md` — append TWO entries: iter-5 close
  (small, mirrors per-task subjects), and a separate milestone-
  close summary covering the whole 5-iteration arc.

- [ ] **Step 1: Append the iter-5 close entry**

In `docs/JOURNAL.md`, append at file end:

```markdown
## 2026-05-10 — Iteration Floats.5: prose + DESIGN.md + milestone close

Replaced the iter-1 prose `unimplemented!("Floats milestone iter 5:
prose")` arm with `write_float_lit` — finite values render as
shortest round-trippable decimal with `.0` suffix (parallel to
surface print); non-finite values render as `NaN` / `+Inf` /
`-Inf` (Mainstream-language spellings) because prose is one-way
render and CAN handle Form-A NaN / ±Inf bits that surface lex
cannot produce.

DESIGN.md gained a new top-level §"Float semantics" subsection per
spec section A5: IEEE-754 binary64 commitment, per-op bit stability
on fixed (target, LLVM), NaN / ±Inf propagation, `-0`/`+0` hash-vs-
equality asymmetry, FMA-contraction / reassociation / subnormal
flushing UNSPECIFIED, conversions semantics, Form-A serialisation
shape, Pattern::Lit::Float rejection rationale, and the
`float_to_str` deferred-codegen note. The "What is supported"
bullet list at line 2034 was extended to mention `Float` as a
primitive type; the builtins list was refreshed to include the
widened ops (`forall a. (a, a) -> a`), the 5 new fn builtins, the
3 Float constants, and the 4th IO effect op (`io/print_float`).

Roadmap flipped Floats from `[~]` to `[x]`; Post-22 Prelude is
unblocked (the `depends on: Floats` line dropped — the partial-
Eq/Ord-for-Float story is now settled and documented in
§"Float semantics", so the Prelude milestone can decide what's
instanced without bouncing back to Float design).

Per-task commits:

- `<sha-5.1>` floats iter 5.1: prose renders Float literals (finite + NaN/Inf)
- `<sha-5.2>` floats iter 5.2: DESIGN.md — Float in primitive types + refreshed builtins list
- `<sha-5.3>` floats iter 5.3: DESIGN.md — new §Float semantics subsection (A5 determinism contract)
- `<sha-5.4>` floats iter 5.4: roadmap — mark Floats [x] + unblock Post-22 Prelude
```

Replace each `<sha-5.N>` with the actual commit SHA at write time.

- [ ] **Step 2: Append the milestone-close entry**

In `docs/JOURNAL.md`, immediately AFTER the iter-5 close section,
append:

```markdown
## 2026-05-10 — Milestone close: Floats

The Floats milestone is closed. `Float` is a fully supported
primitive type in AILang, end-to-end. `examples/floats.ail.json`
builds via `ail build`, runs, and produces predictable stdout —
the milestone-acceptance gate landed first try in iter 4.6.

**Five-iteration arc:**

- **Iter 1 (schema).** `Literal::Float { bits: u64 }` AST variant
  with private `hex_u64` serde helper (16-char lowercase hex string
  in canonical JSON; bypasses `serde_json::Number` for bit
  stability + NaN/Inf representability). `Float` registered as
  primitive name. 8 downstream `match Literal` sites wired with
  permanent semantic arms or named-iteration `unimplemented!`
  placeholders. Drift-test anchors added to `spec_drift.rs` /
  `design_schema_drift.rs` / `form_a.md` / DESIGN.md JSON-schema
  block. Bit-stability tests pin A1 / A5 properties.
- **Iter 2 (surface).** Lex `<digits>.<digits>(e[+-]?<digits>)?`
  and `<digits>e[+-]?<digits>` per spec A2; reject bare leading /
  trailing dots, missing fraction-after-dot, missing / sign-only
  exponents. Parser accepts `Tok::Float` in atom + pat-lit
  positions (typecheck rejects pat-lit Float in iter 3). Surface
  print emits shortest-round-trippable decimal with `.0` suffix
  fallback; non-finite bits panic per spec (cannot reach printer
  via well-formed surface input). Round-trip property
  `lex(print(L)) == L` pinned for 6 representative bit patterns.
- **Iter 3 (typecheck + builtins).** Widened `+`/`-`/`*`/`/` and
  `!=`/`<`/`<=`/`>`/`>=` from monomorphic `(Int, Int) -> {Int, Bool}`
  to polymorphic `forall a. (a, a) -> {a, Bool}` (same shape `==`
  already had). `%` stays Int-only. 5 new builtins installed:
  `neg` (poly), `int_to_float`, `float_to_int_truncate`,
  `float_to_str`, `is_nan`. 3 bit-pattern constants installed as
  bare-value globals: `nan`, `inf`, `neg_inf`. 1 new effect op:
  `io/print_float`. `Pattern::Lit::Float` typecheck-rejected via
  new `CheckError::FloatPatternNotAllowed`.
- **Iter 4 (codegen + E2E).** Float literals lower as LLVM hex-
  float `double` constants. `synth::builtin_binop` replaced by
  3-tuple-returning `builtin_binop_typed(name, &Type)` —
  `fadd/fsub/fmul/fdiv double` and `fcmp olt/ole/ogt/oge/oeq/UNE
  double` arms (note `UNE`, not `one`). `lower_eq` Float arm.
  5 new fn-builtin lowering arms (`neg` poly with `fneg double`;
  `int_to_float` `sitofp`; `float_to_int_truncate`
  `@llvm.fptosi.sat.i64.f64`; `is_nan` `fcmp uno`; `float_to_str`
  deferred via structured `CodegenError`). 3 Float constants
  intercepted at `Term::Var` arm. `io/print_float` via inline
  `printf("%g\n", v)`. `examples/floats.ail.json` E2E fixture +
  `crates/ail/tests/floats_e2e.rs` E2E test — milestone gate.
- **Iter 5 (prose + DESIGN.md).** Prose renderer for Float
  literals (finite + NaN/Inf). DESIGN.md §"Float semantics" + line-
  2034 + builtins-list refresh. Roadmap mark + Prelude unblock.

**Key design decisions (rationale):**

- **One float type only — `f64`, named `Float`** (no `f32`). LLM
  authors don't reach for `f32` unprompted; shipping both would
  surface a per-op type-pun question that adds friction without
  measurable correctness gain.
- **IEEE-conformant equality** — `==` returns `false` for `nan ==
  nan`, no `Eq` instance for `Float` in the eventual prelude. The
  partial-equality reality is real and surfaces through builtins
  (`is_nan`, ordering ops returning `false` for NaN-involved
  comparisons) rather than through a lying total typeclass
  instance.
- **Polymorphic operators over `{Int, Float}` via codegen-dispatch**
  — the same mechanism `==` already used. Mainstream alignment
  beats the explicit-naming purity of the earlier `(fadd 1.5 2.5)`
  draft. The hardcoded `{Int, Float}` filter is transitional;
  cleanly replaceable by a `Num a` constraint when typeclasses
  ship in 22c.
- **Form-A bit-pattern hex string** — bypasses `serde_json::Number`
  (not bit-stable across versions for floats; cannot represent
  NaN / ±Inf). Routing through the string path preserves bit-exact
  determinism + lets non-finite Floats round-trip through
  canonical JSON.
- **Pattern::Lit::Float hard-reject at typecheck** — IEEE semantics
  make Float patterns semantically dubious (NaN never matches;
  bit-exact equality is rarely the LLM-author's intent). Surface
  lex / parser accept the syntax to keep the diagnostic at the
  correct layer (typecheck, not parser).
- **`fcmp UNE` for `!=`, NOT `fcmp one`** — `one` is "ordered and
  not equal" and returns false for `nan != nan`, violating IEEE-
  `!=` and the user-fixed constraint #2. Caught during the
  pre-implementation LLVM IR audit; documented in iter-4 codegen
  arm + DESIGN.md §"Float semantics".
- **`fneg double` for `neg`, NOT `fsub double 0.0, x`** — IEEE
  `0.0 - 0.0 = +0.0`, so the `fsub`-from-zero desugar would
  wrongly produce `+0.0` for `neg(+0.0)` instead of `-0.0`. LLVM 8+
  intrinsic; clang 22 always available.
- **`@llvm.fptosi.sat.i64.f64` for `float_to_int_truncate`** —
  saturating fp-to-int intrinsic exactly matches Rust `as i64`
  semantics (NaN → 0, ±Inf → i64::{MIN,MAX}, saturating). Total,
  no Maybe wrapper.

**Process notes (orchestration lessons):**

- **Drift tests are part of the schema layer.** The original 5-iter
  plan put DESIGN.md anchor edits in iter 5; iter 1's drift-test
  break revealed they belong in iter 1 (where they get added
  together with the AST variant they document). The exhaustive-
  match drift tests are *the enforcement mechanism* of the schema
  invariant — adding a new `Literal` variant without their anchors
  IS a schema-layer break.
- **Plan inconsistencies caught by the reviewer chain.** Iter 4.2
  shipped a plan that would have stranded comparison ops (Step 4
  said `builtin_binop_typed` returns None for them; Step 5
  narrowed the dispatch matches!). Implementer caught it; pulled
  forward Task 3 Steps 3-4 as minimal repair; orchestrator
  endorsed; Task 3's residual scope was narrowed accordingly. The
  two-stage review (spec + quality) caught two more issues:
  the dual-meaning `(instr, ll_ty)` 2-tuple → fixed via 3-tuple
  return; the `unimplemented!()` panic for `float_to_str` →
  fixed via structured `CodegenError::Internal`.
- **`is_static_callee` companion-edit.** Any new lowering arm in
  `lower_app` MUST also be recognised by `is_static_callee`
  (otherwise App dispatch falls through to indirect-call →
  UnknownVar). This bit twice (iter 4.2 for `==`, iter 4.4 for
  the 5 new fn-builtins). Both pulled forward as minimal repairs.
- **The `synth_term` test helper does not exist.** Iter 3 plan
  named it; the actual fn is `crate::synth(...)` with 8 args. The
  implementer flagged this; future plans should specify the
  adapter pattern explicitly.

**Workspace at milestone close:** 405+ tests passing, 0 failed.
Iter-1-baseline rustdoc warnings preserved (1 warning on `desugar`
private link, pre-existing). `def_hash` regression hashes
(`db33f57cb329935e` for `sum.sum`, `b082192bd0c99202` for
`IntList`) preserved bit-identical — adding a Literal variant
does not perturb pre-existing canonical bytes.

**Known debt deferred beyond this milestone:**

- `float_to_str` codegen lowering — requires runtime-allocated Str
  (the current Str path uses only static `@.str_*` globals;
  no malloc-backed dynamic-Str infrastructure). Symbol is
  type-installed and surface-callable, but lowering errors with a
  structured `CodegenError::Internal`. Future milestone wires the
  runtime Str-allocator path; revisit then.
- Float-typed container slot layout — mono pass produces
  `List_Fl` etc. naturally per the iter-1 `type_descriptor` `Fl`
  arm, but no current fixture exercises a Float-typed container.
  Verify when a future use case surfaces.
- Pattern-matching on Float ranges (e.g. `(0.0..1.0)`) — out of
  scope; would need a different Pattern variant entirely.
- Float-aware ADT layout for Float-only ADT fields — same
  monomorphisation guarantee as `List<Float>` would extend; not
  exercised by current corpus.

**Roadmap effects:** Floats `[x]`. Post-22 Prelude unblocked (was
`depends on: Floats`); the Prelude milestone can now ship `Show`
for `Float` and decide-against `Eq` / `Ord` for Float (both
reflecting the partial-equality reality settled in this milestone).

Next dispatch (orchestrator): `audit` skill — milestone-close
drift review + bench-regression diagnostics + rustdoc audit.
After audit closes clean: `fieldtest` skill — 2-4 `.ailx`
real-world examples exercising the new Float surface.
```

- [ ] **Step 3: Commit**

```bash
git add docs/JOURNAL.md
git commit -m "floats iter 5: JOURNAL — iter-5 close + Floats milestone close"
```

---

## Iteration acceptance

- [ ] `cargo build --workspace` is clean.
- [ ] `cargo test --workspace` is GREEN — pre-existing 402 tests
  stay GREEN; the 3 new prose tests PASS (= 405+).
- [ ] No `unimplemented!("Floats milestone iter 5: prose")` arm
  remains anywhere in `crates/`.
- [ ] DESIGN.md §"Float semantics" present.
- [ ] DESIGN.md line 2034 lists Float as a supported primitive.
- [ ] `crates/ailang-core/tests/design_schema_drift.rs` and
  `tests/spec_drift.rs` GREEN (the iter-1 anchors are unchanged).
- [ ] Roadmap shows Floats `[x]`; Post-22 Prelude has no
  `depends on: Floats` line.
- [ ] JOURNAL has BOTH the iter-5 close entry AND the separate
  milestone-close summary.
- [ ] No file touched outside the four listed in the file map.

When all five tasks are committed and the acceptance checklist is
green, hand back to the orchestrator. The orchestrator dispatches
`audit` next (milestone-close drift review + bench regression),
followed by `fieldtest` (2-4 real-world `.ailx` examples).