# Typed ry's hill climb

Typed ry grows by a hill climb. Each step is one change to the language or its implementation, and
it is kept only when it raises the fitness without lowering soundness. `just climb` computes the
fitness; `just climb --log "NOTE"` also appends it to `tools/climb/log.tsv`, which is the climb's
step log. The tour of what exists is [Typed ry](/reference/language.md).

## Fitness

| Score | Measures | Better |
| --- | --- | --- |
| `unsound` | Seeded random programs that strict mode accepts but that fail with a type error, or hold a value of another type than declared, when they run | 0, always |
| `rejected` | Random well-typed programs that strict mode rejects | lower |
| `friendly` | Cases in `tools/climb/friendly/` that behave as their first line says | higher |
| `suffixes per 100 lines` | `i64`/`f64` suffixes the typed benchmark programs need | lower |
| `typed ry / Rust` | Geometric mean of typed ry's time over the Rust reference's, per benchmark program | lower, 1 is Rust |
| `untyped ry / GNU R` | The same for the untyped twins on ry against GNU R | lower |

Soundness is a constraint, not a trade: a step that makes `unsound` nonzero is reverted or fixed
before anything else. Among the other scores, speed and friendliness weigh equally.

## Corpus

- **Speed.** The 17 typed benchmark programs, each a `<name>.typed.R` (typed ry, strict mode) beside
  its plain R `<name>.R` in `tools/bench/kernels/` or `tools/bench/applications/`, and each with a
  Rust reference in `tools/bench/typed/` written the way a Rust programmer would and printing the
  same checksum. They are the `typed` benchmark suite, and the climb times them through that
  suite's runner (`tools/bench/bench.py`), so both report the same statistic: the median warm run
  of each engine, and the geometric mean of typed ry's time over Rust's.
- **Friendliness.** `tools/climb/friendly/*.R`. A case starts with `# expect: ok` or
  `# expect: CODE`. An `ok` case must pass strict mode and, on ry's runtime, print exactly its `#>`
  lines; any other case must report exactly that one diagnostic code. A known gap gets a case first,
  so it fails until a step fixes it.
- **Soundness.** A generator in `tools/climb/run.py` writes programs over `I64`, `F64`, `Bool`,
  `Str` and their lists that lean on unsuffixed literals, typed and untyped bindings, `if`, `match`
  arms, generic standard library calls and lambdas. Each program prints the `typeof()` of every
  value, which must match its declared type (`I64` for `I64` and `List<I64>`, `double` for `F64`).
  `--seed` and `--programs` replay or widen a run, and a failure prints the program's path.

## Steps

`tools/climb/log.tsv` holds one line per measured step: the date, the commit, every score, and a
note. A taste question a step raises (a new syntax, a changed default) goes to the orchestrator in
one batch rather than being decided inside the climb.

### Step log

| Step | friendly | unsound | rejected | Change |
| --- | --- | --- | --- | --- |
| baseline | 8/16 | 0 | not measured | The harness, the corpus, and the first friendliness gaps the generator found |
| 1 | 13/17 | 0/10 | 10/20 | `&&` and `\|\|` on two `Bool`s give `Bool`. Arithmetic on number literals alone (`2 * 3.14159 * r`) adapts like a lone literal. Within one function, a variable written with a string, `TRUE`/`FALSE` or number literal is decided by the parameter it is passed to or the annotated binding it flows into |
| 2 | 20/21 | 0/12 | 5/20 | In a strict file or a file with ry syntax, a top-level literal binding is a ry value (`rate <- 2.0` is an `F64`), and passing an `I64` or a `List<I64>` to an R function names `Num.to_r()` or `List.to_r()` |
| 3 | 20/21 | 8/240 | 0/240 | A value of literals alone (logic, comparisons, an `if` of literals, a one-statement `{}`) adapts like a lone literal; a literal beside a `Bool` in `&&` takes `Bool`; an annotation decides a ry number a call left open. The generator now writes empty ranges, which exposed the empty-list gap below; an empty list that carries the `I64` kind (from `List.range`) sums to the `I64` 0 |
| 4 | 20/21 | 0/240 | 0/240 | An empty list keeps the item type the checker gave it: the preflight passes `[]` and each callback-built library list (`List.map`) through `.ry_items` with that type |

## Open questions

- **Empty lists in code that is not elaborated.** `ry run` and the console pass `[]` and every
  library call whose result items come from a callback (`List.map`) through `.ry_items` with the
  item type the checker gave them, so an empty result keeps its type. `ry load` and `source()` run
  unelaborated text, where such an empty list is still a `logical` vector of length zero unless a
  `List<I64>` parameter or result converts it.
