stdlib-reference.md

# Standard Library Reference

<!-- Generated by scripts/stdlib-reference.mjs --write. Do not edit: change the declarations
     (stdlib/*.cml and stdlib/signatures/*.cml) or the comments of the library and
     regenerate. -->

The functions of the core standard library, by module. The boundary is the one the design
principles draw (section 10.5): a primitive that touches the system or is sensitive to
performance is an operator written in C++, an opaque node of the graph; logic composed from
primitives is written in Camel, a subgraph that passes can see into.

Every function follows the [standard library conventions](stdlib-conventions.cn.md): one fact
one place, the declaration is the signature, naming, parameters, error kinds, and where a
module lives.

How to read an entry:

- **Signature**: `name: <with-parameters> (parameters) => result`. The value a function works
  on is its ordinary parameter and what configures it is a with-parameter, so calls chain:
  `s->trim->split<','>`, `xs->filter<p>->sort_by<key>`. `int` is the 64-bit integer and `float`
  the 64-bit float; `i32` and `f32` are the 32-bit ones; numeric types are never converted
  implicitly.
- **Pure** operators depend on their arguments only: a pass may evaluate a call ahead of time,
  merge two equal calls or drop an unused one. An operator **with effects** is left alone, and
  its call runs only when it is reachable from a `sync` block or its result is used (design
  principles 3.1). Every operator of these modules declares which it is.
- **Failure**: a *fault* stops the program with a located diagnostic (an index out of range, an
  argument outside what the operator defines). An *error* is a value: the function returns
  `T!` and the program handles it with `!!`, `->` or `match`. A result that may not exist is
  `T?`, handled with `??`. An entry without a failure line does not fail.
- **Named arguments**: a call may give a parameter by name (`f(x: 1)`, `len(x: xs)`) when
  the name gives that position the same name in every form the callee has, whether the callee is
  a Camel declaration or a group of built-in rules; the type of the argument then decides which
  form runs (`len`'s one parameter is `x` for a string, an array, a map and a set, so one name
  reaches all four). The name is written in the list that holds the parameter: an ordinary one
  in the parentheses (`len(x: xs)`), a `with` one in the angle brackets (`j->get<key: 'port'>`).
  A form that gives a position no name, or leaves its count to the arguments (a rest list,
  as `println` takes), is one no named argument reaches: the call
  reports that the signature is not known where the call is written. `contains` refuses a named
  argument for a reason of its own: its position 0 means an element in two forms and the
  substring in the third, so the name would mean another thing in one of them.
- Write one call that has with-arguments per statement when several appear in one argument
  list: `f<a>(x), g<b>(y)` is read as comparisons.

Not in this reference: the profiler (`perf`).

| Module | Import | Written in |
|---|---|---|
| [built-in](#built-in-functions) | none | C++ |
| [str](#str) | `import { ... } from str` | C++ |
| [bytes](#bytes) | `import { ... } from bytes` | C++ |
| [ckpt](#ckpt) | `import { ... } from ckpt` | C++ |
| [tree](#tree) | `import { ... } from tree` | Camel |
| [transforms](#transforms) | `import { ... } from transforms` | C++ |
| [vjp](#vjp) | `import { ... } from vjp` | Camel |
| [tensor](#tensor) | `import { ... } from tensor` | C++ |
| [types](#types) | `import { ... } from types` | Camel |
| [array](#array) | `import { ... } from array` | Camel |
| [stream](#stream) | `import { ... } from stream` | Camel |
| [math](#math) | `import { ... } from math` | C++ |
| [statistics](#statistics) | `import { ... } from statistics` | Camel |
| [random](#random) | `import { ... } from random` | C++ |
| [time](#time) | `import { ... } from time` | C++ |
| [fs](#fs) | `import { ... } from fs` | C++ |
| [io](#io) | `import { ... } from io` | C++ |
| [process](#process) | `import { ... } from process` | C++ |
| [env](#env) | `import { ... } from env` | C++ |
| [json](#json) | `import { ... } from json` | C++ |
| [hash](#hash) | `import { ... } from hash` | C++ |
| [re](#re) | `import { ... } from re` | C++ |
| [para](#para) | `import { ... } from para` | C++ |
| [test_support](#test_support) | `import { ... } from test_support` | C++ |
| [this](#this) | `import { ... } from this` | C++ |
| [graph](#graph) | `import { ... } from graph` | C++ |
| [rewrite](#rewrite) | `import { ... } from rewrite` | C++ |
| [tiles](#tiles) | `import { ... } from tiles` | C++ |
| [pyplot](#pyplot) | `import { ... } from pyplot` | C++ |
| [python](#python) | `import { ... } from python` | C++ |
| [nn](#nn) | `import { ... } from nn` | C++ |
| [optim](#optim) | `import { ... } from optim` | Camel |
| [autodiff](#autodiff) | `import { ... } from autodiff` | C++ |
| [rulesets.jvp](#rulesets.jvp) | `import { ... } from rulesets.jvp` | Camel |
| [rulesets.vmap](#rulesets.vmap) | `import { ... } from rulesets.vmap` | Camel |
| [sim](#sim) | `import { ... } from sim` | C++ |
| [onnx](#onnx) | `import { ... } from onnx` | C++ |
| [built-in](#built-in-functions) | none |  |
| [str](#str) | `import { ... } from str` |  |
| [bytes](#bytes) | `import { ... } from bytes` |  |
| [ckpt](#ckpt) | `import { ... } from ckpt` |  |
| [tree](#tree) | `import { ... } from tree` |  |
| [transforms](#transforms) | `import { ... } from transforms` |  |
| [vjp](#vjp) | `import { ... } from vjp` |  |
| [tensor](#tensor) | `import { ... } from tensor` |  |
| [types](#types) | `import { ... } from types` |  |
| [array](#array) | `import { ... } from array` |  |
| [stream](#stream) | `import { ... } from stream` |  |
| [math](#math) | `import { ... } from math` |  |
| [statistics](#statistics) | `import { ... } from statistics` |  |
| [random](#random) | `import { ... } from random` |  |
| [time](#time) | `import { ... } from time` |  |
| [fs](#fs) | `import { ... } from fs` |  |
| [io](#io) | `import { ... } from io` |  |
| [process](#process) | `import { ... } from process` |  |
| [env](#env) | `import { ... } from env` |  |
| [json](#json) | `import { ... } from json` |  |
| [hash](#hash) | `import { ... } from hash` |  |
| [re](#re) | `import { ... } from re` |  |
| [para](#para) | `import { ... } from para` |  |
| [test_support](#test_support) | `import { ... } from test_support` |  |
| [this](#this) | `import { ... } from this` |  |
| [graph](#graph) | `import { ... } from graph` |  |
| [rewrite](#rewrite) | `import { ... } from rewrite` |  |
| [tiles](#tiles) | `import { ... } from tiles` |  |
| [pyplot](#pyplot) | `import { ... } from pyplot` |  |
| [python](#python) | `import { ... } from python` |  |
| [nn](#nn) | `import { ... } from nn` |  |
| [optim](#optim) | `import { ... } from optim` |  |
| [autodiff](#autodiff) | `import { ... } from autodiff` |  |
| [rulesets.jvp](#rulesets.jvp) | `import { ... } from rulesets.jvp` |  |
| [rulesets.vmap](#rulesets.vmap) | `import { ... } from rulesets.vmap` |  |
| [sim](#sim) | `import { ... } from sim` |  |
| [onnx](#onnx) | `import { ... } from onnx` |  |

<a id="built-in-functions"></a>

## Built-in functions

The operators behind the language's own operators (`+`, `==`, `[]`, `??`, assignment, ...) are
registered under reserved names (`__add__`, ...) and are not listed here.

These declarations are compiled with every program: a name they write that does not exist fails
every program, with its location here. They give a call's arguments their expected types (so a
lambda passed to `filter` needs no parameter types), --verify-ops checks them against the
operators the core registers, and docs/stdlib-reference.md is generated from them
(scripts/stdlib-reference.mjs).

The parameter names written here are the names a call binds to by name (`len(x: xs)`), and they
are the ones the reference page prints: `--verify-ops` compares them with the names of the
registered rules, position by position, in both the `with` list and the ordinary one. Until
these declarations also decide which function a call matches (design principles, "the single
source of a signature"), the C++ rules still do, so the two have to stay equal, and a difference
is a test failure rather than a silent drift. The names here are the ones to keep:
the reference page is generated from them, and a position a call names is the position this file
names (stdlib-conventions.cn.md, section 4).

### Memory

Data blocks (design principles 10.5): the process-wide counters, read between two operations.

#### `std::mem::blocks`

```camel
std::mem::blocks: () => { allocs: int, frees: int, live: int, bytes: int }
```

The data-block counters: blocks allocated so far, freed so far, live now, and the bytes the
live blocks hold. The call is not pure: it reports process state, so the optimizer must not
fold, merge or drop it.

- Example: `std::mem::blocks().live` gives `0 when no block is alive`

### Conversions

Numeric types are never converted implicitly; these functions do it. There is one conversion
per target type, named by the type: `int`, `i32`, `float`, `f32`, `bf16`, `f16`, `c64`, `c128`
(and `i64`, `f64`, the spellings of `int` and `float`). Each is one declaration per source type,
the overloads of one name written under one comment. Applied to an array, a conversion converts every element (one rule with arithmetic:
`f32(xs)` is one node, and `T(xs)` does it for the type a generic function is given); that entry
is declared below, with the core's conversions: it needs no import. Converting a float to an integer drops the fraction.

#### `int`

```camel
int: (x: i32) => int
int: (x: int) => int
int: (x: f32) => int
int: (x: float) => int
int: (x: string) => int
int: (x: bf16) => int
int: (x: f16) => int
```

x as a 64-bit integer.

- Failure: fault `InvalidNumberText` when x is a string that is not, as a whole, one integer (blanks and a trailing part included); fault `ConversionOutOfRange` when x is a string that is an integer beyond the range, or a float that is NaN, infinite or beyond the range; use parse_int to handle text in the program.
- Example: `int(2.9)` gives `2`

#### `i64`

```camel
i64: (x: i32) => int
i64: (x: int) => int
i64: (x: f32) => int
i64: (x: float) => int
i64: (x: string) => int
i64: (x: bf16) => int
i64: (x: f16) => int
```

The same as int.

- Failure: fault `InvalidNumberText` when x is a string that is not, as a whole, one integer; fault `ConversionOutOfRange` when x is a string that is an integer beyond the range, or an int or a float beyond the range of i32, or NaN.
- Example: `i64('42')` gives `42`

#### `i32`

```camel
i32: (x: i32) => i32
i32: (x: int) => i32
i32: (x: f32) => i32
i32: (x: float) => i32
i32: (x: string) => i32
i32: (x: bf16) => i32
i32: (x: f16) => i32
```

x as a 32-bit integer.

- Failure: fault `InvalidNumberText` when x is a string that is not, as a whole, one integer; fault `ConversionOutOfRange` when x is a string that is an integer beyond the range, or an int or a float beyond the range of i32, or NaN.
- Example: `i32(7)` gives `7`

#### `float`

```camel
float: (x: i32) => float
float: (x: int) => float
float: (x: f32) => float
float: (x: float) => float
float: (x: string) => float
float: (x: bf16) => float
float: (x: f16) => float
```

x as a 64-bit float.

- Failure: fault `InvalidNumberText` when x is a string that is not, as a whole, one number; fault `ConversionOutOfRange` when x is a string that is a number beyond the range of float (overflow or underflow); use parse_float to handle that in the program.
- Example: `float(3)` gives `3`

#### `f64`

```camel
f64: (x: i32) => float
f64: (x: int) => float
f64: (x: f32) => float
f64: (x: float) => float
f64: (x: string) => float
f64: (x: bf16) => float
f64: (x: f16) => float
```

The same as float.

- Failure: fault `InvalidNumberText` when x is a string that is not a number; fault `ConversionOutOfRange` when x is a string that is a number beyond the range of float (overflow or underflow).
- Example: `f64('2.5')` gives `2.5`

#### `f32`

```camel
f32: (x: i32) => f32
f32: (x: int) => f32
f32: (x: f32) => f32
f32: (x: float) => f32
f32: (x: string) => f32
f32: (x: bf16) => f32
f32: (x: f16) => f32
```

x as a 32-bit float.

- Failure: fault `InvalidNumberText` when x is a string that is not a number; fault `ConversionOutOfRange` when x is a string that is a number beyond the range of f32 (overflow or underflow).
- Example: `f32(0.5)` gives `0.5`

#### `bf16`

```camel
bf16: (x: i32) => bf16
bf16: (x: int) => bf16
bf16: (x: f32) => bf16
bf16: (x: float) => bf16
bf16: (x: bf16) => bf16
bf16: (x: string) => bf16
```

x as a bf16: the nearest bf16 of x, rounding to nearest with ties to even, once. A bf16 is a
floating-point type of the language (design principles 7.3), not only a tensor element type,
and writing the conversion asks for that precision, so no numeric permission is involved.

- Failure: fault `InvalidNumberText` when x is a string that is not a number; fault `ConversionOutOfRange` when x is a string that is a number beyond the range of bf16 (overflow or underflow).
- Example: `bf16(0.5)` gives `0.5`

#### `f16`

```camel
f16: (x: i32) => f16
f16: (x: int) => f16
f16: (x: f32) => f16
f16: (x: float) => f16
f16: (x: f16) => f16
f16: (x: string) => f16
```

x as an f16: the nearest f16 of x, rounding to nearest with ties to even, once. The same
conversion as bf16, at the other reduced precision (design principles 7.3).

- Failure: fault `InvalidNumberText` when x is a string that is not a number; fault `ConversionOutOfRange` when x is a string that is a number beyond the range of f16 (overflow or underflow).
- Example: `f16(0.5)` gives `0.5`

#### `i32`

```camel
i32: (x: A) => WithElement<A, i32> when is_compact_array::<A>()
```

The conversion `i32` applied to every element of a numeric array: the result has the input's extents and element type `i32`. A scalar converts by the declaration above.

- Pure.
- Example: `i32([1.0, 2.0])`

#### `i64`

```camel
i64: (x: A) => WithElement<A, int> when is_compact_array::<A>()
```

The conversion `i64` applied to every element of a numeric array: the result has the input's extents and element type `int64`. A scalar converts by the declaration above.

- Pure.
- Example: `i64([1.0, 2.0])`

#### `int`

```camel
int: (x: A) => WithElement<A, int> when is_compact_array::<A>()
```

The conversion `int` applied to every element of a numeric array: the result has the input's extents and element type `int64`. A scalar converts by the declaration above.

- Pure.
- Example: `int([1.0, 2.0])`

#### `f32`

```camel
f32: (x: A) => WithElement<A, f32> when is_compact_array::<A>()
```

The conversion `f32` applied to every element of a numeric array: the result has the input's extents and element type `f32`. A scalar converts by the declaration above.

- Pure.
- Example: `f32([1.0, 2.0])`

#### `f64`

```camel
f64: (x: A) => WithElement<A, float> when is_compact_array::<A>()
```

The conversion `f64` applied to every element of a numeric array: the result has the input's extents and element type `f64`. A scalar converts by the declaration above.

- Pure.
- Example: `f64([1.0, 2.0])`

#### `float`

```camel
float: (x: A) => WithElement<A, float> when is_compact_array::<A>()
```

The conversion `float` applied to every element of a numeric array: the result has the input's extents and element type `f64`. A scalar converts by the declaration above.

- Pure.
- Example: `float([1.0, 2.0])`

#### `bf16`

```camel
bf16: (x: A) => WithElement<A, bf16> when is_compact_array::<A>()
```

The conversion `bf16` applied to every element of a numeric array: the result has the input's extents and element type `bf16`. A scalar converts by the declaration above. A conversion into `bf16` or `f16` rounds (to nearest, ties to even); writing it asks for that precision, so it needs no numeric permission (`change_precision` governs a computation the compiler moves to lower precision, design principles 7.2-7.3).

- Pure.
- Example: `bf16([1.0, 2.0])`

#### `f16`

```camel
f16: (x: A) => WithElement<A, f16> when is_compact_array::<A>()
```

The conversion `f16` applied to every element of a numeric array: the result has the input's extents and element type `f16`. A scalar converts by the declaration above. A conversion into `bf16` or `f16` rounds (to nearest, ties to even); writing it asks for that precision, so it needs no numeric permission (`change_precision` governs a computation the compiler moves to lower precision, design principles 7.2-7.3).

- Pure.
- Example: `f16([1.0, 2.0])`

#### `c64`

```camel
c64: (x: i32) => c64
c64: (x: int) => c64
c64: (x: f32) => c64
c64: (x: float) => c64
c64: (x: c64) => c64
c64: (x: c128) => c64
```

x as a 64-bit complex number: the real part is x and the imaginary part is zero. A c128
keeps both parts as they are.

- Example: `c64(2)` gives `2+0i`

#### `c128`

```camel
c128: (x: i32) => c128
c128: (x: int) => c128
c128: (x: f32) => c128
c128: (x: float) => c128
c128: (x: c64) => c128
c128: (x: c128) => c128
```

x as a 128-bit complex number: the real part is x and the imaginary part is zero.

- Example: `c128(2)` gives `2+0i`

#### `string`

```camel
string: (x: T) => string
```

x as text, as println writes it. A float is written as the shortest text that reads back as
the same number: string(2.5) is '2.5', string(2.0) is '2.0'.

- Example: `string(42)` gives `'42'`

#### `parse_int`

```camel
parse_int: (text: string) => int!
```

The integer a text spells, or an error value.

- Failure: error `ParseError` when the text is not, as a whole, one integer (blanks are not skipped).
- Example: `parse_int('42') !! 0` gives `42`

#### `parse_float`

```camel
parse_float: (text: string) => float!
```

The number a text spells, or an error value.

- Failure: error `ParseError` when the text is not a number.
- Example: `parse_float('2.5') !! 0.0` gives `2.5`

#### `error`

```camel
error: (kind: string, message: string) => Error
```

An Error value of the given kind with the given message; the compiler adds the source
position of the call. `return error(...)` hands it out of a function declared `T!`.

- Example: `return error('RangeError', 'too large')`

### Input and output

#### `print`

```camel
print: <fmt: string> (x: T, ...rest) => T
print: (x: T, ...rest) => T
print: () => void
```

Writes the arguments, separated by spaces, without a line end, and gives back the first one
(so that the write can be part of the data flow). The other arguments may each have a type
of their own. With a format, print<fmt>(...), writes the format with the arguments put in,
also without a line end.

- Example: `print('a', 1)` gives `a 1`

#### `println`

```camel
println: <fmt: string> (x: T, ...rest) => T
println: (x: T, ...rest) => T
println: () => void
```

Writes the arguments, separated by spaces, and a line end, and gives back the first one (so
that the write can be part of the data flow). The other arguments may each have a type of
their own. With a format, println<fmt>(...), writes the format with the arguments put in and
one line end.

- Example: `println('a', 1)` gives `a 1`

#### `eprintln`

```camel
eprintln: <fmt: string> (x: T, ...rest) => T
eprintln: (x: T, ...rest) => T
eprintln: () => void
```

Writes the arguments, separated by spaces, and a line end, to standard error, and gives back
the first one (so that the write can be part of the data flow). The other arguments may each
have a type of their own. With a format, eprintln<fmt>(...), writes the format with the
arguments put in and one line end.

- Example: `eprintln('a', 1)` gives `a 1`

### Strings

#### `format`

```camel
format: <...args> (fmt: string) => string
```

The text fmt with each `{}` placeholder replaced by the next argument; placeholders take
format specifications such as `{:.2f}` and `{:>8}`.

A specification whose argument is a numeric array acts on each element on its own, while the
brackets and the `, ` between the elements are the array's own form: `'{:.4f}'->format<xs>`
with `xs = [0.7692267, 0.780836, 0.77707076]` is `[0.7692, 0.7808, 0.7771]`, and an array of
rank 2 keeps one bracket level per dimension (`[[0.7692, 0.7808], [0.7771, 2.0000]]`). Each
element is written by the specification and by its own type, so `{:.2f}` rounds an `f32`
element and an `f64` element each at two places. An array without a specification prints as
it does everywhere else: every element in the shortest text that reads back as the same
number, which is `'{}'->format<xs>` giving `[0.7692267, 0.780836, 0.77707076]`.

- Failure: fault `FormatFailed` when the placeholders and the arguments do not fit.
- Example: `'{} is {:.2f}'->format<'x', 2.5>` gives `'x is 2.50'`

#### `join`

```camel
join: <sep: string> (xs: string[]) => string
```

The strings of xs joined with sep between them.

- Example: `['a', 'b']->join<', '>` gives `'a, b'`

#### `len`

```camel
len: (x: string) => int
```

The number of code points of a string.

- Pure.
- Example: `len('h€')` gives `2`

#### `len`

```camel
len: (x: A) => int when is_array::<A>()
```

The length of the first dimension of an array of any rank.

- Pure.
- Example: `len([1, 2, 3])` gives `3`

#### `len`

```camel
len: (x: Bytes) => int
```

The number of bytes of a `Bytes`.

- Pure.
- Example (a fragment, not compiled): `len(encode('h€'))` gives `4`
- Why it is not compiled: the example builds its `Bytes` with `encode` from the `bytes` module, which this page does not import

#### `extent_of`

```camel
extent_of: () => int[] when is_array::<A>()
```

The extents an array type writes down, in order: `extent_of::<float[2, 3]>()` is `[2, 3]`.

The answer is a fact of the type argument and of nothing else, so the call takes no argument and
names one type: `A` is the whole array type, the way a transposition law names one (`matmul_t::<T,
A, B>`). Every extent of `A` has to be a number written in the type; a type that leaves one open
states no shape -- `float[]` (= `float[?]`) states one dimension and no length, and `float[...]`
states neither the rank nor a length -- and is refused where the call is instantiated. A shape
that is a fact of a *value* is `shape(x)`, which is a question about the value and not the type.

A transposition is where this is needed: the adjoint of a map is a function of the cotangent and
of the shape of the map's domain, and a parameter whose cotangent is what the transposed function
takes has no value to read (`func pick(x: float[3])`). `transpose(pick)` answers
`([0.0, 1.0, 0.0])` because the shape the law spreads its cotangent over is written in the type
`x` is declared with, and this is the language's one spelling of "the shape a type writes down" --
the transposition walk asks the same rule (`statedExtentsOf`).

The value is settled where the call is built and where the name is used as a value, and the
graph holds the list itself: the operator records the instantiated type of the call but not the
type argument it was written with, so the run has nothing left to read
(`src/builtin/operators/struct.cpp#ExtentOfResolver`, the rule's
`valueFromTypeArgs`). The refusal names the **position** that has no number in it
(`SemanticDiag::ExtentOfNeedsStatedShape`).

- Pure.
- Example: `extent_of::<float[2, 3]>()` gives `[2, 3]`

### Arrays

#### `range`

```camel
range: (start: int, end: int, step: int) => int[]
```

The integers of a step: `start`, `start + step`, ... up to, not including, `end`; with no step
the step is 1, `range(a, b)` is the same sequence as the interval `a..b` and becomes it on the
graph (design principles 4.2). `step` must move: a step of 0 is a fault, and a constant call
with a step of 0 is refused where it is written. The result is empty when the step does not
carry `start` towards `end`. A `for` over an interval is fused by the compiler and builds no
array; this call builds one.

- Failure: fault `InvalidArgument` when the step is 0.
- Example: `range(0, 10, 3)` gives `[0, 3, 6, 9]`
- Example: `range(10, 0, -3)` gives `[10, 7, 4, 1]`

#### `last`

```camel
last: (xs: T[]) => T
```

The last element. An empty array has none: check len first. Negative indices are not
counted from the end (a negative index is a fault), so this is how the last element is
written.

- Failure: fault `IndexOutOfRange` when the array is empty.
- Example: `last([1, 2, 3])` gives `3`

#### `slice`

```camel
slice: <axis: int, start: int, end: int, step: int = 1> (x: T[]) => T[]
```

The part of x from start up to, not including, end along one axis, taking every step-th
position (a step of 1 by default, any non-zero value allowed). x is an array of any rank, a
string (by code point) or a `Bytes`; this is the same node the subscript `x[a:b:s]` builds, so
a pipeline can write it: `xs->slice<0, 1, 3>`. A bound outside the value (a negative one
included) is a fault, as an index out of range is; a start after the end gives the empty
value. The last element is `last(x)` and the length of an axis `dim(x, axis)`.

- Failure: fault `IndexOutOfRange` when a bound lies outside the axis; fault `InvalidArgument` when the step is 0.
- Example: `[1, 2, 3, 4]->slice<0, 1, 3>` gives `[2, 3]`

#### `slice`

```camel
slice: <axis: int, start: int, end: int, step: int = 1> (x: string) => string
```

The same slice of a string, by code point: a string has the one axis 0, and the result is a
string. `'中文字'[1:3]` and `'中文字'->slice<0, 1, 3>` are both `'文字'`.

- Example: `'hello'->slice<0, 1, 4>` gives `'ell'`

#### `slice`

```camel
slice: <axis: int, start: int, end: int, step: int = 1> (x: Bytes) => Bytes
```

The same slice of a `Bytes`, by byte: it has the one axis 0, and the result is a `Bytes`.
`b[1:3]` and `b->slice<0, 1, 3>` are the same bytes.

- Example (a fragment, not compiled): `encode('hello')->slice<0, 1, 4>` gives `the bytes of 'ell'`
- Why it is not compiled: the example names `encode`, which is `bytes`'s, and a doc example is compiled with this module's names only

#### `concat`

```camel
concat: (xs: T[], ys: T[]) => T[]
```

The elements of xs followed by those of ys, as a new array.

- Example: `concat([1], [2, 3])` gives `[1, 2, 3]`

#### `contains`

```camel
contains: <value: T> (xs: T[]) => bool
```

Whether an element of xs equals value, by the `==` of the element type (by content for
arrays, tuples and structs).

- Example: `[1, 2, 3]->contains<2>` gives `true`

#### `contains`

```camel
contains: <sub: string> (s: string) => bool
```

Whether sub occurs in the string s (bytes are compared). The empty string occurs in every
string.

- Example: `'hello'->contains<'ell'>` gives `true`

#### `zip`

```camel
zip: (...xs: ...A) => (...ElementOf<A>)[] when ...is_array::<A>()
```

Two arrays combined element by element into pairs. They must have the same length.
Three or more arrays (`zip(xs, ys, zs)`) give tuples of that many elements.

- Failure: fault `InvalidArgument` when the lengths differ.
- Example: `zip([1, 2], ['a', 'b'])` gives `[(1, 'a'), (2, 'b')]`

#### `append`

```camel
append: <value: T> (xs: T[]) => T[]
```

A new array: the elements of xs, then value. xs is unchanged; to add to a variable, bind it
to the result: `acc = acc->append<4>` (as a statement, that form grows the array in place
when nothing else refers to it, which cannot be observed).

- Example: `[1, 2, 3]->append<4>` gives `[1, 2, 3, 4]`

### Higher-order functions

`map` and `filter` apply f to the elements with no order among the calls: the parallel
scheduler may run them at the same time, and the result is by position. `foreach` and
`reduce` call f element by element in order. `T[]` is an array of that element type (rank 1); the rank-n meaning is P5
work. They are declared with effects because what a
call does is what f does.

#### `map`

```camel
map: <f: (item: T) => U> (xs: T[]) => U[]
```

f applied to every element; the calls have no order among them. One call batches one array,
along the one axis that array has, and the result is by position: a function of one value
becomes a function of an array of them, and of nothing else. Batching a second array, choosing
or naming the axis, and applying the batch where no array is written yet are not this function.

- Example: `[1, 2, 3]->map<(x) => x * 2>` gives `[2, 4, 6]`

#### `filter`

```camel
filter: <f: (item: T) => bool> (xs: T[]) => T[]
```

The elements for which f is true, in order; the calls of f have no order among them.

- Example: `[1, 2, 3, 4]->filter<(x) => x % 2 == 0>` gives `[2, 4]`

#### `reduce`

```camel
reduce: <f: (acc: U, item: T) => U, initial: U> (xs: T[]) => U
```

The elements combined from left to right: f(...f(f(initial, xs[0]), xs[1])..., xs[n-1]).

- Example: `[1, 2, 3]->reduce<(acc: int, x: int) => acc + x, 0>` gives `6`

#### `foreach`

```camel
foreach: <f: (item: T) => void> (xs: T[]) => void
```

Calls f for every element, in order.

- Example: `[1, 2, 3]->foreach<(x) => println(x)>`

### Fault isolation

A fault (a division by zero, an index out of range, a recursion that is too deep, ...) ends
the program with a located diagnostic. `attempt` isolates it at the boundary of one call
(design principles 3.9; docs/technical/33_fault_isolation.md). It is a function transform:
`attempt(f)` is the function whose parameters are f's and whose calls are calls of f made
inside the boundary. The name is provisional.

#### `fail`

```camel
fail: <Kind: string> (message: string) => never
```

Raises a fault of the kind the program writes, with the message it gives. The call gives no
value at all: its type is the bottom type `never` (design principles 3.9), so it may stand
where any type is expected, and a branch arm that raises the fault leaves the branch's type
to the other arm. The fault is raised where the call is written, and `attempt` isolates it
into an error value whose kind is the name in the angle brackets.

- Failure: fault `<Kind>` with the message, which `attempt` isolates.
- Example: `fail<'BadLimit'>('the limit must be positive')`

#### `attempt`

```camel
attempt: (f: F) => F!
```

The function f with the faults of its calls turned into error values: `attempt(f)` takes the
parameters of f and gives the result of f plus `!`. A fault raised inside a call becomes an
error value whose kind is the name of the fault (`DivisionByZero`, ...), with the fault's
message and position; otherwise the call gives the result of f. When f itself returns `U!`,
so does `attempt(f)`. What the call did before the fault is not undone; exit() and the
failures of the compiler itself are not isolated. `attempt(f)` itself calls nothing: the
faults are those of a call of the value.

- Failure: fault `DivisionByZero` and every other fault of a call of f: the call gives an error value whose kind is the fault's name, with the fault's message and position; an error value f itself returns is handed on unchanged.
- Example: `attempt((x: int) => 10 / x)(2) !! -1` gives `5`
- Example: `attempt((x: int) => 10 / x)(0) !! -1` gives `-1: the division fault becomes an error value`

#### `len`

```camel
len: (x: C) => int when is_map::<C>() || is_set::<C>()
```

The number of entries of a map or of elements of a set. The collection is `x`, the name the
string and array declarations above give their one parameter: the position means the value
whose length is asked for, whatever its type.

- Example: `len([('a', 1), ('b', 2)] as Map<string, int>)` gives `2`

#### `get`

```camel
get: <key: K> (m: Map<K, V>) => V?
```

The value stored under key, or null when the map has no such key. `m[key]` is the same lookup.

- Example: `([('a', 1)] as Map<string, int>)->get<'z'> ?? 0` gives `0 when the map has no 'z'`

#### `get_or`

```camel
get_or: <key: K, fallback: V> (m: Map<K, V>) => V
```

The value stored under key, or fallback when the map has no such key.

- Example: `([('a', 1)] as Map<string, int>)->get_or<'z', -1>` gives `-1 when the map has no 'z'`

#### `put`

```camel
put: <key: K, value: V> (m: Map<K, V>) => Map<K, V>
```

A map with value stored under key; an existing entry of that key is replaced. m is unchanged.

- Example: `([('a', 1), ('b', 2)] as Map<string, int>)->put<'c', 3>` gives `{a: 1, b: 2, c: 3}`

#### `remove`

```camel
remove: <key: K> (c: Map<K, V>) => Map<K, V>
remove: <key: K> (c: Set<K>) => Set<K>
```

A map without the entry of key, or a set without the element; a key or element that is not there changes nothing. The argument is unchanged.

- Example: `([('a', 1), ('b', 2)] as Map<string, int>)->remove<'a'>` gives `{b: 2}`

#### `has`

```camel
has: <key: K> (c: Map<K, V>) => bool
```

Whether a map has an entry of key. (A set is asked with `contains`.)

- Example: `([('a', 1)] as Map<string, int>)->has<'a'>` gives `true`

#### `keys`

```camel
keys: (m: Map<K, V>) => K[]
```

The keys of a map, in ascending order.

- Example: `keys([('b', 2), ('a', 1)] as Map<string, int>)` gives `[a, b]`

#### `values`

```camel
values: (m: Map<K, V>) => V[]
```

The values of a map, in the ascending order of their keys.

- Example: `values([('b', 2), ('a', 1)] as Map<string, int>)` gives `[1, 2]`

#### `items`

```camel
items: (m: Map<K, V>) => (K, V)[]
```

The entries of a map as (key, value) tuples, in ascending order of the keys.

- Example: `items([('b', 2), ('a', 1)] as Map<string, int>)` gives `[(a, 1), (b, 2)]`

#### `items`

```camel
items: (m: Set<T>) => T[]
```

The elements of a set as an array, in ascending order. The collection is `m`, the name the
map declaration above gives its one parameter: the position means the collection whose items
are listed.

- Example: `items([3, 1, 2] as Set<int>)` gives `[1, 2, 3]`

#### `merge`

```camel
merge: (m: Map<K, V>, other: Map<K, V>) => Map<K, V>
```

A map with the entries of both maps; for a key in both, the entry of other is taken. Neither argument is changed.

- Example: `merge([('a', 1), ('b', 2)] as Map<string, int>, [('b', 20), ('c', 30)] as Map<string, int>)` gives `{a: 1, b: 20, c: 30}`

#### `contains`

```camel
contains: <value: T> (s: Set<T>) => bool
```

Whether value is an element of the set.

- Example: `([1, 2, 3] as Set<int>)->contains<9>` gives `false`

#### `add`

```camel
add: <value: T> (s: Set<T>) => Set<T>
```

A set with value added; s is unchanged.

- Example: `([1, 2, 3] as Set<int>)->add<9>` gives `{1, 2, 3, 9}`

#### `union`

```camel
union: (s: Set<T>, other: Set<T>) => Set<T>
```

The set of the elements that are in either set.

- Example: `union([1, 2, 3] as Set<int>, [3, 4] as Set<int>)` gives `{1, 2, 3, 4}`

#### `intersect`

```camel
intersect: (s: Set<T>, other: Set<T>) => Set<T>
```

The set of the elements that are in both sets.

- Example: `intersect([1, 2, 3] as Set<int>, [3, 4] as Set<int>)` gives `{3}`

#### `difference`

```camel
difference: (s: Set<T>, other: Set<T>) => Set<T>
```

The set of the elements of s that are not in other.

- Example: `difference([1, 2, 3] as Set<int>, [3, 4] as Set<int>)` gives `{1, 2}`

#### `is_subset`

```camel
is_subset: (s: Set<T>, other: Set<T>) => bool
```

Whether every element of s is an element of other.

- Example: `is_subset([1, 2] as Set<int>, [1, 2, 3] as Set<int>)` gives `true`

### Streams

#### `tee_note`

```camel
tee_note: (hint: int, cap: int, elements: int, peak: int, s: T..) => void
```

Records one `tee` (design principles 5.4) for the report of a profile session: the hint it
took, the widest hint the implementation honours, the elements it has pulled from its source so
far, and the most elements it has buffered at once -- with the stream it reads, whose value
tells one tee from another and whose type the operator takes, and whose elements it does not.
A program does not write this: `tee` calls it once per element it pulls, and `std::profile`
prints what it recorded (`STREAM_TEE`).

- Example (a fragment, not compiled): `tee_note(8, 64, 2, 2, s)` gives `the tee written `s->tee<8>` reports itself this way`
- Why it is not compiled: the last operand is the stream a tee reads, and no example program has one

<a id="str"></a>

## `str`: strings

Text functions. A string is always valid UTF-8, and its length and indices count code points:
`len('中文')` is 2 and `'中文'[0]` is `'中'`. Binary data is `Bytes`; `bytes::encode` and
`bytes::decode` are the one place where a string becomes UTF-8 bytes and back.

- The string a function works on is its ordinary argument; everything that configures the
  call is a with-argument, so calls chain: `s->trim->split<','>`.
- Every function returns a new string; none changes its argument.
- A result that may not exist is `T?` (`index_of`, `strip_prefix`). A number that is not a
  code point is an error value (`from_codepoints`). An index outside the string is a fault.
- Only what Camel cannot say about a string is native: code points as numbers and
  letter case (cutting by code point is the subscript `s[a:b]` of the core). The rest is
  written here; `index_of` and `split` carry a native kernel under `#impl` for speed, with the same result as their bodies.

### Native primitives

#### `codepoints`

```camel
codepoints: (s: string) => int[]
```

The code points of s, as numbers.

- Pure.
- Example: `codepoints('h€')` gives `[104, 8364]`

#### `from_codepoints`

```camel
from_codepoints: (xs: int[]) => string!
```

The string made of the given code points.

- Pure.
- Failure: error `EncodingError` when an element is not a code point (negative, above 0x10FFFF, or a surrogate).
- Example: `from_codepoints([104, 8364]) !! ''` gives `'h€'`

#### `to_upper`

```camel
to_upper: (s: string) => string
```

s with every letter in upper case, by the Unicode case mapping that does not depend on a
language or on the context: a letter may become several (`'ß'` is `'SS'`), and a letter
without a mapping, such as a CJK character or an emoji, is kept. The language-specific rules
are not applied: `'i'` is `'I'` and a dotless `'ı'` is also `'I'`, and Greek `'Σ'` is always `'σ'` in lower case,
even at the end of a word.

- Pure.
- Example: `to_upper('straße')` gives `'STRASSE'`

#### `to_lower`

```camel
to_lower: (s: string) => string
```

s with every letter in lower case, by the same mapping as `to_upper`: `'İ'` is `'i'` followed
by a combining dot above, and `'I'` is `'i'`.

- Pure.
- Example: `to_lower('ÀÉÎ Привет')` gives `'àéî привет'`

### Searching

#### `index_of`

```camel
index_of: <sub: string> (s: string) => int?
```

The index (in code points) of the first occurrence of sub in s, or null when there is none.
An empty sub is found at 0.

- Example: `'hello'->index_of<'l'>` gives `2`

#### `starts_with`

```camel
starts_with: <prefix: string> (s: string) => bool
```

Whether s begins with prefix. Every string begins with the empty string.

- Example: `'hello'->starts_with<'he'>` gives `true`

#### `ends_with`

```camel
ends_with: <suffix: string> (s: string) => bool
```

Whether s ends with suffix. Every string ends with the empty string.

- Example: `'hello'->ends_with<'lo'>` gives `true`

#### `strip_prefix`

```camel
strip_prefix: <prefix: string> (s: string) => string?
```

s without the prefix at its start, or null when s does not begin with it.

- Example: `'v1.2'->strip_prefix<'v'>` gives `'1.2'`

#### `strip_suffix`

```camel
strip_suffix: <suffix: string> (s: string) => string?
```

s without the suffix at its end, or null when s does not end with it.

- Example: `'a.cml'->strip_suffix<'.cml'>` gives `'a'`

### Cutting and joining

#### `split`

```camel
split: <sep: string> (s: string) => string[]
```

The pieces of s between occurrences of sep. An empty s gives one empty piece; a separator at
the start or the end gives an empty piece there. An empty sep cuts s into its code points
(no pieces for an empty s).

- Example: `'a,b,,c'->split<','>` gives `['a', 'b', '', 'c']`

#### `lines`

```camel
lines: (s: string) => string[]
```

The lines of s, cut at a line feed or a carriage return followed by a line feed. A line
feed at the very end does not start another line.

- Example: `'a\r\nb\n'->lines` gives `['a', 'b']`

#### `replace`

```camel
replace: <old: string, new: string> (s: string) => string
```

s with every occurrence of old replaced by new, found from left to right without overlap.
An empty old puts new between the code points of s.

- Example: `'a-b-c'->replace<'-', '+'>` gives `'a+b+c'`

#### `repeat`

```camel
repeat: <count: int> (s: string) => string
```

s written count times in a row; the empty string when count is not positive.

- Example: `'ab'->repeat<3>` gives `'ababab'`

### White space

#### `trim_start`

```camel
trim_start: (s: string) => string
```

s without the ASCII white space (space, tab, line feed, carriage return, vertical tab, form
feed) at its start.

- Example: `trim_start('  hi  ')` gives `'hi  '`

#### `trim_end`

```camel
trim_end: (s: string) => string
```

s without the ASCII white space at its end.

- Example: `trim_end('  hi  ')` gives `'  hi'`

#### `trim`

```camel
trim: (s: string) => string
```

s without the ASCII white space at both ends. Other white space, such as U+00A0, is kept.

- Example: `trim('  hi \n')` gives `'hi'`

<a id="bytes"></a>

## `bytes`: immutable binary values and UTF-8 conversion

Binary data. `Bytes` is an immutable value of the core; a string is text and never holds
arbitrary bytes, so the only crossing between the two is `encode` and `decode`.

Length (`len`), concatenation (`a + b`) and cutting (`b[a:b]`) are the core's, as they are for
a string. What is here converts, and is native: a `Bytes` is a data block, and reading or
building one needs the layout control the language does not show (design principles 10.4).

#### `encode`

```camel
encode: (text: string) => Bytes
```

The UTF-8 bytes of text.

- Pure.
- Example: `encode('hello')`

#### `decode`

```camel
decode: (content: Bytes) => string!
```

The text the bytes spell. Bytes that are not valid UTF-8 are an error value, not a fault: they
come from the outside world.

- Pure.
- Failure: error `EncodingError` when the bytes are not valid UTF-8 or the text is larger than a string can be.
- Example: `decode(encode('中文')) !! ''` gives `'中文'`

#### `from_array`

```camel
from_array: (values: int[]) => Bytes
```

The bytes with the given values.

- Pure.
- Failure: fault `InvalidArgument` when an element is outside 0..255.
- Example: `from_array([0, 128, 255])`

#### `to_array`

```camel
to_array: (content: Bytes) => int[]
```

The values of the bytes, each in 0..255.

- Pure.
- Example: `to_array(encode('AB'))` gives `[65, 66]`

<a id="ckpt"></a>

## `ckpt`: parameter trees and checkpoints

Checkpoints of a parameter tree. A tree is a struct or a tuple whose members are trees or
leaves; a checkpoint holds the leaves an array of numbers, `Bytes`, `string`, `bool`, `i32`,
`int`, `f32` and `float` can be written as (`has_ckpt_form`), and a tree with any other leaf is
refused where the call is written.

The tree is the data, the directory is where it goes: `tree->save_tree<dir: 'out/ckpt'>` and
`'out/ckpt'->load_tree::<T>`. A failure of the file system is an error value; a directory that
holds something other than a tree of the type asked for is an error value too. Walking a tree is
the tree library's (`stdlib/tree.cml`), not this module's.

A checkpoint here is what is written down, not what is recomputed: the transform that trades
memory for recomputation (the same values, the annotated section recomputed in the backward pass)
is named `remat` in this standard library, and never `checkpoint` -- so a name in a gradient that
says checkpoint is this module, and a name that says `remat` is that transform.

#### `tree_leaves`

```camel
tree_leaves: (tree: T) => L
```

The leaves of a tree, as a tuple.

- Pure.
- Example: `tree_leaves({ a: 1, b: (2, 3) })` gives `(1, 2, 3)`

#### `save_tree`

```camel
save_tree: <dir: string, dataset_manifest_sha256: string? = null> (tree: T) => void! uses fs when has_ckpt_form::<T>()
```

Saves a tree to a directory, one file per leaf named by its path (`blocks.0.w.npy` for an
array), with a manifest that records the types, sizes and SHA-256 sums and, when
`dataset_manifest_sha256` is given, that hash of the data manifest. The directory is replaced as
a whole or not at all: the new checkpoint is written and flushed into a temporary sibling and
renamed into place, and the old directory is kept beside it as the hidden sibling
`.<name>.ckpt-previous` until that rename succeeds, so a failure puts the old directory back. A
destination that does not exist is created; one that does is replaced; a symbolic link there is
refused. If the process dies between the two renames, `load_tree` reads the sibling and the
next `save_tree` restores it before replacing it. Only one writer may save to a directory at a
time; one of two racing saves fails, and a reader still sees a complete checkpoint.

- Failure: error value `PermissionDenied` when the file system refuses a write; error value `IOError` when the directory cannot be written or published, or a symbolic link is in the way.
- Example: `{ w: 1.0, step: 10 }->save_tree<dir: 'out/ckpt'>`

#### `load_tree`

```camel
load_tree: <dataset_manifest_sha256: string? = null> (dir: string) => T! uses fs, stderr when has_ckpt_form::<T>()
```

Reads a tree of the type T back from a directory `save_tree` wrote, checking the structure, the
types, the sizes and the SHA-256 sums first: nothing is partly loaded. A
`dataset_manifest_sha256` that differs from the one the checkpoint records is a warning on
standard error, not an error. T is the explicit type argument or the expected type of the
result. When a save was interrupted after moving the old directory aside, the complete
`.<name>.ckpt-previous` sibling is read instead, with a warning on standard error.

- Failure: error value `NotFound` when there is no checkpoint at the path; error value `CheckpointError` when the directory does not hold a tree of the type T, or a file is missing or does not match its recorded sum.
- Example: `'out/ckpt'->load_tree::<{ w: float, step: int }> !! { w: 0.0, step: 0 }`

<a id="tree"></a>

## `tree`: parameter trees written in Camel

The parameter-tree library written in Camel (design principles 13.5): a tree is a value made
of nested structs and tuples, and everything else is a leaf.

`tree_paths`, `tree_map`, `tree_reduce` and `tree_unzip` are written here, with `match type`,
`static for`/`static loop`, `fields`, `indices`, `typeof` and rest parameters: the walk is
expanded at each call into ordinary access and fill nodes, with no function of its own per
leaf type. Each exported function recurses itself. `unzip_at` stays: it is not a hand-off but
the walk of one component of the leaf tuple. Nothing here inspects a type when the program
runs: the fields of a type are walked while the call is compiled.

`tree_leaves` is not here yet. The leaves are one flat tuple whose length is the sum of the
leaves of every field, and Camel cannot splice a tuple value's elements into a tuple being
built: `( ...ts )` is not written (a rest argument is only a call argument), and a function
with a rest parameter has no value to return. It stays `ckpt:tree_leaves` until value-tuple
expansion exists.

The path of a leaf is its field names (tuple indices) from the root, joined by dots; the
root's own path is the empty string. The path values are ordinary strings, so the result is
the same tree with a `string` at every leaf.

#### `tree_paths`

```camel
tree_paths: (t: T, here: string = '') => ?
```

The path of every leaf, as a tree of the same shape. `here` is the path of `t` itself; the
caller leaves it out.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `tree_paths({ a: 1, b: (2, 3) })` gives `{ a: 'a', b: ('b.0', 'b.1') }`

#### `tree_map`

```camel
tree_map: <f: F> (t: T, ...ts) => ?
```

Applies f to the leaves in the same place of the trees (one tree, or several of the same
shape: the callback then takes one leaf of each), and gives a tree of the results. The shape
is that of the first tree.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `tree_map<(x: int): int => x + 1>({ a: 1, b: (2, 3) })` gives `{ a: 2, b: (3, 4) }`

#### `tree_reduce`

```camel
tree_reduce: <f: (acc: R, leaf: A) => R> (t: T, init: R) => R
```

Folds the leaves from the first to the last with f, starting from init.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `tree_reduce<(acc: int, x: int): int => acc + x>({ a: 1, b: (2, 3) }, 0)` gives `6`

#### `tree_unzip`

```camel
tree_unzip: (r: R, s: S) => ?
```

Turns a tree of tuples into a tuple of trees: the shape is that of `reference`, and every
leaf of `tree` at a leaf of the reference is a tuple of the same length.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `tree_unzip({ a: (1, 2.0) }, { a: 0 })` gives `({ a: 1 }, { a: 2.0 })`

<a id="transforms"></a>

## `transforms`: program transforms

#### `jvp`

```camel
jvp: (f: F) => Jvp<F> when is_function::<F>()
```

Forward mode: `jvp(f)` gives a function that takes the parameters of `f` followed by their
tangents and returns the pair `(value, tangent)`. `jvp(f)(2.0, 1.0)` is the value `f(2.0)`
together with the derivative of `f` at 2 in the direction 1.

- Example: `let forward = jvp((x: float) => x * x)`

#### `split`

```camel
split: (f: (v: float, d: float) => (float, float)) => (v: float, d: float) => (float, (float, float) => float)
```

The step of `vjp` that separates a lifted function into the part computable now and the linear
residue (design 4.2, 4.4). Implemented for the straight-line tier (`modules/transforms/split.cpp`):
the halves are built from the graph, and what crosses the cut -- the residuals -- is read off the
graph too, so a body that needs a value it computed carries it instead of computing it again.

The cut, as the author rules it (15:25; revised 2026-11-01 and 2026-11-02 08:30): the front half
takes the ordinary parameters and answers `(result, lin)`; `lin` is the back half, closed over the
residuals -- the values it reads -- and takes the tangents and nothing else.

    split(f) = (fwd)  where  fwd(...values) = (result, lin)
    lin      = the back half, its residuals captured rather than passed

The residuals are therefore **not a position in any type**: they are `lin`'s closure tuple, whose
layout the run-time kernel reads off the back half's graph (the capture ports the graph declares),
one member per residual, in the order the graph names them. At a call site `lin` is an ordinary
function type, so no signature states a count it cannot know and no guard has to admit one
(`ResidualsOf<F>`, and the `_` position before it, are both gone). `lin` is linear in the tangent
it is given -- the condition the transpose step (M3) reads -- and both halves speak in `Tangent<T>`
at the top of this file.

- Example: `let step = split`

#### `transpose`

```camel
transpose: (f: F) => Transpose<F> when is_function::<F>()
```

The transpose of a linear function: `transpose(f)` takes the cotangent of `f`'s result and
gives the cotangent of its parameter. The data flow runs backwards -- each primitive is replaced
by the rule the `rulesets.transpose` family files under it, and a value used k times receives k
cotangents that add. `f(x) = 2*x + 3*x` transposed at the cotangent `1.0` gives `5.0`.

The transposed function takes one value, the cotangent of `f`'s result, and answers one cotangent
per parameter. Both lists are `f`'s own: every parameter of `f` is a linear input, and the
cotangent it is answered for is the one the caller hands in.

A value the transposed body needs beside the cotangent is not passed to it: it is a residual the
function that is transposed was closed over, and the body reads it as a closure port. That is the
same rule for a value the body computed, a value it read from outside, and a `with` value it read
(`lin`'s residual tuple): a parameter with no tangent space is a value, and it is the one place
the transposed graph takes a port that is not a cotangent, because the call site still fills it.

**`stdlib/types.cml#Transpose` is the contract**: the build makes the declared type, and the build
that makes it is `modules/transforms/transpose.cpp#transposeSignature`. So `transpose(f)` is
called as `transpose(f)(1.0)` for a one-`float` function -- one argument, the cotangent.

- Example: `let back = transpose((x: float) => 2.0 * x + 3.0 * x)`

#### `vmap`

```camel
vmap: (f: F) => Vmap<F> when is_function::<F>()
```

Batching: `vmap(f)` gives the function that applies `f` to every row of a batch. A row is one
dimension less than the batch: for `f: (f32) => f32` it is `(f32[]) => f32[]`, and for
`f: (f32[3]) => f32` it is `(f32[?, 3]) => f32[]` -- `Lift<T> = RowsOf<T>`, the value with one
dimension of unknown length in front of it (`stdlib/types.cml`). The arithmetic of every
elementwise primitive is that primitive (`bx + bw` is `x + w` element by element), which is why
`vmap(f)(xs)` and the row-by-row `map` answer the same bits.

The rules come from `stdlib/rulesets/vmap.cml`: the transform asks that family, by the operator's
key, for every primitive of `f`, and calls the function the rule names with the batches. An
operator with no rule is refused by name at the primitive, never batched by a guess; a call, a
branch or a loop in the body is refused the same way, because the elementwise tier batches
straight-line bodies.

- Example: `let batched = vmap((x: f32) => x * 2.0)`

#### `remat`

```camel
remat: (f: F) => F when is_function::<F>()
```

Memory for recomputation: `remat(f)` gives a function whose graph is `f`'s graph with the
property "a call of it is recomputed on the backward pass instead of kept" (the author's ruling
of 2026-11-01). The property is the graph's, not the call site's and not a tag's: the call
answers with a new graph whose body is the body it was given, so a call through it is a call of
the same function and no value changes -- what changes is what a step that cuts the graph in two
has to keep across the cut. `split` reads the property: the values of a marked graph that cannot
be recomputed from the parameters are not residuals, and the backward half computes them again
(`modules/transforms/split.cpp`). JAX writes the same transform as `jax.checkpoint`, whose other
name is `jax.remat`; in this tree "checkpoint" is the persistence module `ckpt`, so the transform
takes the other word.

The type is the argument's own: a function in, the same function out, which is the whole of what
the name says. `modules/transforms/remat_operator.cpp` answers `(f: F) => F` and builds the graph
the value stands on; the shapes a call site can write today are the ones `jvp`'s and `split`'s
declarations show, because the result of a call is the exit type its resolver gives.

- Example: `let remembered = remat((x: int) => x + 1)`

#### `first_with_as_param`

```camel
first_with_as_param: (f: F) => FirstWithAsParam<F> when is_function::<F>()
```

The signature reinterpretation: `f` with its first `with` parameter moved onto the front of the
ordinary list, and its body untouched. The design's name for this kind of step is
`reinterp<first_with_as_param>(f)` (design principles 9.9: `reinterp<H>(f)` gives every primitive
the meaning `H` gives it); in this tree the kind is the operator's own name, the way `jvp(f)` is
`reinterp<jvp>(f)`, because a pass cannot answer a function value.

The body is not read, rewritten or re-derived -- the one thing that differs is which list a port
is in -- and a `with` value the body reads is read through a port like any other value, so a
reclassification of the port is the whole of the transform
(`modules/transforms/first_with_as_param_operator.cpp`). The transform is what makes a weight
differentiable by the library's composition: a `with` parameter has no place to take a direction
in from, and an ordinary one has.

Three shapes have no first `with` parameter to move, and each is refused where it is written: a
function with a `with` pack (the pack stands for however many arguments a call gives past the
fixed ones, so it has no first member), a `var` `with` parameter (a variable is read and written
by name, not handed in by a call), and a `constas` one (part of the signature's identity rather
than a value).

- Example (a fragment, not compiled): `let reinterpreted = first_with_as_param(weighted)`
- Why it is not compiled: `weighted` is a function the program declares, because the example needs a `with` parameter

<a id="vjp"></a>

## `vjp`: the derivative, as a library

#### `vjp`

```camel
vjp: (f: F) => Vjp<F> when is_function::<F>()
```

The reverse transform, in JAX's order (author's ruling of 2026-11-01): `vjp(f)(x)` gives the pair
`(y, pullback)`, and `pullback(ct)` gives the cotangents of `f`'s parameters, `ct`'s own weight one
member per parameter. The pullback is `lin`'s transpose, and that is the whole of the step: the
two have the shape `(ct) => (cotangents)` (author's ruling of 2026-11-02 11:30), so nothing is
wrapped around it.

The pullback answers a tuple in every case, one member per parameter, so a function of one
parameter has a one-long one -- `(27.0)` for `vjp(cube)(3.0)`'s pullback at `ct = 1.0` -- and the
number a gradient is comes out of it by position: `grad(f)(x)` is `vjp(f)(x).1(1.0).0` (author's
ruling of 2026-11-01 14:30: one rule for every arity, no exception for one parameter, no type
function that takes an element out of a one-long tuple).
The derivative of `f` with respect to its parameters: `vjp(f)(x, y, ...)` is the pair
`(value, pullback)`, and `pullback(ct)` answers the cotangents of the parameters -- one member per
parameter, so a function of one parameter has a one-long tuple (author's ruling of 2026-11-01: one
rule for every arity, no exception for one parameter, no type function that takes an element out of
a one-long tuple).

One declaration for every arity: `F` is the function, `Vjp<F>` says the parameters are `F`'s and the
pullback's cotangents are too (stdlib/types.cml), and `<...ws> (...xs)` takes both lists the
instantiated `Vjp<F>` has -- the `with` list and the parameters, each from the position the lambda
stands in (author's rulings of 2026-11-01 19:10 and 2026-11-03 13:50). The packs are values in the
body: `xs` is the tuple of the parameters and `ws` the tuple of `f`'s `with` values, so
`split(jvp(f))<...ws>(...xs)` hands the forward half the list it declares and the parameters it
takes. `transpose(lin)` takes no `with` argument and none is written for it: `lin` has no `with`
list, because the `with` value the backward half reads is a residual the cut captured in its
closure (author's ruling of 2026-11-03 15:15; `Pullback<F>` in stdlib/types.cml is
`(ct) => (...Tangent<ParamsOf<F>>)`, no list). So the `with` values are written once, where the
lambda receives them, and `split(jvp(f))<...ws>(...xs)` is the only place they appear. The lambda
writes the pack rather than naming the `with` parameters: `Vjp<F>` splices `WithOf<F>` as types,
and a body that read a name from there would depend on what the caller of `vjp` called its own
parameters.
The whole reading in one line: the function is written where the call is, so the example is a
program of its own -- `y` is `x * x` at 3, and the pullback read at `ct = 1.0` answers the
derivative there, one member per parameter.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `let (y, pullback) = vjp((x: float) => x * x)(3.0)` gives `y = 9.0, and pullback(1.0) is (6.0)`

#### `grad`

```camel
grad: (f: F) => GradientOf<F> when is_function::<F>()
```

The gradient of a function with respect to its first `with` parameter (design principles 9.9):
`grad(f)` takes the weight first and `f`'s own parameters after it, and answers the weight's
cotangent -- `grad(weighted)(3.0, 2.0)` for `<x: float> func weighted(y) = x*y + x`.

It is a composition and not a second transform: `vjp` read at the seed 1, its first cotangent
taken. The weight is on the ordinary list because that is the list `vjp` differentiates, so the
step before is `first_with_as_param` -- the signature reinterpretation that reclassifies that one
port and copies the body (`stdlib/signatures/transforms.cml`), which is why nothing in the
differentiated body reads a `with` value that would need a direction of its own.
`GradientOf<F>` (`stdlib/types.cml`) is the shape that falls out: the weight, then the parameters.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example (a fragment, not compiled): `let slope = grad(f)`
- Why it is not compiled: `f` is a function value, so the example is a fragment of a program that declares one

#### `has_aux`

```camel
has_aux: (f: (w: float) => (float, float)) => (w: float) => ((float, float), float)
```

The value, the auxiliary value and the gradient together, for a function whose result is the pair
`(value, aux)`: `has_aux(f)` gives a function of the weight that answers `((value, aux), gradient)`
-- the shape and the order the engine's `with_grad(f, has_aux: true)` answers, JAX's
`value_and_grad(f, has_aux=True)`. The weight is the one ordinary parameter `f` takes, as it is
for `grad` above: the library's names are functions of ordinary parameters, and the subject's
`with` values are closed over where the lambda is written.

The body is the composition, not a second transform, and it composes **forward**: `jvp(f)` is the
function `(w, dw) => (result, tangent)`, so `jvp(f)(w, 1.0)` reads one direction -- the weight's --
and answers the pair and the pair's tangent; the value's derivative is the tangent's first
member, because a pair's tangent is a pair in the same order (`core/tangent_space.h`). One pass
answers all three numbers.

The transposed half is not what this is written on, and the reason is the pair: `vjp`'s second
half turns the cotangent of what the function answers around, and a pair has no cotangent --
`transpose` takes a function whose result has one, which is why handing a pair-returning function
to `vjp` is refused rather than guessed at (`has_aux_vjp_pair` in
test/cases/modules/autodiff/). A pair **does** have a tangent space, which is what the forward
direction needs, so the composition that reads all three numbers is the one above.

The backward spelling of this body was tried and **refused by name** (2026-11-05): `split(jvp(f))`
read for `(pair, lin)`, the value member built as `(t) => lin(t).0`, and that member transposed at
the seed `1.0` -- the construction that does not invent a zero cotangent for the auxiliary
member. `transpose` cannot turn around a body that calls a **function value**: the mirrored graph
of `(t) => lin(t).0` needs a transposed graph for `lin`, `lin` is a value and not a named callee,
and the pass stops with `transforms: transpose has no transpose for this function: this call's
callee has no transpose of its own, so the call cannot be turned around`. The wall is
`transpose`'s (a written body whose callee arrives as a value), not this composition's, so this
name stays forward and the backward spelling waits for that rule.

The pair is carried and the auxiliary value is not differentiated: `frozen(w) = (1.0, w*w)`
answers a gradient of 0.0 with an auxiliary value of 9.0. The tangent's second member is the
auxiliary value's own slope; it is built (the lift answers the whole pair's direction) and not
read, which is what makes "carried, not differentiated" a fact about the body rather than about
the numbers it happens to print.

The shape is written once, for a weight of one `float` and a result of two, the way `grad` above
is written once for one parameter; the declarations whose parameters and results are packs are
what the generic form is written with when the library takes it, and this name keeps answering
that shape until then.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example (a fragment, not compiled): `let step = has_aux(loss)`
- Why it is not compiled: `loss` must be a function of one parameter whose result is a pair, and that takes a declaration, so the example is a fragment of a program that declares it

<a id="tensor"></a>

## `tensor`: multi-dimensional numeric arrays

The `tensor` module: multi-dimensional numeric arrays, their element type and extents, their
binary form, a NumPy file, and the module's worker threads.

The declarations written here are the operators a body-less declaration can state. It was once
thought that a name whose element type or shape follows its arguments could not be declared at
all — elementwise arithmetic, the reshaping operators, the axis forms of a reduction — but
`numel` and `shape` showed the limit is the generic parameter, not the operator: written as
`export func numel::<T>(t: T[...]): int when is_numeric::<T>()`, a name whose result type follows
its argument declares fine, and the axis reductions below are written the same way. What a
declaration still cannot state is a signature that depends on a *value* argument. The operators
whose signature the page renders from `stdlib/signatures/tensor.cml` are the ones left in C++
(design principles 6.4).

### Creation

#### `zeros`

```camel
zeros: (shape: int[]) => T[...] when is_numeric::<T>()
```

An array of the given extents whose elements are all 0. The element type is written
(`zeros::<f32>([2, 3])`) or comes from the position of the call (`let x: f32[2, 3] =
zeros([2, 3])`); there is no default.

- Pure.
- Example: `zeros::<f32>([2, 3])`

#### `ones`

```camel
ones: (shape: int[]) => T[...] when is_numeric::<T>()
```

An array of the given extents whose elements are all 1; the element type is the call's, as for
`zeros`.

- Pure.
- Example: `ones::<f32>([2, 3])`

#### `full`

```camel
full: (shape: int[], value: number) => float[...]
```

A tensor of the given extents whose elements are all value; the element type is the value's.

- Pure.
- Example: `full([2, 2], -1.0)`

#### `eye`

```camel
eye: (n: int) => T[...] when is_numeric::<T>()
```

The n by n identity matrix; the element type is the call's, as for `zeros`.

- Pure.
- Example: `eye::<f32>(2)`

### Elementwise

#### `maximum`

```camel
maximum: (lhs: float[...] | number, rhs: float[...] | number) => float[...]
```

IEEE 754-2019 maximum per element, with NumPy broadcasting: NaN on either side gives the
canonical quiet NaN, and -0 is below +0.

- Pure.
- Example: `maximum([1.0, -0.0] as float[], 0.0)` gives `[1.0, 0.0]`

#### `minimum`

```camel
minimum: (lhs: float[...] | number, rhs: float[...] | number) => float[...]
```

IEEE 754-2019 minimum per element, with NumPy broadcasting: NaN on either side gives the
canonical quiet NaN, and -0 is below +0.

- Pure.
- Example: `minimum([1.0, -0.0] as float[], 0.0)` gives `[0.0, -0.0]`

#### `where`

```camel
where: (cond: bool[...], lhs: float[...] | number, rhs: float[...] | number) => float[...]
```

lhs where cond holds, rhs elsewhere, broadcast to one shape; the element type is the wider of
lhs and rhs.

- Pure.
- Example: `where([true, false] as bool[], [1.0, 2.0] as float[], 0.0)` gives `[1.0, 0.0]`

#### `abs`

```camel
abs: (t: float[...]) => float[...]
```

|x| per element: the sign cleared.

- Pure.
- Example: `abs([-1.5, 2.0] as float[])` gives `[1.5, 2.0]`

#### `exp`

```camel
exp: (t: float[...]) => float[...]
```

e^x per element, within 2 ulp, subnormal results included.

- Pure.
- Example: `exp([0.0, 1.0] as float[])` gives `[1.0, 2.7182817]`

#### `log`

```camel
log: (t: float[...]) => float[...]
```

ln x per element, within 2 ulp; NaN, +-inf, +-0 and negative x are exact (negative x gives
NaN).

- Pure.
- Example: `log([1.0, 2.7182817] as float[])` gives `[0.0, 1.0]`

#### `sqrt`

```camel
sqrt: (t: float[...]) => float[...]
```

sqrt(x) per element, rounded once in `f32`.

- Pure.
- Example: `sqrt([4.0, 9.0] as float[])` gives `[2.0, 3.0]`

#### `rsqrt`

```camel
rsqrt: (t: float[...]) => float[...]
```

1 / sqrt(x) per element: two steps, each rounded in `f32`.

- Pure.
- Example: `rsqrt([4.0] as float[])` gives `[0.5]`

#### `sigmoid`

```camel
sigmoid: (t: float[...]) => float[...]
```

The logistic function 1 / (1 + e^-x) per element.

- Pure.
- Example: `sigmoid([0.0] as float[])` gives `[0.5]`

#### `tanh`

```camel
tanh: (t: float[...]) => float[...]
```

The hyperbolic tangent per element.

- Pure.
- Example: `tanh([0.0] as float[])` gives `[0.0]`

#### `relu`

```camel
relu: (t: float[...]) => float[...]
```

maximum(x, +0) per element: NaN gives the canonical NaN, and -0 gives +0.

- Pure.
- Example: `relu([-1.0, 2.0] as float[])` gives `[0.0, 2.0]`

#### `gelu`

```camel
gelu: (t: float[...]) => float[...]
```

The Gaussian error linear unit per element, computed as its normative definition in Camel.

- Pure.
- Example: `gelu([0.0] as float[])` gives `[0.0]`

#### `erf`

```camel
erf: (t: float[...]) => float[...]
```

The Gauss error function per element.

- Pure.
- Example: `erf([0.0] as float[])` gives `[0.0]`

#### `erfc`

```camel
erfc: (t: float[...]) => float[...]
```

The complementary error function 1 - erf(x) per element.

- Pure.
- Example: `erfc([0.0] as float[])` gives `[1.0]`

### Shape and reshaping

#### `reshape`

```camel
reshape: (t: float[...] | number[], shape: int[]) => float[...]
```

The elements in row-major order, in a new shape; one extent may be -1, which the element
count fills.

- Pure.
- Example: `reshape<[2, 2]>([1.0, 2.0, 3.0, 4.0] as float[])`

#### `unsqueeze`

```camel
unsqueeze: (t: float[...], axis: int) => float[...]
```

The elements unchanged, with an axis of extent 1 added at axis.

- Pure.
- Example: `unsqueeze<0>([1.0, 2.0] as float[])` gives `shape [1, 2]`

#### `transpose`

```camel
transpose: (t: float[...]) => float[...]
```

The last two axes swapped (a vector becomes a column, a matrix its transpose).

- Pure.
- Example: `transpose([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])`

#### `permute`

```camel
permute: (t: float[...], perm: int[]) => float[...]
```

The axes reordered as perm lists them.

- Pure.
- Example: `permute<[1, 0]>([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])`

#### `concat`

```camel
concat: (a: float[...] | number[], b: float[...] | number[], axis: int) => float[...]
```

a and b joined along axis; every other extent must agree.

- Pure.
- Example: `concat<0>([[1.0]] as float[1, 1], [[2.0]] as float[1, 1])` gives `shape [2, 1]`

#### `take`

```camel
take: (t: float[...], indices: int64[...] | number[]) => float[...]
```

The entries of the first axis that indices name, in that order.

- Pure.
- Failure: fault `RuntimeError` when an index is outside the first axis.
- Example: `take([[1.0], [2.0], [3.0]] as float[3, 1], [2, 0])` gives `[[3.0], [1.0]]`

#### `one_hot`

```camel
one_hot: (labels: int64[...] | number[], classes: int) => f32[...]
```

Each label (an integer below classes) expanded to a row of classes with a 1 at its position:
a `f32` tensor of shape [labels, classes], each row a distribution over the classes.

- Pure.
- Failure: fault `IndexOutOfRange` when a label is outside [0, classes), and fault `InvalidArgument` when classes is negative.
- Example: `one_hot([0, 2] as int[], 3)` gives `[[1.0, 0.0, 0.0], [0.0, 0.0, 1.0]]`

#### `shape`

```camel
shape: (t: T[...]) => int[] when is_numeric::<T>()
```

The extents of a tensor, in order.

- Pure.
- Example: `shape([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])` gives `[2, 2]`

#### `numel`

```camel
numel: (t: T[...]) => int when is_numeric::<T>()
```

The number of elements in a tensor: the product of its extents.

- Pure.
- Example: `numel(zeros::<f32>([2, 3]))` gives `6`

#### `dim`

```camel
dim: <axis: int> (t: T[...]) => int when is_numeric::<T>()
dim: <axis: i32> (t: T[...]) => int when is_numeric::<T>()
```

The extent of one axis; a negative axis counts from the last one (`-1` is the last axis).

- Pure.
- Failure: fault `RuntimeError` when the axis is outside the rank.
- Example: `dim<1>(zeros::<f32>([2, 2]))` gives `2`

#### `pick_at`

```camel
pick_at: (t: T[...], position: int, length: int) => T when is_numeric::<T>()
```

The element at `position` of a rank-1 tensor whose length is `length`: `t[position]`, with the
length stated by whoever holds the value.

The length is a **known operand**, and it is the reason this spelling exists beside the
language's own `t[i]`. A transpose rule may read only known operands (author, 2026-11-03 11:10),
and `T[]` carries no length in its type (design principles 5.4), so the law that scatters a
cotangent back into the array's shape (9.9: the reverse of a gather is a scatter-add) has nothing
to build the zeros from unless the value's length is handed to it. A forward half can state it --
`rulesets.jvp`'s `jvp_idx_arr` passes `len(xs)`, a value of the primal -- and this operator is
what it passes it to.

The position and the length are two parameters of their own sorts and not one list. They were a
list while this read was written, because the transpose walk was believed to answer an operator
with one or two normal operands and two integers beside the tensor would have been three. The
walk's refusal is about a third **tensor**, not a third parameter (`take_stated` takes two
`int[]` operands beside its tensor), so the count was never this operator's limit: each value
now says which it is, and a reader of a law does not count positions in a list.

The stated length is checked against the tensor and the position against both, so a wrong length
is a fault rather than an array of the wrong shape.

- Pure.
- Failure: fault `RuntimeError` when `length` disagrees with the tensor, or `position` is outside it.
- Example: `pick_at([1.0, 2.0, 3.0] as float[], 2, 3)` gives `3.0`

### Reduction

#### `sum`

```camel
sum: (t: T[...]) => T
```

The sum of every element, in the operand's element type: the canonical form of the element
type `T` is `sum::<T>(x: T[...]): T = T(sum(float(x)))`, so the elements are widened into an
`f64` accumulator (`float(x)`), the additions happen in `f64` in row-major order from +0, and
their sum is rounded into `T` once, at the end — the same element type and the same one
rounding as the axis form below, so the full form and the axis form agree bit for bit
(design principles 7.3). An `int64`, `int32` or `bool` tensor has no float accumulator: it is
summed exactly in `int64`, wrapping on overflow as integer arithmetic does (design principles
5.1, 7.7), and that exact value is the answer — `int64` as it stands, `int32` truncated into
its element type, `bool` as `int64`.

- Pure.
- Example: `sum([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])` gives `10.0`

#### `sum`

```camel
sum: <axis: int, keepdims: bool = false> (t: T[...]) => T[...]
```

The sum of each lane along one axis, accumulated in `f64` from `+0` in ascending order and
rounded once into the element type. The axis and the flag are the call's `with` arguments --
`sum<0>`, `sum<1, true>` -- under the whole reduction's name (design principles 7.3), and
`keepdims` leaves the reduced axis as an extent of one.
The result's extents are the operand's, with that axis removed or kept as an extent of one, so
the type a call reads states them (`float[2, 3]` along axis 0 is a `float[3]`).

- Pure.
- Failure: fault `RuntimeError` when the axis is outside the rank.
- Example: `sum<0>([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])` gives `[4.0, 6.0]`

#### `mean`

```camel
mean: (t: T[...]) => T
```

The mean of every element, in the operand's element type, with one rounding: the canonical
form of the element type `T` is `mean::<T>(x: T[...]): T = T(sum(float(x)) / float(numel(x)))`.
The sum and the division by the element count both happen in `f64`, and their result is
rounded into `T` once — never a sum rounded to the element type and divided again, which
would round twice. A mean of an integer or bool tensor is `f32`, as by axis; an empty tensor
is a fault.

- Pure.
- Failure: fault `DivisionByZero` when the tensor has no element.
- Example: `mean([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])` gives `2.5`

#### `mean`

```camel
mean: <axis: int, keepdims: bool = false> (t: T[...]) => T[...]
```

The mean of each lane along one axis: the sum and the count both in `f64`, one rounding into
the element type. An empty axis is a fault. The axis and the flag are the call's `with`
arguments -- `mean<0>`, `mean<1, true>` -- under the whole reduction's name (design principles
7.3). The result's extents are the operand's, with that axis removed or kept as an extent of
one.

- Pure.
- Failure: fault `RuntimeError` when the axis is outside the rank, and fault `DivisionByZero` when the axis is empty.
- Example: `mean<1>([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])` gives `[1.5, 3.5]`

#### `max`

```camel
max: (t: T[...]) => T
```

IEEE 754-2019 maximum of every element (design principles 7.7): a NaN anywhere gives `nan`, and
-0 is below +0. An extremum has no identity, so a tensor with no element is a fault rather than
an answer. The axis form below is the same name, chosen by arity (design principles 7.3).

- Pure.
- Failure: fault `InvalidArgument` when the tensor has no element.
- Example: `max([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])` gives `4.0`

#### `min`

```camel
min: (t: T[...]) => T
```

IEEE 754-2019 minimum of every element: a NaN anywhere gives `nan`, and -0 is below +0. A tensor
with no element is a fault.

- Pure.
- Failure: fault `InvalidArgument` when the tensor has no element.
- Example: `min([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])` gives `1.0`

#### `argmax`

```camel
argmax: (t: T[...]) => int
```

The position of the maximum of every element, counted in row-major order and answered as an
`int`: the first NaN's position if there is one, +0 above -0, and the earliest position on a
tie (design principles 7.7). A tensor with no element is a fault.

- Pure.
- Failure: fault `InvalidArgument` when the tensor has no element.
- Example: `argmax([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])` gives `3`

#### `argmin`

```camel
argmin: (t: T[...]) => int
```

The position of the minimum of every element, counted in row-major order and answered as an
`int`: the first NaN's position if there is one, -0 below +0, and the earliest position on a
tie. A tensor with no element is a fault.

- Pure.
- Failure: fault `InvalidArgument` when the tensor has no element.
- Example: `argmin([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])` gives `0`

#### `max`

```camel
max: <axis: int, keepdims: bool = false> (t: T[...]) => T[...]
```

The largest element of each lane along one axis. An empty axis is a fault, as for the whole
tensor. The axis and the flag are the call's `with` arguments -- `max<0>`, `max<1, true>` --
under the whole reduction's name (design principles 7.3). The result's extents are the
operand's, with that axis removed or kept.

- Pure.
- Failure: fault `RuntimeError` when the axis is outside the rank, and fault `InvalidArgument` when the axis has no element.
- Example: `max<0>([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])` gives `[3.0, 4.0]`

#### `min`

```camel
min: <axis: int, keepdims: bool = false> (t: T[...]) => T[...]
```

The smallest element of each lane along one axis. An empty axis is a fault: a minimum over no
element has no identity to return. The axis and the flag are the call's `with` arguments --
`min<1>`, `min<0, true>` -- under the whole reduction's name (design principles 7.3). The
result's extents are the operand's, with that axis removed or kept.

- Pure.
- Failure: fault `RuntimeError` when the axis is outside the rank, and fault `InvalidArgument` when the axis has no element.
- Example: `min<1>([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])` gives `[1.0, 3.0]`

#### `argmax`

```camel
argmax: <axis: int, keepdims: bool = false> (t: float[...]) => int64[...]
```

The position of the largest element of each lane along one axis, an `int` index along that
axis. A tie keeps the earlier position. An empty axis is a fault. The axis and the flag are the
call's `with` arguments -- `argmax<1>`, `argmax<0, true>` -- under the whole reduction's name
(design principles 7.3). The result's extents are the operand's, with that axis removed or
kept.

- Pure.
- Failure: fault `RuntimeError` when the axis is outside the rank, and fault `InvalidArgument` when the axis has no element.
- Example: `argmax<1>([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])` gives `[1, 1]`

#### `argmin`

```camel
argmin: <axis: int, keepdims: bool = false> (t: float[...]) => int64[...]
```

The position of the smallest element of each lane along one axis; a tie keeps the earlier
position. An empty axis is a fault. The axis and the flag are the call's `with` arguments --
`argmin<0>`, `argmin<1, true>` -- under the whole reduction's name (design principles 7.3). The
result's extents are the operand's, with that axis removed or kept.

- Pure.
- Failure: fault `RuntimeError` when the axis is outside the rank, and fault `InvalidArgument` when the axis has no element.
- Example: `argmin<0>([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])` gives `[0, 0]`

### The reductions with their extents stated

#### `mean_axis_stated`

```camel
mean_axis_stated: (t: T[...], axis: int, keepdims: bool, extents: int[]) => T[...]
```

The mean of each lane along one axis, with the axis, `keepdims` and the operand's extents stated
as parameters of their own: `mean_axis_stated(t, axis, keepdims, extents)` is
`mean<axis, keepdims>(t)`.

The result is the axis mean's at the stated extents: the operand's, with the `axis` removed, or kept
as an extent of one when `keepdims`. It is computed rather than declared because those extents
follow from values, so a call that states all three states its own result -- `0, false, [4]` over a
rank-1 operand is the element, not `float[...]` and a conversion -- and a call whose parameters are
values of the run states the operand's element type at a rank nobody fixed.

- Pure.
- Failure: fault `RuntimeError` when the extents disagree with the tensor's shape, or the axis is outside the rank.
- Example: `mean_axis_stated([[1.0, 2.0], [3.0, 4.0]] as float[2, 2], 0, true, [2, 2])` gives `[[2.0, 3.0]]`

#### `softmax`

```camel
softmax: (t: f32[...], axis?: int) => f32[...]
```

The softmax over the axis (-1, the last axis, by default), computed as its normative
definition in Camel, in `f32`.

- Pure.
- Failure: fault `RuntimeError` when the axis is outside the rank.
- Example: `softmax([1.0, 1.0] as f32[])` gives `[0.5, 0.5]`

#### `softmax`

```camel
softmax: (t: float[...], axis?: int) => float[...]
```

The same softmax of an `f64` tensor: the kernel takes the element type of the tensor it is
given, so the result is `f64` as well.

- Pure.
- Failure: fault `RuntimeError` when the axis is outside the rank.
- Example: `softmax([[1.0, 1.0]] as float[1, 2])` gives `[[0.5, 0.5]]`

#### `log_softmax`

```camel
log_softmax: (t: f32[...], axis?: int) => f32[...]
```

The log of the softmax over the axis (-1 by default), computed as its normative definition in
Camel, in `f32`.

- Pure.
- Failure: fault `RuntimeError` when the axis is outside the rank.
- Example: `log_softmax([1.0, 1.0] as f32[])` gives `[-0.6931472, -0.6931472]`

#### `log_softmax`

```camel
log_softmax: (t: float[...], axis?: int) => float[...]
```

The same log softmax of an `f64` tensor, in `f64`.

- Pure.
- Failure: fault `RuntimeError` when the axis is outside the rank.
- Example: `log_softmax([[1.0, 1.0]] as float[1, 2])` gives `[[-0.6931472, -0.6931472]]`

#### `softmax_grad`

```camel
softmax_grad: (y: f32[...], dy: f32[...], axis?: int) => f32[...]
```

The gradient of the softmax of y with the incoming gradient dy, over the axis (-1 by default).

- Pure.
- Failure: fault `RuntimeError` when the axis is outside the rank.
- Example: `softmax_grad(y, dy)`

#### `softmax_grad`

```camel
softmax_grad: (y: float[...], dy: float[...], axis?: int) => float[...]
```

The same gradient in `f64`: y and dy are `f64` tensors and the result is one too.

- Pure.
- Failure: fault `RuntimeError` when the axis is outside the rank.
- Example: `softmax_grad(y, dy)`

#### `layer_norm`

```camel
layer_norm: (x: f32[...], gamma: f32[...], beta: f32[...], eps?: number) => f32[...]
```

Layer normalization of x with gamma and beta, whose extents are the trailing ones of x, over
the trailing axes; eps is 1e-5 by default. The result is `f32`.

- Pure.
- Failure: fault `TensorDimensionMismatch` when gamma or beta does not match the trailing extents of x.
- Example: `layer_norm(x, gamma, beta)`

#### `layer_norm`

```camel
layer_norm: (x: float[...], gamma: float[...], beta: float[...], eps?: number) => float[...]
```

The same normalization of `f64` tensors, in `f64`: x, gamma and beta are `f64` and the result
is one too.

- Pure.
- Failure: fault `TensorDimensionMismatch` when gamma or beta does not match the trailing extents of x.
- Example: `layer_norm(x, gamma, beta)`

### Linear algebra

#### `matmul`

```camel
matmul: (lhs: float[...], rhs: float[...]) => float[...]
```

The matrix product of lhs and rhs: per output element acc = +0, then acc = fma(a[i][k],
b[k][j], acc) for k ascending, every fused multiply-add rounded once in `f32`.

- Pure.
- Failure: fault `TensorDimensionMismatch` when the inner extents do not agree.
- Example: `matmul([[1.0, 2.0]] as float[1, 2], [[3.0], [4.0]] as float[2, 1])` gives `[[11.0]]`

#### `linear`

```camel
linear: (x: f32[...], weight: f32[...], bias?: f32[...]) => f32[...]
```

The affine transform of x by a rank-2 weight [in, out] whose rows are the features of x, plus
a rank-1 bias [out] when given.

- Pure.
- Failure: fault `TensorDimensionMismatch` when the features of x are not the rows of weight, or bias is not rank 1 of the output extent.
- Example: `linear(x, weight, bias)`

#### `linear`

```camel
linear: (x: float[...], weight: float[...], bias?: float[...]) => float[...]
```

The same transform of `f64` operands, in `f64`: it takes the element type of its operands
(the `f32` path is the fused one, the other element types go through `matmul` and the addition).

- Pure.
- Failure: fault `TensorDimensionMismatch` when the features of x are not the rows of weight, or bias is not rank 1 of the output extent.
- Example: `linear(x, weight, bias)`

### Gradient

#### `zeros_like`

```camel
zeros_like: (t: float[...]) => float[...]
```

A tensor of zeros shaped and typed like t.

- Pure.
- Example: `zeros_like([[1.0, 2.0]] as float[1, 2])`

#### `ones_like`

```camel
ones_like: (t: float[...]) => float[...]
```

A tensor of ones shaped and typed like t.

- Pure.
- Example: `ones_like([[1.0, 2.0]] as float[1, 2])`

### Conversion and display

#### `load_npy`

```camel
load_npy: (path: string) => T[...]
```

The tensor a NumPy `.npy` file holds, as the element type the program declares: the extents are
the file's (read them with `shape`, or check them with `as`), and the file's element type must
be `T` -- a file of another element type is a fault, never a conversion (design principles 5.1,
5.5). `T` is `f32`, `f64`, `i32`, `i64` or `bool`, the element types the format's storage types
(`'<f4'`, `'<f8'`, `'<i4'`, `'<i8'`, `'|b1'`) map to, exactly the type given. It is written at
the call (`load_npy::<f32>(p)`) or taken from the type of the position the call stands in
(`f32[3]`, `f32[...]`); `T` is the one type variable no parameter mentions, so a call
that says neither is not a use of this operator.

- With effects: reads a file.
- Failure: fault `RuntimeError` when the file is missing, is not a NumPy file, holds a storage type the module does not read, or holds another element type than `T`.
- Example: `load_npy::<f32>('x.npy')`

#### `show`

```camel
show: (t: A[...]) => void when is_numeric::<A>() || is_same::<A, bool>()
```

Prints t to the console, in the module's layout.

The elements are the ones a tensor stores -- the numbers and the booleans (`x * s`, a bool's
gradient and the widths the kernels carry are all read at those, modules/tensor/dtype.cpp
`isSupportedTensorScalar`) -- and the parameter says so, so an element type no kernel can read
is refused at the call and not left to the runtime. The parameter takes `A[...]`, which includes
rank 0 (design principles 5.4), so the condition is what keeps a `string` from being read as one
element of a rank-zero array.

- With effects: writes the console.
- Example: `show([[1.0, 2.0]] as float[1, 2])`

### Binary form

#### `from_bytes`

```camel
from_bytes: (bytes: Bytes, shape: int[]) => T[...] when is_plain::<T>()
```

An array of the given shape made of little-endian elements: the payload `to_bytes` wrote. The
element type is the explicit type argument (`from_bytes::<f32>(b, [2])`) or comes from the
expected type of the result; it is `f32`, `f64`, `bf16`, `f16`, `i32`, `i64` or `bool`, exactly
the type given, or a struct or tuple whose fields are all pure data, which takes its element
type from the call (`from_bytes::<P>(b, [2])`) -- a declaration's parameters cannot mention a
type variable that only the result mentions. The element's bytes are its layout's, written as
`to_bytes` wrote them. A byte count that does not fit the shape is a fault. The bits are
copied: reading `bf16` or `f16` here passes the stored values through without rounding, so it
needs no numeric permission.

- Pure.
- Failure: fault `TensorDimensionMismatch` when the number of bytes does not fit the shape and the element type.
- Example: `from_bytes::<f32>(to_bytes([1.0, 2.0] as float[]), [2])`

#### `to_bytes`

```camel
to_bytes: (t: T[...]) => Bytes when is_plain::<T>()
```

The elements of a tensor as little-endian bytes, in row-major order: the payload `from_bytes`
reads back. The elements are the tensor's own bytes, so every pure-data element type has them:
one byte an element for a `bool` tensor, four for an `f32` one and eight for an `f64` or `c64`
one.

- Pure.
- Example: `to_bytes([1.0, 2.0] as float[])` gives `[0, 0, 128, 63, 0, 0, 0, 64]`

#### `save_npy`

```camel
save_npy: (t: T[...], path: string) => void when is_numeric::<T>()
```

Writes a tensor to a NumPy `.npy` file, replacing it.

- With effects: writes a file.
- Failure: fault `RuntimeError` when the file cannot be written.
- Example: `save_npy(zeros::<f32>([2, 2]), 'x.npy')`

### The same operations, with the extents the reverse law needs

A reduction and a gather both forget something a pullback has to put back: `sum` forgets how many
elements it added, `take` forgets how many rows it read from, and `mean` over an axis forgets the
lane. The reverse of each spreads one cotangent over *that* shape, and it cannot read the shape
off the operand: a transpose rule may read only **known** operands (author, 2026-11-03 11:10 and
17:35), and the operand a cotangent comes back through has no value on that side -- while `T[...]`
carries no extents in its type (design principles 5.4).

So the forward half states them, and these declarations are what it states them to. Each is the
operation above it with one more operand, an `int[]` the value does not need and the reverse law
reads instead of the array. `pick_at` is the same arrangement for the read: `length` is the number
`xs[i]` cannot state for itself.

The extents travel in one list because that is the list the reverse law wants whole: the axis and
the flag decide which extents are lanes and the extents decide where each lane's cotangent goes, so
one argument holds the three facts the adjoint reads and the value spends on nothing. (The number
of ordinary ports is not the constraint it once was: the walk used to refuse a third position before
looking for a law, and `TransposeRefusalCause` no longer has that cause -- the two extrema below take
a third port, their tie selection, which no extent list could carry.)

#### `sum_stated`

```camel
sum_stated: (t: T[...], extents: int[]) => T when is_numeric::<T>()
```

The sum of every element, with the operand's extents stated: `sum(t)`, and `extents` is `shape(t)`.

The extents are read by `rulesets.transpose`'s `sum_stated_t` and by nothing else -- the value is
the sum, and the accumulation, the element type and the one rounding are `sum`'s own. A list that
disagrees with the tensor's shape is a fault, because a spread over extents nobody verified is a
gradient of the wrong shape.

- Pure.
- Failure: fault `RuntimeError` when `extents` disagrees with the tensor's shape.
- Example: `sum_stated([1.0, 2.0, 3.0] as float[], [3])` gives `6.0`

#### `take_stated`

```camel
take_stated: (t: T[...], indices: int[], extents: int[]) => T[...] when is_numeric::<T>()
```

The rows `take` reads, with the indices it reads **and** the operand's extents stated:
`take_stated(t, [i0, ..., i(n-1)], [d0, ..., d(rank-1)])` is `take(t, [i0, ..., i(n-1)])`.

The value is that take. `rulesets.transpose`'s `take_stated_t` reads `extents` to build the
array the scatter-add writes into, which is the operand's shape and therefore has to come from a
known operand. The two lists are told apart by their parameters, not by a count written into the
first one: `indices` is what `take` reads and `extents` is the shape to spread the rows back into.
outside the first dimension

- Pure.
- Failure: fault `RuntimeError` when `extents` disagrees with the tensor's shape, or an index is.
- Example: `take_stated([[1.0, 2.0], [3.0, 4.0]] as float[2, 2], [1], [2, 2])` gives `[[3.0, 4.0]]`

#### `mul_stated`

```camel
mul_stated: (x: T[...], w: T[...], ax: int[], aw: int[]) => T[...] when is_numeric::<T>()
```

The product of two tensors, with **both** operands' extents stated: `x * w`, where `ax` is
`shape(x)` and `aw` is `shape(w)`.

The value is the product and spends nothing on the extents: the broadcast, the element type and the
one rounding are `multiply`'s own. `rulesets.transpose`'s `mul_stated_t` reads the two lists
instead of the operand whose cotangent it is answering -- that operand is a tangent on the reverse
side, and a tangent's type states no extents (design principles 5.4) -- and the forward half that
computes them is `rulesets.jvp`'s `jvp_mul_tensor`, where both operands are values.

Two lists and not one, unlike the stated reductions above: a product broadcasts, so the operands'
shapes differ (`[2, 2, 3] * [3]`), and each cotangent comes back to its **own** operand's shape. An
operand that is one number states no extents, and its list is empty.

- Pure.
- Failure: fault `RuntimeError` when either list disagrees with its operand's shape.
- Example: `mul_stated([1.0, 2.0] as float[2], [3.0, 4.0] as float[2], [2], [2])` gives `[3.0, 8.0]`

#### `matmul_stated`

```camel
matmul_stated: (a: T[...], b: T[...], sa: int[], sb: int[]) => T[...]
```

The matrix product, with **both** operands' extents stated: `a @ b`, where `sa` is `shape(a)` and
`sb` is `shape(b)`.

The value is the product (`matmul`'s own kernel, so the accumulation and the inner-extent check are
the definition's own) and the two lists are read by `rulesets.transpose`'s `matmul_stated_t`, which
reduces each cotangent to its own operand's shape without reading that operand. Two lists because
the answer's shape is neither operand's: a `[3, 4] @ [4, 2]` product reduces the left cotangent to
`[3, 4]` and the right one to `[4, 2]`.

- Pure.
- Failure: fault `RuntimeError` when either list disagrees with its operand's shape.
- Example: `matmul_stated([[1.0, 2.0]] as float[1, 2], [[3.0], [4.0]] as float[2, 1], [1, 2], [2, 1])` gives `[[11.0]]`

#### `sum_axis_stated`

```camel
sum_axis_stated: (t: T[...], axis: int, keepdims: bool, extents: int[]) => T[...] when is_numeric::<T>()
```

The sum of each lane along one axis, with the axis, `keepdims` and the operand's extents
stated: `sum_axis_stated(t, axis, keepdims, extents)` is `sum<axis, keepdims>(t)`.

The value needs the axis and the flag -- `k::reduceAxis` is the kernel the axis form runs, so the
accumulation in `f64`, the element type and the one rounding are the definition's own -- and
`extents` is checked against the tensor's shape. `rulesets.transpose`'s `sum_axis_stated_t` reads
the three stated values and nothing of the operand: the adjoint of a lane sum spreads each lane's
cotangent back over the lane, which is a shape of the primal. A negative axis counts from the last
one, as it does in the axis form: the reduction normalizes it on entry and this spelling hands it
over unchanged.
outside the rank

- Pure.
- Failure: fault `RuntimeError` when `extents` disagrees with the tensor's shape, or the axis is.
- Example: `sum_axis_stated([[1.0, 2.0], [3.0, 4.0]] as float[2, 2], 0, false, [2, 2])` gives `[4.0, 6.0]`

#### `mean_stated`

```camel
mean_stated: (t: T[...], extents: int[]) => T when is_numeric::<T>()
```

The mean of every element, with the operand's extents stated: `mean(t)`, and `extents` is
`shape(t)`.

The value is the mean -- the sum and the division both in `f64`, rounded into the element type
once, which is `mean`'s own definition -- and the extents are what its adjoint needs: the reverse
law (`rulesets.transpose`'s `mean_stated_t`) divides the cotangent by the number of elements and
spreads it over those extents, and neither number is in the cotangent's type.
element

- Pure.
- Failure: fault `RuntimeError` when `extents` disagrees with the tensor's shape, or the tensor has no.
- Example: `mean_stated([1.0, 2.0, 3.0, 4.0] as float[], [4])` gives `2.5`

#### `max_axis_stated`

```camel
max_axis_stated: (t: T[...], mask: bool[...], axis: int, keepdims: bool, extents: int[]) => T[...] when is_numeric::<T>()
```

The largest element of each lane along one axis, with the tie selection, the axis, `keepdims` and
the operand's extents stated: `max_axis_stated(t, mask, axis, keepdims, extents)` is
`max<axis, keepdims>(t)`, and `mask` holds `true` at every position that holds its lane's
largest element.

The mask is what an extremum's adjoint needs and what the extents cannot rebuild: an extremum
gives the whole cotangent to **every** position that holds it (a tie is not shared out), and which
positions those are is a fact of the values. The mask and the three stated values are read by
`rulesets.transpose`'s `max_axis_stated_t` and by nothing else -- the value is the axis form's own
reduction -- so a mask of another shape is answered where it is used: the reverse law's `where`
broadcasts it against the stated extents.
outside the rank

- Pure.
- Failure: fault `RuntimeError` when `extents` disagrees with the tensor's shape, or the axis is.
- Example: `max_axis_stated([[1.0, 2.0], [3.0, 4.0]] as float[2, 2], [[false, true], [false, true]] as bool[2, 2], 1, false, [2, 2])` gives `[2.0, 4.0]`

#### `min_axis_stated`

```camel
min_axis_stated: (t: T[...], mask: bool[...], axis: int, keepdims: bool, extents: int[]) => T[...] when is_numeric::<T>()
```

The smallest element of each lane along one axis, with the tie selection, the axis, `keepdims` and
the operand's extents stated: `min<axis, keepdims>(t)`, laid out exactly as
`max_axis_stated` is.
outside the rank

- Pure.
- Failure: fault `RuntimeError` when `extents` disagrees with the tensor's shape, or the axis is.
- Example: `min_axis_stated([[1.0, 2.0], [3.0, 4.0]] as float[2, 2], [[true, false], [true, false]] as bool[2, 2], 1, false, [2, 2])` gives `[1.0, 3.0]`

### Module state

#### `num_threads`

```camel
num_threads: () => int
```

The size of the module's worker pool.

- With effects: reads the size of the worker pool.
- Example: `num_threads()`

#### `set_num_threads`

```camel
set_num_threads: (n: int) => void
set_num_threads: (n: i32) => void
```

Sets the size of the module's worker pool; a value below 1 is read as 1.

- With effects: changes the size of the worker pool.
- Example: `set_num_threads(4)`

#### `gemm_backend`

```camel
gemm_backend: () => string
```

The name of the matrix-multiplication kernel the module dispatches to.

- Pure.
- Example: `gemm_backend()`

#### `gemm_threads`

```camel
gemm_threads: () => int
```

The thread count the matrix multiplication had for its most recent call: the tensor-pool
chunks that split a whole-work library product, the worker pool's width for a canonical call,
and 1 inside a region or for a library call inside a batch chunk. The count is what one
product got: `num_threads()` is what the run was given, and this is what one product spent.

- With effects: reads the size of the worker pool.
- Example: `gemm_threads()`

#### `gemm_library_threads`

```camel
gemm_library_threads: () => int
```

The library's own thread count for the most recent call: 1 when a library call ran (each chunk
of a split product is one such call), 0 when the canonical kernel did. `gemm_threads()` is the
pool that split the product; this is what each of its library calls got.

- With effects: reads the thread count of the last library call.
- Example: `gemm_library_threads()`

#### `gemm_library`

```camel
gemm_library: () => string
```

The name of the matrix-multiplication kernel the library path calls: `cblas` in a build with a
CBLAS, otherwise the canonical kernel's name, which is what the path forwards to.

- Pure.
- Example: `gemm_library()`

### The reductions along an axis, computed rather than declared

The six reductions along an axis -- `sum`, `mean`, `min`, `max`, `argmax` and `argmin` with the
axis and the flag in angle brackets (one name per reduction, design principles 7.3) -- are the
operators `tensor:sum_axis` and its five siblings (that URI naming is what the ONNX lowering table
and the semantics declarations are keyed on), and they are not declared here: their **result
type** is not a signature a declaration can state. The extents of
an axis reduction are the operand's extents with one axis removed -- or kept as an extent of one
-- so they follow from the operand's type *and* from the value of `axis` and of `keepdims`, and
a declaration's result is a type, not a function of two values. Written here as a declaration
the name answered `T[...]`, which is a result that states no extent at all; the operator's own
inference computes the extents (`modules/tensor/ops/reduction_ops.cpp#reduceAxisInfer`, through
`support.cpp#reduceShape`), and a program that writes `mean<0, false>(x)` now reads a
`float[3]` where it used to read a `float[...]`.

The one thing that stays unknown is what the axis and the flag really are: `mean_axis_stated`
takes them as parameters of its own, so a call that leaves them to the run states no rank, and its
result is `T[...]` and honestly so. That is why it is still declared above and these six are not.

`stdlib/signatures/tensor.cml` records the six computed signatures; `stdlib/array.cml` imports
the names instead of declaring a second spelling of each.

#### `sum_to`

```camel
sum_to: (t: T[...], at: int[]) => T[...] when is_float::<T>()
```

`t` reduced over its **leading axes** to the extents `at`: a leading-axis reduction, and nothing
else.

`at` is the target itself -- the extents the answer has, written where the call is. The length is
therefore the caller's: it is not read off another value's shape (the older spelling passed a
zero array whose shape stood in for the target) and not off a type, and no registry, context or
expected result type supplies it -- the extents are the runtime shape the caller states, which is
the layer the author's ruling of 2026-11-05 puts them on.

**The contract is 甲: `at` is a suffix of `t`'s shape.** The axes `t` has in front of `at`'s are
summed away, and an axis `at` states 1 against a longer one is summed too -- the adjoint of a
broadcast that handed one element along that lane (design principles 5.4). Two equal shapes are
the identity, which is the shape a gradient usually arrives in. Anything else is a fault named at
the call: a target *longer* than `t`, or one asking for an extent `t` does not have at that
position, is refused with both shapes in the sentence
(`modules/tensor/kernels/gradient.cpp#requireSuffixTarget`). The operator never spreads;
`broadcast_like` is the operator that does.

The element type is `t`'s, and the answer is written at it (design principles 9.9: a gradient is
the width of the value it belongs to). The extents are not in the result type, because they are a
runtime value -- `T[...]` is the result, and a caller that needs a rank states it with `as`.

The transposition laws reduce a product's cotangents with it (`rulesets.transpose`:
`sum_to(ct * other, ax)` is one operand's cotangent at the extents that operand states), and the
engine accumulates a tensor operand with it (`modules/tensor/ops/vjp.cpp#accumulateOperand`).

- Pure.
- Example: `sum_to([[1.0, 2.0], [3.0, 4.0]] as float[2, 2], [2])` gives `[3.0, 7.0]`
- Example: `sum_to([[1.0, 2.0], [3.0, 4.0]] as float[2, 2], [])` gives `10.0`
- Example: `sum_to([1.0, 2.0, 3.0] as float[], [3])` gives `[1.0, 2.0, 3.0]`

#### `broadcast_like`

```camel
broadcast_like: (t: T, like: S) => S
```

`t` spread out to the shape `like` states: the **other** direction of the same adjoint, and the
operator that owns it.

The two directions used to share `sum_to`, and they are not one move: a reduction reads a target
that is a suffix of its operand's shape and adds over the axes in front of it, while a spread
writes an element into every lane a broadcast would have handed it out along -- the operation
`broadcast_like` is named for. `sum_to` now takes the extents themselves (ruling 甲) and refuses
a target *longer* than its operand by name; a law that needs a rank-one value in the lanes of a
rank-two one says `broadcast_like(value, like)` and reads the shape off a value the cut carries.

`like` is a tensor (or a value whose stated shape is the target); `t` is a tensor or a single
number, and a number is written at `like`'s element type -- a rank-zero operand *is* an element
(design principles 5.4), so it spreads as that value. Two tensors that are not one element type
are refused: a broadcast is a copy of the elements, not a conversion between them
(design principles 5.1).

It is what the transpose laws of the broadcast products write where an operand has to grow
(`stdlib/rulesets/transpose.cml`), and it is the adjoint-turned-around of `sum_to`.

- Pure.
- Example: `broadcast_like(2.0, [[0.0, 0.0], [0.0, 0.0]] as float[2, 2])` gives `[[2.0, 2.0], [2.0, 2.0]]`
- Example: `broadcast_like([1.0, 2.0] as float[2], [[0.0, 0.0], [0.0, 0.0]] as float[2, 2])` gives `[[1.0, 2.0], [1.0, 2.0]]`

<a id="types"></a>

## `types`: the properties of types

The properties of types that an applicability condition asks about. These are ordinary Camel
functions: each one matches the type it is given with `match type` and returns a constant, so
`func f::<T>(x: T) when is_float::<T>()` is applicable exactly where `T` is a float. There is
no run-time inspection of a type: a predicate is settled when the call is compiled.

One family, one spelling: `is_<property>::<T>()` asks one type, and `is_same::<T, U>()` asks two.
The identity predicates (`is_integer`, `is_float`, `is_complex`, `is_string`, `is_bool`,
`is_function`, and the shapes `is_array`, `is_nullable`, `is_fallible`, `is_map`, `is_set`) carry the
`match type` cases; the others ask them (`is_numeric`, `is_ordered`,
`is_plain`), so a type is named in one place and a new integer width is added to `is_integer`
alone. A single type (`i32`, `f32`, `int`) is asked with `is_same`.

Types are also computed from types, in the one language (design principles 5.6, 21): a type
function is declared with `type`, takes its arguments in the angle brackets of a type position
and has a type expression for its body, a `match type` among them. `ElementOf<T>` (the element
of an array or a set), `PayloadOf<T>` (the `U` of `U?` or `U!`), `KeyOf<T>` and `ValueOf<T>` (the
key and value types of a map) take a type apart where `match type` cannot, and `RowsOf<T>` (the
array whose first-dimension elements are `T`) puts one back together the same way; they are
declared below without a body: the compiler provides them. They are evaluated when the instance that
binds `T` is made, so `is_integer::<ElementOf<T>>()` asks the element type of `T`.

`match type` compares a type's identity as well as its shape (design principles 5.5): the
cases below name the types the language spells (`int`, `i32`, `float`, `f32`, `bf16`, `f16`,
`c64`, `c128`, `string`, `bool`), and `case func` is the shape of every function type.
`bf16` and `f16` are floating-point types (design principles 7.3), so they belong to
`is_float` and inherit `is_numeric` and `is_ordered` from it.

#### `is_same`

```camel
is_same: () => bool
```

True when `T` and `U` are the same type. Identity, not shape: two named types with the same
fields are different, `i32` and `int` are different.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_same::<int, int>()` gives `true`
- Example: `is_same::<i32, int>()` gives `false`

#### `is_integer`

```camel
is_integer: () => bool
```

True when `T` is an integer type (`int` is 64-bit, `i32` is 32-bit).

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_integer::<int>()` gives `true`
- Example: `is_integer::<float>()` gives `false`

#### `is_float`

```camel
is_float: () => bool
```

True when `T` is a floating-point type (`float` is 64-bit, `f32` is 32-bit, `bf16` and
`f16` are the two reduced-precision floating types).

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_float::<float>()` gives `true`
- Example: `is_float::<bf16>()` gives `true`
- Example: `is_float::<int>()` gives `false`

#### `is_complex`

```camel
is_complex: () => bool
```

True when `T` is a complex number (`c64` is 64-bit, `c128` is 128-bit).

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_complex::<c64>()` gives `true`
- Example: `is_complex::<float>()` gives `false`

#### `is_numeric`

```camel
is_numeric: () => bool
```

True when `T` is a number: an integer, a float or a complex number.

The three families are asked, not listed again: a type spelled in one of them is numeric
without appearing here, so adding an integer width changes `is_integer` alone. The complex
branch is `is_complex`, which is why `c64` is numeric.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_numeric::<int>()` gives `true`
- Example: `is_numeric::<string>()` gives `false`
- Example: `is_numeric::<c64>()` gives `true`

#### `is_real`

```camel
is_real: () => bool
```

True when `T` is a real number: an integer or a float. A complex number is not.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_real::<float>()` gives `true`
- Example: `is_real::<c64>()` gives `false`

#### `is_ordered`

```camel
is_ordered: () => bool
```

True when `T` has a total order: the number types, `string` and `bool`.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_ordered::<string>()` gives `true`
- Example: `is_ordered::<bool>()` gives `true`

#### `is_function`

```camel
is_function: () => bool
```

True when `T` is a function type, whatever its parameters and result.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_function::<(x: int) => int>()` gives `true`

#### `is_array`

```camel
is_array: () => bool
```

True when `T` is an array type, of any rank.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_array::<int[]>()` gives `true`
- Example: `is_array::<f32[...]>()` gives `true`
- Example: `is_array::<int>()` gives `false`

#### `is_nullable`

```camel
is_nullable: () => bool
```

True when `T` is `U?` for some `U`.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_nullable::<int?>()` gives `true`
- Example: `is_nullable::<int!>()` gives `false`
- Example: `is_nullable::<int>()` gives `false`

#### `is_fallible`

```camel
is_fallible: () => bool
```

True when `T` is `U!` for some `U`.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_fallible::<int!>()` gives `true`
- Example: `is_fallible::<int?>()` gives `false`
- Example: `is_fallible::<int>()` gives `false`

#### `is_map`

```camel
is_map: () => bool
```

True when `T` is a map, `Map<K, V>`.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_map::<Map<string, int>>()` gives `true`
- Example: `is_map::<Set<int>>()` gives `false`

#### `is_set`

```camel
is_set: () => bool
```

True when `T` is a set, `Set<E>`.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_set::<Set<int>>()` gives `true`
- Example: `is_set::<Map<string, int>>()` gives `false`

#### `is_string`

```camel
is_string: () => bool
```

True when `T` is `string`.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_string::<string>()` gives `true`
- Example: `is_string::<int>()` gives `false`

#### `is_bool`

```camel
is_bool: () => bool
```

True when `T` is `bool`.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_bool::<bool>()` gives `true`
- Example: `is_bool::<int>()` gives `false`

#### `is_plain`

```camel
is_plain: () => bool
```

True when `T` is pure data: a number, `bool`, or a struct or tuple whose fields are all pure
data.

Pure data is what a value can be stored as itself: the bytes contain the value and every read of
them is the value again, because no field of the type is a reference. It is the element type an
array is allocated and copied for, the element type `to_bytes` writes and `from_bytes` reads, and
the element type the interchange with other frameworks names. A `string` holds a reference to
its characters, an array holds a reference to its block, and a function, an enum and a tagged
form hold something a copy of the bytes would not carry, so none of them is pure data.

The families are asked here as everywhere else: a number is pure data because `is_numeric` says
so, and a struct or tuple is asked field by field.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `is_plain::<float>()` gives `true`
- Example: `is_plain::<bool>()` gives `true`
- Example: `is_plain::<{ x: int, y: f32 }>()` gives `true`
- Example: `is_plain::<string>()` gives `false`
- Example: `is_plain::<int[]>()` gives `false`

<a id="array"></a>

## `array`: arrays, sorting and higher-order functions

Functions on arrays, written in Camel on the built-in operators (`map`, `filter`, `reduce`,
`zip`, `len`, the subscript) and on two native atoms: `argsort`, and the flat view of an array
of any rank. Every function returns a new value; none changes its argument. The functions of
one dimension take `T[]`; the reductions take `T[...]` and reduce every element, in row-major
order.

- The array is the ordinary argument; what configures the function (a count, a value, a
  function) is in angle brackets, so calls chain: `xs->filter<keep>->sort_by<key>->take<3>`.
- A result that may not exist (`find`, `find_index`, `index_of`) is `T?`; nothing here returns
  an error value. The `sum` of no element is 0; `mean`, `min`, `max`, `argmax` and `argmin`
  of no element are faults, as design principles 7.7 say.
- A function passed to these runs element by element in order and stops as soon as the answer
  is known (`find`, `any`, `all`), or is mapped, with no order among the calls (`sort_by`,
  `flat_map`, `zip_with`). None of them asks for a `pure` function.
- Elements are not converted: the numbers added, compared or searched for are of the
  element type of the array.

### Rearranging

#### `reverse`

```camel
reverse: (xs: T[]) => T[]
```

The elements in reverse order.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `[1, 2, 3]->reverse` gives `[3, 2, 1]`

#### `take`

```camel
take: <n: int> (xs: T[]) => T[]
```

The first n elements; all of them when there are fewer, none when n is not positive.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `[1, 2, 3, 4]->take<2>` gives `[1, 2]`

#### `drop`

```camel
drop: <n: int> (xs: T[]) => T[]
```

The elements after the first n; none when there are fewer, all when n is not positive.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `[1, 2, 3, 4]->drop<1>` gives `[2, 3, 4]`

#### `chunks`

```camel
chunks: <n: int> (xs: T[]) => T[][]
```

Consecutive pieces of n elements; the last is shorter when n does not divide the length.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when n is not positive.
- Example: `[1, 2, 3, 4, 5]->chunks<2>` gives `[[1, 2], [3, 4], [5]]`

#### `enumerate`

```camel
enumerate: (xs: T[]) => (int, T)[]
```

Each element with its index.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `['a', 'b']->enumerate` gives `[(0, 'a'), (1, 'b')]`

#### `flatten`

```camel
flatten: (xss: T[][]) => T[]
```

The elements of the inner arrays, in order.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `[[1, 2], [3]]->flatten` gives `[1, 2, 3]`

#### `flatten`

```camel
flatten: (xs: T[...]) => T[] when !is_array::<T>()
```

The elements of an array of any rank, in row-major order, as an array of one dimension.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `([[1, 2], [3, 4]] as int[2, 2])->flatten` gives `[1, 2, 3, 4]`

#### `unique`

```camel
unique: (xs: T[]) => T[]
```

The first occurrence of every value, in order. Values are compared as `==` compares them, so
a NaN equals nothing and every NaN is kept. The time is quadratic in the number of distinct
values; to drop repeats of numbers or strings in a long array, `sort` it and compare
neighbours.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `[3, 1, 3, 2, 1]->unique` gives `[3, 1, 2]`

### Searching

#### `find_index`

```camel
find_index: <pred: (x: T) => bool> (xs: T[]) => int?
```

The index of the first element for which pred is true, or null. pred is not called on the
elements after it.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `[3, 9, 2]->find_index<(x) => x > 4> ?? -1` gives `1`

#### `find`

```camel
find: <pred: (x: T) => bool> (xs: T[]) => T?
```

The first element for which pred is true, or null.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `[3, 9, 2]->find<(x) => x > 4> ?? -1` gives `9`

#### `index_of`

```camel
index_of: <x: T> (xs: T[]) => int?
```

The index of the first element equal to x, or null. Equality is `==`, so a NaN is never found.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `[3, 9, 2]->index_of<9> ?? -1` gives `1`

#### `any`

```camel
any: <pred: (x: T) => bool> (xs: T[]) => bool
```

True when pred is true for at least one element; false for an empty array.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `[3, 9, 2]->any<(x) => x > 4>` gives `true`

#### `all`

```camel
all: <pred: (x: T) => bool> (xs: T[]) => bool
```

True when pred is true for every element; true for an empty array.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `[3, 9, 2]->all<(x) => x > 4>` gives `false`

#### `count`

```camel
count: <pred: (x: T) => bool> (xs: T[]) => int
```

The number of elements for which pred is true.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `[3, 9, 2]->count<(x) => x > 2>` gives `2`

### Reducing

#### `sum`

```camel
sum: (xs: T[...]) => T when is_numeric::<T>()
```

The sum of the elements.

A float element type is added in f64 and rounded once into the element type: the rule of
every float reduction, not a rounding after each addition. An integer or complex element
type is added in itself and wraps around on overflow, as `+` does.
The sum of no element is 0, the identity of addition.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `[1, 2, 3]->sum` gives `6`
- Example: `[0.5, 0.25]->sum` gives `0.75`

#### `mean`

```camel
mean: (xs: T[...]) => T when is_float::<T>()
```

The arithmetic mean: the sum and the division both in f64, rounded once into the element
type, `T(sum(float(x)) / float(numel(x)))`.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when the array has no element.
- Example: `[1.0, 2.0, 3.0, 4.0]->mean` gives `2.5`

#### `min`

```camel
min: (xs: T[...]) => T when is_ordered::<T>()
```

The smallest element. Numbers are compared as `math::min` compares them: a NaN anywhere gives
NaN, and -0 is below +0. Strings compare by their bytes, and false is below true.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when the array has no element.
- Example: `[3, 9, 2]->min` gives `2`

#### `max`

```camel
max: (xs: T[...]) => T when is_ordered::<T>()
```

The largest element. Numbers are compared as `math::max` compares them: a NaN anywhere gives
NaN, and +0 is above -0.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when the array has no element.
- Example: `[3, 9, 2]->max` gives `9`

#### `argmax`

```camel
argmax: (xs: T[...]) => int when is_ordered::<T>()
```

The row-major position of the largest element: the first NaN if there is one, +0 above -0,
the earlier position on a tie.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when the array has no element.
- Example: `[3, 9, 2, 9]->argmax` gives `1`

#### `argmin`

```camel
argmin: (xs: T[...]) => int when is_ordered::<T>()
```

The row-major position of the smallest element: the first NaN if there is one, -0 below +0,
the earlier position on a tie.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when the array has no element.
- Example: `[3, 1, 2, 1]->argmin` gives `1`

### Reducing along an axis

#### `sum`

```camel
sum: <axis: int, keepdims: bool = false> (xs: T[...]) => T[...] when is_integer::<T>() || is_float::<T>()
```

The sum along an axis (0 along an axis of extent 0), with the rule of the whole sum: a float element type is added in f64
from +0 in ascending order and rounded once, an integer one wraps around.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when the axis is outside the rank.
- Example: `([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])->sum<0>` gives `[4.0, 6.0]`

#### `mean`

```camel
mean: <axis: int, keepdims: bool = false> (xs: T[...]) => T[...] when is_float::<T>()
```

The mean along an axis: the sum and the division both in f64, rounded once into the element
type.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when the axis is outside the rank or its extent is 0.
- Example: `([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])->mean<1>` gives `[1.5, 3.5]`

#### `min`

```camel
min: <axis: int, keepdims: bool = false> (xs: T[...]) => T[...] when is_integer::<T>() || is_float::<T>()
```

The smallest element along an axis, compared as `min` of the whole array compares.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when the axis is outside the rank or its extent is 0.
- Example: `([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])->min<1>` gives `[1.0, 3.0]`

#### `max`

```camel
max: <axis: int, keepdims: bool = false> (xs: T[...]) => T[...] when is_integer::<T>() || is_float::<T>()
```

The largest element along an axis, compared as `max` of the whole array compares.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when the axis is outside the rank or its extent is 0.
- Example: `([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])->max<0>` gives `[3.0, 4.0]`

#### `argmax`

```camel
argmax: <axis: int, keepdims: bool = false> (xs: T[...]) => int[...] when is_integer::<T>() || is_float::<T>()
```

The position along an axis of the first largest element, ordered as `argmax` of the whole
array orders.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when the axis is outside the rank or its extent is 0.
- Example: `([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])->argmax<1>` gives `[1, 1]`

#### `argmin`

```camel
argmin: <axis: int, keepdims: bool = false> (xs: T[...]) => int[...] when is_integer::<T>() || is_float::<T>()
```

The position along an axis of the first smallest element, ordered as `argmin` of the whole
array orders.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when the axis is outside the rank or its extent is 0.
- Example: `([[1.0, 2.0], [3.0, 4.0]] as float[2, 2])->argmin<0>` gives `[0, 0]`

### Shape

#### `shape`

```camel
shape: (xs: T[...]) => int[]
```

The extents of an array, in order.

- A native operator of this module: an opaque node, pure.
- Example: `shape([[1.0, 2.0], [3.0, 4.0]] as f32[2, 2])` gives `[2, 2]`

#### `numel`

```camel
numel: (xs: T[...]) => int
```

The number of elements of an array: the product of its extents.

- A native operator of this module: an opaque node, pure.
- Example: `numel([[1.0, 2.0], [3.0, 4.0]] as f32[2, 2])` gives `4`

#### `dim`

```camel
dim: <axis: int> (xs: T[...]) => int
```

The extent of one axis; a negative axis counts from the last one.

- A native operator of this module: an opaque node, pure.
- Failure: fault `InvalidArgument` when the axis is outside the rank.
- Example: `([[1.0, 2.0, 3.0]] as f32[1, 3])->dim<1>` gives `3`

### Binary form

#### `to_bytes`

```camel
to_bytes: (xs: T[...]) => Bytes when is_plain::<T>()
```

The elements of an array as little-endian bytes, in row-major order: the payload `from_bytes`
reads back. The elements are the array's own bytes, so every pure-data element type has them:
one byte an element for a `bool` array, four for an `f32` one and eight for an `f64` or `c64`
one.

- A native operator of this module: an opaque node, pure.
- Example: `([1.0, 2.0] as f32[])->to_bytes` gives `[0, 0, 128, 63, 0, 0, 0, 64]`

### Sorting

#### `argsort`

```camel
argsort: (keys: i32[]) => int[]
argsort: (keys: int[]) => int[]
argsort: (keys: f32[]) => int[]
argsort: (keys: float[]) => int[]
argsort: (keys: bf16[]) => int[]
argsort: (keys: f16[]) => int[]
argsort: (keys: bool[]) => int[]
argsort: (keys: string[]) => int[]
```

The positions of the keys in ascending order of key; equal keys keep their order. Numbers
are ordered as `min` and `max` order them, with -0 below +0 and every NaN after the numbers;
strings are ordered by their bytes and false is below true. This is the atom the sorts are
written on.

- A native operator of this module: an opaque node, pure.
- Example: `[30, 10, 20]->argsort` gives `[1, 2, 0]`

#### `sort`

```camel
sort: (xs: T[]) => T[] when is_ordered::<T>()
```

The elements in ascending order, in the order `argsort` gives.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `[3, 1, 2]->sort` gives `[1, 2, 3]`
- Example: `['pear', 'fig']->sort` gives `['fig', 'pear']`

#### `merge_sorted`

```camel
merge_sorted: (xs: T[], ys: T[]) => T[] when is_ordered::<T>()
```

The elements of both arrays in ascending order, in the order `sort` gives: the meaning is
`sort(concat(xs, ys))`. Execution takes a kernel that merges the two in one pass when each is
already in order, which is what the function is for: the cost is O(n + m), against the
O((n + m) log (n + m)) of the sort it stands for. An input that is not in order is sorted with
the other, so the result is the same array for every input; equal elements keep their order,
those of `xs` first.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `merge_sorted([1, 4, 6], [2, 3, 7])` gives `[1, 2, 3, 4, 6, 7]`
- Example: `merge_sorted([2.0, 1.0], [0.5])` gives `[0.5, 1.0, 2.0]`

#### `sort_by`

```camel
sort_by: <key: (x: T) => K> (xs: T[]) => T[] when is_ordered::<K>()
```

The elements in ascending order of key(x); elements with equal keys keep their order, so
sorting by one key and then by another works. key is called once for every element. Keys
are ordered as `argsort` orders them; for a descending order of numbers use the negated key.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `['pear', 'fig', 'apple']->sort_by<(w) => len(w)>` gives `['fig', 'pear', 'apple']`

### Transforming

#### `flat_map`

```camel
flat_map: <f: (x: T) => U[]> (xs: T[]) => U[]
```

f applied to every element, the resulting arrays joined in order.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `[1, 2]->flat_map<(x) => [x, x * 10]>` gives `[1, 10, 2, 20]`

#### `zip_with`

```camel
zip_with: <f: (a: T, b: U) => V> (xs: T[], ys: U[]) => V[]
```

f(xs[i], ys[i]) for every i.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` (of zip) when the two arrays differ in length.
- Example: `zip_with<(a, b) => a + b>([1, 2], [10, 20])` gives `[11, 22]`

### Batching

#### `vmap`

```camel
vmap: (f: (row: T) => U) => (xs: RowsOf<T>) => U[]
```

The batching of a function as a value: `vmap(f)` is the function that applies f to every
element along the leading axis of an array and gives the results in order, which is JAX's
`vmap(fun)` for the one argument and the axis 0. One name serves every rank, the leading axis
being the element `x[i]` takes (design principles 5.4): rank 1 batches the elements
(`vmap((x: float) => x * x)` over a `float[]` gives their squares), and rank 2 and above batch
the rows, so `vmap((r: f32[3]) => sum(r * r))` applied to an `f32[4, 3]` gives the four row
results as an `f32[]`. `RowsOf<T>` states that shape: the type the function takes, with one
dimension of unknown length in front of it.

The rows are taken one at a time, which is what the result is: turning the rowwise application
into one kernel is an optimization of the same semantics, left to the batching rules (it does
not change this interface). A function of two parameters would batch two parameters at once and
is refused rather than batched over its first one, a second array to batch together with the
first is refused, and an axis is not a parameter -- there is nothing to name (`in_axes` and
multiple batched parameters wait for the sixth answer). Being a value, it is stored once and
applied to several arrays (`let batched = vmap(square)`), which is what makes it a transform
rather than a call form of `map`.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap((x: float) => x * x)([0.0, 1.0, 2.0])` gives `[0.0, 1.0, 4.0]`
- Example: `vmap((r: f32[3]) => r[2] * r[2])([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]] as f32[2, 3])` gives `[9.0, 36.0]`

<a id="stream"></a>

## `stream`: producing and consuming streams

Streams, written in Camel. A stream is a value: `T..` is a step function together with its
state, an ordinary function value of the signature `() => (T, T..)?`. One call is one pull; a
pull answers the next element together with the rest of the stream, or `null` when the stream
is over. The consumer is `for x in s`, which the compiler expands on the graph into the `while`
it already has (language reference 7.3.2), so nothing here needs a node kind of its own and
nothing runs until something pulls.

- A stream is consumed once: on every execution path a stream value has one consumer, and a
  second use is a compile-time error (design principles 5.4). A function that takes a stream
  takes it as an argument; a lambda cannot capture one. So every transformation below keeps the
  upstream stream as the state of `unfold` (an argument of its step), never in a closure.
- The transformations are pure and lazy: an element is computed when something pulls it, and
  not before. Sharing is written, with `tee`.
- A generator (`yield`) produces the same kind of value; `unfold` is the producer for a state
  and a step that need no generator.
- What depends on the order of arrival or on time (merging streams, windows by time) is not
  here: those declare their non-determinism and belong to the libraries that own a clock.

### Producing

#### `unfold`

```camel
unfold: (state: S, step: (state: S) => (T, S)?) => T..
```

The stream of what `step` answers from `state` on: one element with the state after it, or
`null` when there is nothing more. The states are threaded, not repeated.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `loop acc = 0 for x in unfold(3, (n: int) => if n > 0 then (n, n - 1) else null) do acc + x` gives `6`

#### `empty`

```camel
empty: () => T..
```

The stream with no element.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `loop n = 0 for x in empty::<int>() do n + 1` gives `0`

#### `from_array`

```camel
from_array: (xs: T[]) => T..
```

The elements of xs, in order.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `loop acc = 0 for x in from_array([1, 2, 3]) do acc + x` gives `6`

#### `iterate`

```camel
iterate: <f: (x: T) => T> (x: T) => T..
```

x, f(x), f(f(x)), ... without end.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `1->iterate<(x: int) => x * 2>->take<4>->collect` gives `[1, 2, 4, 8]`

### Transforming

#### `map`

```camel
map: <f: (x: T) => U> (s: T..) => U..
```

f of every element.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `from_array([1, 2, 3])->map<(x: int) => x * 2>->collect` gives `[2, 4, 6]`

#### `filter`

```camel
filter: <pred: (x: T) => bool> (s: T..) => T..
```

The elements for which pred is true, in order.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `from_array([1, 2, 3, 4])->filter<(x: int) => x % 2 == 0>->collect` gives `[2, 4]`

#### `take`

```camel
take: <n: int> (s: T..) => T..
```

The first n elements; fewer when the stream ends first, none when n is not positive. The
element after the n-th is never pulled.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `1->iterate<(x: int) => x + 1>->take<3>->collect` gives `[1, 2, 3]`

#### `scan`

```camel
scan: <f: (acc: A, x: T) => A, init: A> (s: T..) => A..
```

The running results of folding the elements with f from init: one per element, the first
being f(init, first element).

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `from_array([1, 2, 3])->scan<(acc: int, x: int) => acc + x, 0>->collect` gives `[1, 3, 6]`

#### `chunks`

```camel
chunks: <k: int> (s: T..) => T[]..
```

The elements in arrays of k, in order; the last array is shorter when the stream does not end
on a multiple of k.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `from_array([1, 2, 3])->chunks<2>->collect` gives `[[1, 2], [3]]`

#### `zip`

```camel
zip: (a: T.., b: U..) => (T, U)..
```

The elements of two streams in pairs, until the shorter ends.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `zip(from_array([1, 2]), from_array(['a', 'b', 'c']))->collect` gives `[(1, 'a'), (2, 'b')]`

### Consuming

#### `collect`

```camel
collect: (s: T..) => T[]
```

All the elements, as an array. The stream must end: a stream without end never returns.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `from_array([1, 2, 3])->collect` gives `[1, 2, 3]`

### Sharing

#### `tee`

```camel
tee: <n: int = 8> (s: T..) => (T.., T..)
```

Two streams over the elements of `s` (design principles 5.4), each read once, both seeing the
same elements in the same order. `s` is read once: the first side to need an element the buffer
does not hold pulls it, and the other side finds it there. `n` is a hint -- the width the
buffer is expected to have -- and is clamped to the implementation's cap.
The result is a tuple, and taking it apart is what consumes the two streams; the streams
themselves are values like any other, so a `tee` of one of them is another `tee`.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `let (left, right) = unfold(3, (n: int) => if n > 0 then (n, n - 1) else null)->tee<2>`

<a id="math"></a>

## `math`: numbers and bits

Scalar mathematics. One definition covers every type that has the operation: a function of
floats is written once for `f32`, `float`, `bf16` and `f16` and answers the type it was given;
a function of several numbers takes numbers of one type. Numeric types are not converted
implicitly: `sqrt(4)` is refused, write `sqrt(4.0)` or `sqrt(float(n))`.

- Outside its domain a float function gives the IEEE result (NaN or an infinity), not a fault.
  Special values (zeros, infinities, NaN) are exact.
- The transcendental functions are computed in f64 and rounded once into the type asked for.
  They promise an error of at most 2 ulp (of the type's own precision, for `float`), not the
  same bits on every device (design principles 7.1). `sqrt`, the rounding functions, `min` and
  `max` are exact: the result is the correctly rounded or the selected operand.
- `min` and `max` are the IEEE 754-2019 `minimum` and `maximum`: a NaN on either side gives
  NaN, and -0 is below +0 (design principles 7.7).
- Over an array the elementwise functions are the `tensor` module's for now (`exp(xs)`); the
  scalar ones here apply to a number, and `xs->map<exp>` is the same function on every element.
  The conversions `f32(xs)`, `float(xs)` are elementwise (core). `sum`, `mean`, `min`, `max` of a
  whole array belong to `array`.
- Only what a program cannot compute from the language is native: the f64 kernels of the
  elementary functions, the sign-exact selection of `min` and `max`, the parts of a complex
  number, and the bit operations of an integer width.

### Constants

#### `pi`

```camel
pi: float
```

The ratio of a circle's circumference to its diameter.

- A value: written without parentheses, a constant where it is used.
- Example: `pi` gives `3.14159...`

#### `e`

```camel
e: float
```

The base of the natural logarithm.

- A value: written without parentheses, a constant where it is used.
- Example: `log(e)` gives `1`

#### `inf`

```camel
inf: float
```

Positive infinity; negative infinity is -inf.

- A value: written without parentheses, a constant where it is used.
- Example: `is_inf(-inf)` gives `true`

#### `nan`

```camel
nan: float
```

A NaN. It equals nothing, itself included: test with is_nan.

- A value: written without parentheses, a constant where it is used.
- Example: `is_nan(nan)` gives `true`

### Elementary functions

#### `sqrt`

```camel
sqrt: (x: T) => T when is_float::<T>()
```

The square root; NaN for a negative x, and the square root of -0 is -0.

- Example: `sqrt(9.0)` gives `3`

#### `exp`

```camel
exp: (x: T) => T when is_float::<T>()
```

e raised to the power x.

- Example: `exp(0.0)` gives `1`

#### `exp`

```camel
exp: (z: T) => T when is_complex::<T>()
```

e raised to the power of a complex number.

- Example: `exp(0.0+0.0i)` gives `1+0i`

#### `expm1`

```camel
expm1: (x: T) => T when is_float::<T>()
```

exp(x) - 1, accurate for x near 0.

- Example: `expm1(0.0)` gives `0`

#### `log`

```camel
log: (x: T) => T when is_float::<T>()
```

The natural logarithm. log(0.0) is -inf, the logarithm of a negative number is NaN.

- Example: `log(1.0)` gives `0`

#### `log2`

```camel
log2: (x: T) => T when is_float::<T>()
```

The logarithm to base 2.

- Example: `log2(8.0)` gives `3`

#### `log10`

```camel
log10: (x: T) => T when is_float::<T>()
```

The logarithm to base 10.

- Example: `log10(1000.0)` gives `3`

#### `log1p`

```camel
log1p: (x: T) => T when is_float::<T>()
```

log(1 + x), accurate for x near 0.

- Example: `log1p(0.0)` gives `0`

#### `pow`

```camel
pow: (x: T, y: T) => T when is_float::<T>()
```

x raised to the power y. pow(0.0, 0.0) is 1; a negative x with a fractional y gives NaN.

- Example: `pow(2.0, 10.0)` gives `1024`

#### `hypot`

```camel
hypot: (x: T, y: T) => T when is_float::<T>()
```

The square root of x*x + y*y, without overflow in the squares.

- Example: `hypot(3.0, 4.0)` gives `5`

#### `sin`

```camel
sin: (x: T) => T when is_float::<T>()
```

The sine of x, x in radians.

- Example: `sin(0.0)` gives `0`

#### `cos`

```camel
cos: (x: T) => T when is_float::<T>()
```

The cosine of x, x in radians.

- Example: `cos(0.0)` gives `1`

#### `tan`

```camel
tan: (x: T) => T when is_float::<T>()
```

The tangent of x, x in radians.

- Example: `tan(0.0)` gives `0`

#### `asin`

```camel
asin: (x: T) => T when is_float::<T>()
```

The arc sine, in radians; NaN outside -1 to 1.

- Example: `asin(1.0)` gives `1.5708`

#### `acos`

```camel
acos: (x: T) => T when is_float::<T>()
```

The arc cosine, in radians; NaN outside -1 to 1.

- Example: `acos(1.0)` gives `0`

#### `atan`

```camel
atan: (x: T) => T when is_float::<T>()
```

The arc tangent, in radians.

- Example: `atan(1.0)` gives `0.785398`

#### `atan2`

```camel
atan2: (y: T, x: T) => T when is_float::<T>()
```

The angle of the point (x, y) in radians, between -pi and pi. Note the order: y first.

- Example: `atan2(1.0, 1.0)` gives `0.785398`

#### `sinh`

```camel
sinh: (x: T) => T when is_float::<T>()
```

The hyperbolic sine.

- Example: `sinh(0.0)` gives `0`

#### `cosh`

```camel
cosh: (x: T) => T when is_float::<T>()
```

The hyperbolic cosine.

- Example: `cosh(0.0)` gives `1`

#### `tanh`

```camel
tanh: (x: T) => T when is_float::<T>()
```

The hyperbolic tangent.

- Example: `tanh(0.0)` gives `0`

#### `erf`

```camel
erf: (x: T) => T when is_float::<T>()
```

The error function, 2 / sqrt(pi) times the integral of e^-t^2 from 0 to x.

- Example: `erf(0.0)` gives `0`

#### `erfc`

```camel
erfc: (x: T) => T when is_float::<T>()
```

The complementary error function, 1 - erf(x), without the cancellation of the subtraction for
large x.

- Example: `erfc(0.0)` gives `1`

### Rounding

#### `floor`

```camel
floor: (x: T) => T when is_float::<T>()
```

The largest whole number not above x, as a float.

- Example: `floor(-2.5)` gives `-3`

#### `ceil`

```camel
ceil: (x: T) => T when is_float::<T>()
```

The smallest whole number not below x, as a float.

- Example: `ceil(2.1)` gives `3`

#### `round`

```camel
round: (x: T) => T when is_float::<T>()
```

The nearest whole number, halves away from zero, as a float.

- Example: `round(2.5)` gives `3`

#### `trunc`

```camel
trunc: (x: T) => T when is_float::<T>()
```

x without its fraction (rounded toward zero), as a float.

- Example: `trunc(-2.7)` gives `-2`

### Comparing

#### `min`

```camel
min: (a: T, b: T) => T when is_ordered::<T>()
```

The smaller of two values of one ordered type. For numbers this is the IEEE 754 minimum: a
NaN on either side gives NaN, and -0 is below +0. Strings compare by code point (a proper
prefix first), and false is below true.

- Example: `min(3, 5)` gives `3`
- Example: `min('b', 'a')` gives `'a'`

#### `max`

```camel
max: (a: T, b: T) => T when is_ordered::<T>()
```

The larger of two values of one ordered type. For numbers this is the IEEE 754 maximum: a
NaN on either side gives NaN, and -0 is below +0. Strings compare by code point (a proper
prefix first), and false is below true.

- Example: `max(3, 5)` gives `5`
- Example: `max('a', 'b')` gives `'b'`

#### `clamp`

```camel
clamp: (x: T, lo: T, hi: T) => T when is_real::<T>()
```

x held between lo and hi: lo when x is below, hi when above. A NaN x stays NaN.

- Failure: fault `InvalidArgument` when lo is above hi, or a bound is NaN.
- Example: `clamp(15, 0, 10)` gives `10`

#### `abs`

```camel
abs: (x: T) => T when is_real::<T>()
```

The absolute value of an integer or a float. The sign of a zero is cleared, a NaN stays a NaN,
and the smallest integer is its own absolute value (negation wraps, as it does in `-x`).

- Example: `abs(-3)` gives `3`

#### `abs`

```camel
abs: (z: T) => f32 when is_same::<T, c64>()
```

The modulus of a single-precision complex number.

- Example: `abs(c64(3.0)+4.0i)` gives `5`

#### `abs`

```camel
abs: (z: T) => float when is_same::<T, c128>()
```

The modulus of a double-precision complex number.

- Example: `abs(3.0+4.0i)` gives `5`

#### `sign`

```camel
sign: (x: T) => T when is_real::<T>()
```

-1, 0 or 1 by the sign of x, in the type of x. A zero and a NaN are returned as they are.

- Example: `sign(-2.5)` gives `-1`

#### `is_nan`

```camel
is_nan: (x: T) => bool when is_float::<T>()
```

Whether x is a NaN.

- Example: `is_nan(inf - inf)` gives `true`

#### `is_inf`

```camel
is_inf: (x: T) => bool when is_float::<T>()
```

Whether x is positive or negative infinity.

- Example: `is_inf(1.0)` gives `false`

#### `is_finite`

```camel
is_finite: (x: T) => bool when is_float::<T>()
```

Whether x is neither a NaN nor an infinity.

- Example: `is_finite(1.0)` gives `true`

### Complex numbers

The parts of a complex number are native: the result type is not the argument's.

#### `re`

```camel
re: (z: c64) => f32
re: (z: c128) => float
```

The real part of a complex number.

- Example: `re(3.0+4.0i)` gives `3.0`

#### `im`

```camel
im: (z: c64) => f32
im: (z: c128) => float
```

The imaginary part of a complex number.

- Example: `im(3.0+4.0i)` gives `4.0`

#### `conj`

```camel
conj: (z: T) => T when is_same::<T, c64>()
conj: (z: T) => T when is_same::<T, c128>()
```

The conjugate of a complex number: the imaginary part is negated, a zero's sign included.

- Example: `conj(3.0+4.0i)` gives `3-4i`

### Integers

#### `gcd`

```camel
gcd: (a: T, b: T) => T when is_integer::<T>()
```

The greatest common divisor, never negative; gcd(0, 0) is 0. The smallest integer, which has
no positive counterpart, is not accepted.

- Failure: fault `InvalidArgument` when an argument is the smallest integer of its type.
- Example: `gcd(12, 18)` gives `6`

#### `lcm`

```camel
lcm: (a: T, b: T) => T when is_integer::<T>()
```

The least common multiple, never negative; 0 when either argument is 0.

- Failure: fault `InvalidArgument` when an argument is the smallest integer, or the result does not fit the type.
- Example: `lcm(4, 6)` gives `12`

### Bits

Bit operations are functions, not operators (`&` and `|` are logical). Integers are two's
complement: `int` has 64 bits, `i32` has 32. One declaration per width, because the operator
that runs differs; the name and the signature are one generic.

#### `bit_and`

```camel
bit_and: (a: T, b: T) => T when is_same::<T, i32>()
bit_and: (a: T, b: T) => T when is_same::<T, int>()
```

The bits set in both a and b.

- Example: `bit_and(12, 10)` gives `8`

#### `bit_or`

```camel
bit_or: (a: T, b: T) => T when is_same::<T, i32>()
bit_or: (a: T, b: T) => T when is_same::<T, int>()
```

The bits set in a or in b.

- Example: `bit_or(12, 10)` gives `14`

#### `bit_xor`

```camel
bit_xor: (a: T, b: T) => T when is_same::<T, i32>()
bit_xor: (a: T, b: T) => T when is_same::<T, int>()
```

The bits set in exactly one of a and b.

- Example: `bit_xor(12, 10)` gives `6`

#### `shl`

```camel
shl: <count: int> (x: T) => T when is_same::<T, i32>()
shl: <count: int> (x: T) => T when is_same::<T, int>()
```

x shifted left by count bits: bits shifted out are lost and zeros come in, so the sign may
change.

- Failure: fault `InvalidArgument` when count is negative or not below the width of x (64 for int, 32 for i32).
- Example: `1->shl<4>` gives `16`

#### `shr`

```camel
shr: <count: int> (x: T) => T when is_same::<T, i32>()
shr: <count: int> (x: T) => T when is_same::<T, int>()
```

x shifted right by count bits, keeping the sign (an arithmetic shift): `-8->shr<1>` is -4.

- Failure: fault `InvalidArgument` when count is negative or not below the width of x.
- Example: `256->shr<4>` gives `16`

<a id="statistics"></a>

## `statistics`: variance, standard deviation, median and quantile

Descriptive statistics of an array of floats, written in Camel on `array` (whose `mean` is the
first of them).

Every function takes a float element type (`float`, `f32`, `bf16` or `f16`) and answers it.
The elements are widened to f64, the statistic is computed there, and the result is rounded
once into the element type: the rule of every float reduction. An array of integers is
converted first, `float(xs)`. A statistic that does not exist for the array
(the standard deviation of one value) is a fault, as every reduction over too few elements is
(design principles 7.7).

#### `variance`

```camel
variance: (xs: T[]) => T when is_float::<T>()
```

The sample variance (divisor n - 1).

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when the array has fewer than two elements.
- Example: `[1.0, 2.0, 3.0, 4.0]->variance` gives `1.66667`

#### `stdev`

```camel
stdev: (xs: T[]) => T when is_float::<T>()
```

The sample standard deviation (divisor n - 1).

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when the array has fewer than two elements.
- Example: `[2.0, 4.0, 4.0, 4.0, 5.0, 5.0, 7.0, 9.0]->stdev` gives `2.13809`

#### `median`

```camel
median: (xs: T[]) => T when is_float::<T>()
```

The middle value of the sorted elements, the mean of the two middle ones for an even count;
NaN when an element is NaN.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when the array has no element.
- Example: `[3.0, 1.0, 2.0]->median` gives `2`

#### `quantile`

```camel
quantile: <q: float> (xs: T[]) => T when is_float::<T>()
```

The q-quantile, q from 0 to 1, by linear interpolation between the two nearest ranks
(position q * (n - 1) of the sorted elements); NaN when an element is NaN.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Failure: fault `InvalidArgument` when q is not between 0 and 1, or the array has no element.
- Example: `[1.0, 2.0, 3.0, 4.0, 5.0]->quantile<0.25>` gives `2`

<a id="random"></a>

## `random`

Random numbers by key. A `Key` is a value; a function that draws takes a key and answers a
number, and the same key gives the same bits on every device and every scheduler. Nothing is
read or changed, so these functions are pure and an optimizer may share, move or batch them.
To get several independent streams from one key, derive keys: `split(k)` gives two,
`fold(k, i)` gives the i-th. A key is used for one draw, or to derive other keys, not both.

The generator is Philox4x32-10 (design principles 13.5). The integer functions are
identical on every device. The normal distribution uses `log`, `sqrt`, `cos` and so holds
to the error bound of `math`, not to the bit.

Calls chain on what flows: the key is the data of a draw (`k->uniform::<f32>`), and what shapes
the draw is configuration (`k->randint<1, 7>`, `xs->shuffle<k>`).

For a program that wants a random number without passing keys there is one global stream, the
resource `rng`: `seed(v)` starts it, `next_key()` takes the next key from it, and everything
else is the keyed function applied to that key: `next_key()->randint<1, 7>`. Without `seed`
the stream starts from seed 0, so a run is the same every time.

### Keys

#### `key`

```camel
key: (seed: int) => Key
```

The key of a seed.

- Example: `key(42)` gives `{ hi: 0, lo: 42 }`

#### `fold`

```camel
fold: (k: Key, i: int) => Key
```

The i-th key derived from k, i from 0. The same k and i always give the same key, and k is
not changed.

- Failure: fault `InvalidArgument` when i is negative.
- Example: `key(42)->fold(3)`

#### `split`

```camel
split: (k: Key) => (Key, Key)
```

Two independent keys derived from k: the same pair every time, and k is not changed.

- Example: `let (a, b) = split(key(42))`

### Draws

#### `uniform`

```camel
uniform: (k: Key) => T when is_float::<T>()
```

A number drawn uniformly from 0 (included) to 1 (excluded).

- Example: `key(42)->uniform::<f32>`

#### `uniform`

```camel
uniform: <shape: int[]> (k: Key) => T[...] when is_float::<T>()
```

An array of the given shape; element i (row-major) is the scalar `uniform` of `fold(k, i)`.

- Example: `key(42)->uniform::<f32><shape: [3, 4]>`

#### `normal`

```camel
normal: (k: Key) => T when is_float::<T>()
```

A number drawn from the normal distribution with mean 0 and deviation 1 (Box-Muller).

- Example: `key(42)->normal::<f32>`

#### `normal`

```camel
normal: <shape: int[]> (k: Key) => T[...] when is_float::<T>()
```

An array of the given shape; element i (row-major) is the scalar `normal` of `fold(k, i)`.

- Example: `key(42)->normal::<f32><shape: [3, 4]>`

#### `randint`

```camel
randint: <low: int, high: int> (k: Key) => int
```

An integer drawn uniformly from low (included) to high (excluded).

- Failure: fault `InvalidArgument` when high is not above low, or the range is wider than 2^62.
- Example: `key(42)->randint<1, 7>`

#### `permutation`

```camel
permutation: (k: Key, n: int) => int[]
```

A uniformly random permutation of 0 up to, not including, n: the positions ordered by one
uniform draw each (the key folded with the position), ties keeping position order. Empty when n is not positive.

- Example: `key(42)->permutation(4)`

#### `shuffle`

```camel
shuffle: <k: Key> (xs: T[]) => T[]
```

The elements of xs in a random order, as a new array; xs is not changed. The meaning is
`xs[permutation(k, len(xs))]`; numbers are shuffled by a kernel that makes the same
permutation in O(n log n) time (the cost of ordering n draws) and 16 bytes of working memory
for each element.

- Example: `[1, 2, 3]->shuffle<key(42)>`

#### `choice`

```camel
choice: <k: Key> (xs: T[]) => T
```

One element of xs, drawn uniformly.

- Failure: fault `InvalidArgument` when xs is empty.
- Example: `['a', 'b', 'c']->choice<key(42)>`

#### `sample`

```camel
sample: <k: Key, n: int> (xs: T[]) => T[]
```

n elements of xs drawn without replacement, as a new array.

- Failure: fault `IndexOutOfRange` when n is negative or above the number of elements.
- Example: `[1, 2, 3, 4]->sample<key(42), 2>`

### The global stream

#### `seed`

```camel
seed: (value: int) => void uses rng
```

Starts the global stream: the same seed gives the same sequence of keys.

- Example: `seed(42)`

#### `next_key`

```camel
next_key: () => Key uses rng
```

The next key of the global stream, and the stream moves on: two calls give two keys.

- Example: `next_key()`

#### `rand`

```camel
rand: () => float
```

A number drawn uniformly from 0 (included) to 1 (excluded) from the global stream.

- Example: `rand()`

#### `randn`

```camel
randn: () => float
```

A number drawn from the normal distribution with mean 0 and deviation 1, from the global stream.

- Example: `randn()`

<a id="time"></a>

## `time`

A moment is a `float`: seconds since 1970-01-01 00:00 UTC, with a fraction. Reading the clock is
an effect (`now`); turning a moment into text and back is pure and always in UTC, so the same
moment gives the same text on every machine.

#### `now`

```camel
now: () => float
```

The current time, in seconds since the epoch.

- With effects: reads the clock.
- Example: `now()` gives `1791806400.25`

#### `strftime`

```camel
strftime: <format: string> (timestamp: float) => string
```

The moment written with a strftime format, in UTC.

- Pure.
- Failure: fault `TimeFormatFailed` when the moment is outside the range of calendar time, or the format gives no text.
- Example: `0.0->strftime<'%Y-%m-%d'>` gives `'1970-01-01'`

#### `strptime`

```camel
strptime: <format: string> (text: string) => float!
```

The moment a text gives when read with a strptime format; the fields are taken as UTC.

- Pure.
- Failure: error value `ParseError` when the text does not have the format, or gives a moment outside the range of calendar time.
- Example: `'1970-01-02'->strptime<'%Y-%m-%d'> !! 0.0` gives `86400.0`

<a id="fs"></a>

## `fs`: files

The file system. A file is read and written either as text (`string`, always UTF-8) or as
`Bytes`; the two sets of functions are separate and meet only in `bytes::encode` and
`bytes::decode`, so a text file is never half-read as binary and the bytes written for a text are
the same on every platform. What the file system can refuse -- a missing file, a permission, a
full disk -- is an error value (`T!`) whose kind says which; a wrong argument, such as a negative
size, is a fault.

Every function here uses the resource `fs`: a call runs only when its result is needed or it is
written in a `sync` block, and calls on the file system keep their written order. A path is the
data a reader works on (`'notes.txt'->read_text`) and the destination a writer is configured with
(`text->write_text<'out/log.txt'>`), so `write_text<'out/log.txt'>` is itself the function that
writes that file. Relative paths start at the working directory (`env::get_cwd`).

### Reading

#### `read_text`

```camel
read_text: (path: string) => string!
```

The whole content of a file, as text.

- Failure: error value `NotFound` when nothing exists at the path; error value `PermissionDenied` when the file system refuses the read; error value `IOError` when the path is a directory or the read fails for another reason; error value `EncodingError` when the content is not valid UTF-8.
- Example: `'notes.txt'->read_text !! ''` gives `the text of the file, or '' when it cannot be read`

#### `read_bytes`

```camel
read_bytes: (path: string) => Bytes!
```

The whole content of a file, every byte preserved.

- With effects: reads a file.
- Failure: error value `NotFound` when nothing exists at the path; error value `PermissionDenied` when the file system refuses the read; error value `IOError` when the path is a directory or the read fails for another reason.
- Example (a fragment, not compiled): `'pixels.bin'->read_bytes !! encode('')` gives `the bytes of the file`
- Why it is not compiled: the example builds its default `Bytes` with `encode` from the `bytes` module, which this page does not import

#### `read_chunk`

```camel
read_chunk: <offset: int, size: int> (path: string) => Bytes!
```

Up to size bytes of a file from byte offset on; fewer at the end of the file, none at or past
it. Reading a large file piece by piece is `read_chunk` with a growing offset.

- With effects: reads a file.
- Failure: fault `InvalidArgument` when offset or size is negative; error value `NotFound`, `PermissionDenied` or `IOError` as for `read_bytes`.
- Example (a fragment, not compiled): `'notes.txt'->read_chunk<0, 16> !! encode('')` gives `the first 16 bytes`
- Why it is not compiled: the example builds its default `Bytes` with `encode` from the `bytes` module, which this page does not import

### Writing

#### `write_text`

```camel
write_text: <path: string, atomic: bool = false> (content: string) => void!
```

Replaces the content of the file at path with a text, creating the file and its parent
directories when they are not there. With atomic the content is first written to a temporary
file in the same directory and then renamed over the destination, so a reader sees the old
content or the new, never half of it.

- Failure: error value `PermissionDenied` when the file system refuses the write; error value `IOError` when the path is a directory or the write fails for another reason (no space left included).
- Example: `'done'->write_text<'out/log.txt'>`

#### `write_bytes`

```camel
write_bytes: <path: string, atomic: bool = false> (content: Bytes) => void!
```

Replaces the content of the file at path with bytes; creating, atomic and errors as for
`write_text`.

- With effects: writes a file.
- Failure: error value `PermissionDenied` when the file system refuses the write; error value `IOError` when the path is a directory or the write fails for another reason (no space left included).
- Example (a fragment, not compiled): `encode('abc')->write_bytes<'payload.bin', atomic: true>`
- Why it is not compiled: the example builds its `Bytes` with `encode` from the `bytes` module, which this page does not import

#### `append_text`

```camel
append_text: <path: string> (content: string) => void!
```

Adds a text to the end of the file at path, creating the file and its parent directories when
they are not there.

- Failure: error value `PermissionDenied` when the file system refuses the write; error value `IOError` when the path is a directory or the write fails for another reason.
- Example: `'one more line\n'->append_text<'out/log.txt'>`

#### `append_bytes`

```camel
append_bytes: <path: string> (content: Bytes) => void!
```

Adds bytes to the end of the file at path; creating and errors as for `append_text`.

- With effects: writes a file.
- Failure: error value `PermissionDenied` when the file system refuses the write; error value `IOError` when the path is a directory or the write fails for another reason.
- Example (a fragment, not compiled): `encode('abc')->append_bytes<'payload.bin'>`
- Why it is not compiled: the example builds its `Bytes` with `encode` from the `bytes` module, which this page does not import

### Questions about a path

#### `exists`

```camel
exists: (path: string) => bool
```

Whether anything exists at the path. A path that cannot be looked at (a directory that may not
be searched) is reported as not existing.

- With effects: reads the file system.
- Example: `'notes.txt'->exists` gives `true or false`

#### `is_file`

```camel
is_file: (path: string) => bool
```

Whether the path names a regular file.

- With effects: reads the file system.
- Example: `'notes.txt'->is_file` gives `true or false`

#### `is_dir`

```camel
is_dir: (path: string) => bool
```

Whether the path names a directory.

- With effects: reads the file system.
- Example: `'out'->is_dir` gives `true or false`

#### `file_size`

```camel
file_size: (path: string) => int!
```

The size of a file in bytes.

- With effects: reads the file system.
- Failure: error value `NotFound` when nothing exists at the path; error value `PermissionDenied` when the file system refuses the question; error value `IOError` otherwise.
- Example: `'notes.txt'->file_size !! 0` gives `1024`

#### `list_dir`

```camel
list_dir: (path: string) => string[]!
```

The names of what a directory holds, without the path in front of them, in the byte order of
the names (so the order is the same on every platform). `.` and `..` are not listed.

- With effects: reads the file system.
- Failure: error value `NotFound` when nothing exists at the path; error value `PermissionDenied` when the file system refuses the listing; error value `IOError` when the path is not a directory.
- Example: `'out'->list_dir !! []` gives `['log.txt', 'today']`

### Creating and removing

#### `mkdir`

```camel
mkdir: (path: string) => void!
```

Creates one directory. The parent directory must exist, and the directory must not.

- With effects: changes the file system.
- Failure: error value `AlreadyExists` when something exists at the path; error value `NotFound` when the parent directory does not exist; error value `PermissionDenied` when the file system refuses; error value `IOError` otherwise.
- Example: `'out'->mkdir`

#### `mkdirs`

```camel
mkdirs: (path: string) => void!
```

Creates a directory and every missing parent. A directory that is already there is not an
error, so the call can be repeated.

- With effects: changes the file system.
- Failure: error value `AlreadyExists` when a file, not a directory, exists at the path; error value `PermissionDenied` when the file system refuses; error value `IOError` otherwise.
- Example: `'out/logs/today'->mkdirs`

#### `remove`

```camel
remove: (path: string) => void!
```

Removes a file or a symbolic link; a directory, even an empty one, is an error (use
`remove_dir`). Removing a path that is not there is an error, not a silent success.

- With effects: removes a file.
- Failure: error value `NotFound` when nothing exists at the path; error value `PermissionDenied` when the file system refuses the removal; error value `IOError` when the path is a directory or the removal fails for another reason.
- Example: `'notes.txt'->remove`

#### `remove_dir`

```camel
remove_dir: (path: string) => void!
```

Removes one empty directory. A directory that is not empty is an error, not a recursive
delete; a file or a symbolic link is an error too.

- With effects: removes a directory.
- Failure: error value `NotFound` when nothing exists at the path; error value `PermissionDenied` when the file system refuses the removal; error value `IOError` when the path is a file, a symbolic link, or a directory that is not empty.
- Example: `'out/old'->remove_dir`

<a id="io"></a>

## `io`: terminal input

The terminal as a keyboard: what has been typed and not yet read, the keys themselves, and raw
mode. Reading is a use of the resource `stdin`, so reads and the changes of mode keep their
written order. `input` reads a whole line after writing its prompt; writing to the terminal is
the prelude's (`print`, `println`, `eprintln`).

#### `set_terminal_raw_mode`

```camel
set_terminal_raw_mode: (enabled: bool) => void!
```

Switches the terminal to raw mode (keys arrive one by one, unechoed) or back. Turning raw mode
off always succeeds. Raw mode is left again when the program ends.

- With effects: changes the terminal.
- Failure: error value `NotATerminal` when raw mode is asked for and standard input is not a terminal (a pipe, a file); error value `IOError` when the terminal refuses.
- Example: `set_terminal_raw_mode(true)`

#### `input`

```camel
input: (prompt: string) => string
```

Writes prompt to standard output and reads one line from standard input, without its line end.

- With effects: writes standard output, reads standard input.
- Example: `input('name: ')`

#### `has_input`

```camel
has_input: () => bool
```

Whether a key press is waiting to be read.

- With effects: reads the terminal.
- Example: `has_input()` gives `true or false`

#### `get_chars`

```camel
get_chars: (max: int) => string
```

Up to max characters of the input that is waiting, as text; the empty text when none is. A
character is read whole, so max counts code points, not bytes.

- With effects: reads the terminal.
- Failure: fault `InvalidArgument` when max is negative.
- Example: `get_chars(3)` gives `at most three characters`

#### `get_char`

```camel
get_char: () => string?
```

The next character of the input that is waiting; null when none is.

- Example: `get_char() ?? ''` gives `'w'`

#### `clear_input_buffer`

```camel
clear_input_buffer: () => void
```

Discards the input that is waiting.

- With effects: reads the terminal.
- Example: `clear_input_buffer()`

<a id="process"></a>

## `process`: the process and the machine

The process and the machine it runs on: waiting, ending, who runs it and how many threads it can
have. Durations are seconds as a `float`, like `time::now`. The terminal is `io`'s, the
environment `env`'s.

#### `sleep`

```camel
sleep: (seconds: float) => void
```

Suspends the program for the given number of seconds. The wait is on the clock, so a call is
never folded away and the work of other ready nodes goes on meanwhile.

- With effects: waits.
- Failure: fault `InvalidArgument` when seconds is negative or not a number.
- Example: `sleep(0.1)`

#### `exit`

```camel
exit: (code: int) => never uses process
```

Ends the program with the given exit code, after the buffered output is written and the
external resources are released. Nothing that is written after the call runs. It gives no
value at all: its type is the bottom type `never` (design principles 3.9).

- Example: `exit(2)`

#### `user_name`

```camel
user_name: () => string!
```

The name of the user the process runs as.

- With effects: reads the environment.
- Failure: error value `NotFound` when the system has no name for the user.
- Example: `user_name() !! 'unknown'` gives `'alice'`

#### `cpu_count`

```camel
cpu_count: () => int
```

The number of hardware threads, at least 1.

- With effects: reads the machine.
- Example: `cpu_count()` gives `8`

<a id="env"></a>

## `env`: environment

What the environment tells the process: its variables and its working directory. Both read the
resource `env`, so a call is never folded or merged with another, and what a variable holds is
whatever it holds when the call runs.

#### `get_env`

```camel
get_env: (name: string) => string?
```

The value of an environment variable; null when it is not set. A variable that is set to the
empty text gives the empty text, not null.

- With effects: reads the environment.
- Example: `'HOME'->get_env ?? ''` gives `'/home/alice'`

#### `get_cwd`

```camel
get_cwd: () => string!
```

The current working directory, the directory relative paths start at.

- With effects: reads the environment.
- Failure: error value `NotFound` when the working directory has been removed; error value `PermissionDenied` when it cannot be read.
- Example: `get_cwd() !! ''` gives `'/home/alice/project'`

<a id="json"></a>

## `json`

A Json is a JSON value whose shape is known only when the program runs: `decode` reads a text,
or gives an error value when the text is not JSON, and the accessors look into it, each giving
a value of a definite type. To read a part whose shape is known, `decode_as::<T>` decodes
straight to the type T, and `encode` writes the JSON text of a value; both are applicable to the
types that have a JSON form (`has_json_form`) and to no other. Everything here is pure.

The data an accessor works on is its ordinary argument; the key or the index is its
with-argument, so calls chain: `decode(text)->get<key: 'port'>->as_int`. An accessor has one
declaration for each tagged form of its argument -- `Json`, `Json?`, `Json!` and `Json!?` --
written from the most specific to the widest, which give the result `R?`, `R?`, `R!?` and
`R!?`: an absent part is the null, and the error of a text that failed to decode is passed on
unchanged, so one `!!` or `??` at the end of a chain settles it.

#### `decode`

```camel
decode: (text: string) => Json!
```

The value a JSON text describes, as a `Json`: a value of a definite type whose content is
known only when the program runs. Look into it with `get`, `as_int`, `as_array` and the other
accessors below.

- Pure.
- Failure: error value `JsonParseError` when the text is not JSON (the message gives the position in the text and its beginning); error value `JsonTooDeep` when the document nests deeper than the limit (10000 levels; the message gives the line and column of the bracket that goes too deep).
- Example: `(decode('{"port": 80}')->get<key: 'port'>->as_int ?? 0) !! -1` gives `80`

#### `kind`

```camel
kind: (j: Json) => string
```

The kind of a Json: 'null', 'bool', 'int', 'float', 'string', 'array' or 'object'.

- Pure.
- Example: `decode('[1]') -> kind !! ''` gives `'array'`

#### `is_null`

```camel
is_null: (j: Json) => bool
```

Whether a Json is the JSON null.

- Example: `decode('null') -> is_null !! false` gives `true`

#### `get`

```camel
get: <key: string> (j: Json) => Json?
get: <key: string> (j: Json?) => Json?
get: <key: string> (j: Json!) => Json!?
get: <key: string> (j: Json!?) => Json!?
```

The member key of an object; null when j is not an object, has no such member, or is null
itself (so that calls chain: `j->get<key: 'a'>->get<key: 'b'>`).

- Pure.
- Example: `(decode('{"a": 1}')->get<key: 'a'>->as_int ?? 0) !! -1` gives `1`

#### `get`

```camel
get: <key: int> (j: Json) => Json?
get: <key: int> (j: Json?) => Json?
get: <key: int> (j: Json!) => Json!?
get: <key: int> (j: Json!?) => Json!?
```

The element key of an array; null when j is not an array, the index is out of range, or j is
null itself. The with-parameter is called `key` as in the member form above: which member of
the Json to take is written as a string or as an integer, and the argument's type says which.

- Pure.
- Example: `(decode('[5, 6]')->get<key: 1>->as_int ?? 0) !! -1` gives `6`

#### `as_bool`

```camel
as_bool: (j: Json) => bool?
as_bool: (j: Json?) => bool?
as_bool: (j: Json!) => bool!?
as_bool: (j: Json!?) => bool!?
```

The bool a Json holds; null for any other kind.

- Pure.
- Example: `(decode('true')->as_bool ?? false) !! false` gives `true`

#### `as_int`

```camel
as_int: (j: Json) => int?
as_int: (j: Json?) => int?
as_int: (j: Json!) => int!?
as_int: (j: Json!?) => int!?
```

The integer a Json holds; null for any other kind (a number with a fraction is not an int).

- Pure.
- Example: `(decode('42')->as_int ?? 0) !! 0` gives `42`

#### `as_float`

```camel
as_float: (j: Json) => float?
as_float: (j: Json?) => float?
as_float: (j: Json!) => float!?
as_float: (j: Json!?) => float!?
```

The number a Json holds, an integer included; null for any other kind.

- Pure.
- Example: `(decode('2')->as_float ?? 0.0) !! 0.0` gives `2.0`

#### `as_string`

```camel
as_string: (j: Json) => string?
as_string: (j: Json?) => string?
as_string: (j: Json!) => string!?
as_string: (j: Json!?) => string!?
```

The string a Json holds; null for any other kind.

- Pure.
- Example: `(decode('"hi"')->as_string ?? '') !! ''` gives `'hi'`

#### `as_array`

```camel
as_array: (j: Json) => Json[]?
as_array: (j: Json?) => Json[]?
as_array: (j: Json!) => Json[]!?
as_array: (j: Json!?) => Json[]!?
```

The elements of a JSON array; null for any other kind.

- Pure.
- Example: `len((decode('[1, "a"]')->as_array ?? []) !! [])` gives `2`

#### `as_object`

```camel
as_object: (j: Json) => Map<string, Json>?
as_object: (j: Json?) => Map<string, Json>?
as_object: (j: Json!) => Map<string, Json>!?
as_object: (j: Json!?) => Map<string, Json>!?
```

The members of a JSON object, by name; null for any other kind.

- Pure.
- Example: `len((decode('{"b": 1, "a": 2}')->as_object ?? ([] as Map<string, Json>)) !! ([] as Map<string, Json>))` gives `2`

#### `encode`

```camel
encode: <indent: int? = null> (value: T) => string when has_json_form::<T>()
```

The JSON text of a value, on one line, or indented by `indent` spaces per level when an indent
is given. The type of the value must have a JSON form: numbers, bool, string, null, a Json, and
arrays, tuples, structs, sets and maps with string keys of those; a function or a tensor is
refused when the call is compiled. A map is written with its keys in order, a struct with its
fields in the order of its type, so the same value gives the same text.

- Pure.
- Failure: fault `InvalidArgument` when indent is negative.
- Example: `[1, 2]->encode` gives `'[1,2]'`
- Example: `[1, 2]->encode<indent: 2>` gives `'[\n  1,\n  2\n]'`

#### `decode_as`

```camel
decode_as: (source: string) => T! when has_json_form::<T>()
decode_as: (source: Json) => T! when has_json_form::<T>()
```

The value a JSON text (or a Json decoded before) describes, decoded to the type T. A part of
T typed `Json` takes whatever is there. T is given where the call is written or taken from
where the result goes (`let cfg: Config! = text->decode_as`).

- Pure.
- Failure: error value `JsonTypeError` when the text is JSON of another type (the message gives the path of the mismatch); error value `JsonParseError` when the text is not JSON; error value `JsonTooDeep` when the document nests deeper than the limit.
- Example: `decode_as::<Map<string, int>>('{"a": 1}')` gives `{a: 1}`

<a id="hash"></a>

## `hash`

Digests. A digest is computed over bytes: the digest of a text is the digest of its UTF-8
bytes (`bytes::encode`), so a text and its encoding have the same digest on every platform.
Every function here is pure; the digest is written as lower-case hexadecimal text.

#### `sha256`

```camel
sha256: (data: Bytes) => string
```

The SHA-256 digest of a `Bytes` value, as 64 lower-case hexadecimal digits.

- Example (a fragment, not compiled): `sha256(encode('abc'))` gives `'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad'`
- Why it is not compiled: the example builds its `Bytes` value with `encode` from the `bytes` module, which this page does not import

#### `sha256`

```camel
sha256: (text: string) => string
```

The SHA-256 digest of the UTF-8 bytes of a text, as 64 lower-case hexadecimal digits.

- Example: `sha256('abc')` gives `'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad'`

<a id="re"></a>

## `re`: regular expressions

Regular expressions (ECMAScript syntax) over strings. A position is an index in code points,
as everywhere in a string, so `text[m.start, m.end>` is `m.text`.

- The text a function works on is its ordinary argument; the pattern is a with-argument (it
  decides which function this is), so calls chain: `line->find_all<'[0-9]+'>`.
- A pattern that is not a regular expression is a fault of the call that meets it, as a wrong
  index is. A pattern that comes from the outside world goes through `validate` first.
- The only native pieces are the search itself (`find`), a test for a match
  (`has_match_kernel`) and the check of a pattern; the rest is written here on top of them.

### Native primitives

#### `validate`

```camel
validate: (pattern: string) => string!
```

The pattern itself when it is a regular expression.

- Pure.
- Failure: error `RegexInvalid` when pattern is not a regular expression.
- Example: `validate('[0-9]+') !! ''` gives `'[0-9]+'`

### Matching

#### `find`

```camel
find: <pattern: string, start: int = 0> (text: string) => Match?
```

The first match of pattern in text that starts at or after start, or null. Native: the kernel
builds the `Match`, compiling each pattern once per run.

- Pure.
- Failure: fault `RegexInvalid` when pattern is not a regular expression.
- Example: `'room 42'->find<'[0-9]+', 6> != null` gives `true`

#### `has_match`

```camel
has_match: <pattern: string> (text: string) => bool
```

Whether pattern matches somewhere in text.

- Failure: fault `RegexInvalid` when pattern is not a regular expression.
- Example: `'room 42'->has_match<'[0-9]+'>` gives `true`

#### `find_all`

```camel
find_all: <pattern: string> (text: string) => Match[]
```

Every match of pattern in text, left to right, without overlap. After an empty match the
search goes on one code point further.

- Failure: fault `RegexInvalid` when pattern is not a regular expression.
- Example: `'a1b22'->find_all<'[0-9]+'>->map<(m: Match): string => m.text>` gives `['1', '22']`

### Rewriting

#### `replace_with`

```camel
replace_with: <pattern: string, by: (m: Match) => string> (text: string) => string
```

text with every match of pattern replaced by what by makes of it.

- Failure: fault `RegexInvalid` when pattern is not a regular expression.
- Example: `'a1b22'->replace_with<'[0-9]+', (m: Match): string => '<' + m.text + '>'>` gives `'a<1>b<22>'`

#### `replace`

```camel
replace: <pattern: string, new: string> (text: string) => string
```

text with every match of pattern replaced by the text new, which is taken literally.

- Failure: fault `RegexInvalid` when pattern is not a regular expression.
- Example: `'a1b22'->replace<'[0-9]+', '#'>` gives `'a#b#'`

#### `split`

```camel
split: <pattern: string> (text: string) => string[]
```

The pieces of text between the matches of pattern; one piece, the whole text, when there is
no match.

- Failure: fault `RegexInvalid` when pattern is not a regular expression.
- Example: `'a1b22c'->split<'[0-9]+'>` gives `['a', 'b', 'c']`

<a id="para"></a>

## `para`: unordered iteration

The unordered counterparts of the built-in `foreach` and `reduce`: the scheduler may run the
calls of the function in any order and at the same time. The effects the function has are those
of the callback, and the order they happen in is not fixed; that is the promise `unordered_` makes
and the reason to use these only for work whose calls do not depend on one another.

#### `unordered_foreach`

```camel
unordered_foreach: <f: (item: T) => void> (xs: T[]) => void
```

Calls f for every element, for its effects; the calls have no order among them.

- Example: `[1, 2]->unordered_foreach<(x: int) => println(x)>`

#### `unordered_reduce`

```camel
unordered_reduce: <f: (acc: T, item: T) => T, initial: T> (xs: T[]) => T
```

Combines the elements with f starting from initial; the order in which elements are combined is
not fixed, so f should be associative and commutative.

- Example: `[1, 2, 3]->unordered_reduce<(acc: int, x: int): int => acc + x, 0>` gives `6`

<a id="test_support"></a>

## `test_support`: the facilities of a test

Facilities for tests of the runtime, not for programs: things that make a property of the
scheduler visible.

#### `rendezvous`

```camel
rendezvous: (parties: int, timeout: float) => int uses rendezvous_point
```

Blocks until `parties` calls are waiting at the meeting point, or until `timeout` seconds have
passed, and gives how many calls met (after a timeout, how many were waiting). A tool for
showing that calls really run at the same time.

- Failure: fault `InvalidArgument` when parties is below 1 or timeout is negative.
- Example: `rendezvous(2, 1.0)` gives `2 when another call arrived in time`

#### `thread_count`

```camel
thread_count: () => int uses process
```

The number of threads this process has, the caller included: the count the operating system
reports for the process, not the number of processors. A test reads it to pin how many worker
threads a run creates.

- Example: `thread_count()` gives `1 at -t 1`

#### `with_probe`

```camel
with_probe: <base: int, step: int = 10, mode: int = 0> (x: T) => int
```

`base * 10000 + step * 100 + mode`: the three `with` values the call ended with, the defaults of
the parameters it left out among them. A native operator with a generic declaration, for the
tests that pin where the names and the defaults of a call come from.

- Example: `with_probe<1>(0)` gives `11000`

#### `with_probe`

```camel
with_probe: <base: int, step: int = 10, mode: int = 0> (xs: int[]) => int
```

The same for an array: the number plus the length of the array, so a test reads which of the two
declarations of the name a call reached.

- Example: `with_probe<1>([5, 6])` gives `11002`

#### `arity_probe`

```camel
arity_probe: <tag: int, extra: int[] = []> (f: F, example: E) => int when is_function::<F>()
```

An operator that wants a function and an example and writes `when is_function::<F>()`, the
condition a pass writes: the count of ordinary parameters (a pass takes one) tells the two
apart, so this is an operator, exported and callable with its `with` arguments by name, as
`onnx::export_model` is. It gives `tag * 10 + len(extra)`.

- Example: `arity_probe<7, [1]>((x: int): int => x, 0)` gives `71`

<a id="this"></a>

## `this`

The text of the Zen of Camel. The file `ZEN` of the repository is built into the module, so the
text has one source and a program that asks for it reads no file.

#### `zen`

```camel
zen: () => string
```

The Zen of Camel, the text of the file ZEN.

- Example: `println(zen())`

<a id="graph"></a>

## `graph`: the graph of a function as a value

The graph of a function, as a value. A function is a graph; this module reads it and, in a
transaction, edits it. The handles `Graph`, `Node`, `Op`, `TypeRef`, `Region` and `Tag` name
things inside the graphs of one function and compare with `==` and `!=`. Reads are pure.

A pass is a function from a function to a function of the same type, `(f: F) => F!`, so it
applies to one function, `loss->opt::fold`, or to the program's entry on the pipeline,
`camel prog.cml opt::fold std::nvm`. A pass written in Camel opens a transaction on `f`
(`open`), replaces and erases nodes, and commits (`commit`), which gives the changed function:
the same type, the captured values it had, and every graph nothing changed shared. What a pass
reads of the program around the function (declarations, tags, facts) is read through the
function; no snapshot of the program is in this interface.

A module that holds passes is compiled as a program of its own, whose entry is the pass: its
module-level values are computed before the pass runs. It may import modules written in C++ and
libraries written in Camel (for example `array`); the imports are declared and built with it.

### The graphs of a function

#### `graph_of`

```camel
graph_of: (f: F) => Graph when is_function::<F>()
```

The graph of a function value: its body.

- Example: `graph_of((x: int): int => x + 1)`

#### `graphs_of`

```camel
graphs_of: (f: F) => Graph[] when is_function::<F>()
```

The graph of a function value and every graph it calls, directly or not, in the order of
their ids; each graph once.

- Example: `len(graphs_of((x: int): int => x + 1))`

#### `name`

```camel
name: (g: Graph) => string
```

The name of the graph.

- Example: `name(graph_of((x: int): int => x + 1))`

#### `nodes`

```camel
nodes: (g: Graph) => Node[]
```

The nodes of the graph in NodeId order; the places of removed nodes are skipped.

- Example: `nodes(graph_of((x: int): int => x + 1))`

### Reading nodes

#### `inputs`

```camel
inputs: (n: Node) => Node[]
```

The nodes whose values `n` takes as ordinary inputs, in order.

- Example (a fragment, not compiled): `inputs(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `with_inputs`

```camel
with_inputs: (n: Node) => Node[]
```

The nodes whose values `n` takes as with inputs.

- Example (a fragment, not compiled): `with_inputs(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `sync_inputs`

```camel
sync_inputs: (n: Node) => Node[]
```

The nodes that must run before `n` when both run, because a sync block puts them in one chain
(the sync edges of design principles 3.1).

- Example (a fragment, not compiled): `sync_inputs(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `order_inputs`

```camel
order_inputs: (n: Node) => Node[]
```

The nodes that must run before `n` when both run, because they use the same resource (the
order edges of design principles 3.1); an order edge never makes a node run.

- Example (a fragment, not compiled): `order_inputs(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `users`

```camel
users: (n: Node) => Node[]
```

The nodes that read `n` as an input of any kind, once each, in NodeId order.

- Example (a fragment, not compiled): `users(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `value_users`

```camel
value_users: (n: Node) => Node[]
```

The nodes that read the value of `n` (ordinary or with input), once each.

- Example (a fragment, not compiled): `len(value_users(n)) == 0`
- Why it is not compiled: n is a node of the surrounding pass

#### `kind`

```camel
kind: (n: Node) => NodeKind
```

The kind of the node.

- Example (a fragment, not compiled): `kind(n) == NodeKind::Oper`
- Why it is not compiled: n is a node of the surrounding pass

#### `op`

```camel
op: (n: Node) => Op?
```

The operator of an operation node, null for any other node.

- Example (a fragment, not compiled): `op(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `op_name`

```camel
op_name: (o: Op) => string
```

The URI of the operator, such as `:op/add_l`.

- Example (a fragment, not compiled): `op_name(o)`
- Why it is not compiled: `o` is an operator taken from a node of the surrounding pass

#### `is_pure`

```camel
is_pure: (n: Node) => bool
```

Whether the node is an operation whose operator is declared pure.

- Example (a fragment, not compiled): `is_pure(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `may_be_recomputed`

```camel
may_be_recomputed: (n: Node) => bool
```

Whether a pass may compute the node's value itself and treat it as a value: its operator is
pure *and* foldable, so folding it, merging it with an identical call or dropping it when
nothing reads it cannot change the program. A pure operator that must run where the program
writes it (a rule's value, a `fact`) is not one, and neither is any node that is no operation.
This is the question the C++ fold, cse and dce ask (`OperatorTable::mayBeRecomputed`); whether
the call may also be *moved* or dropped asks `may_fault` as well.

- Example (a fragment, not compiled): `may_be_recomputed(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `may_fault`

```camel
may_fault: (n: Node) => bool
```

Whether running the node can raise a fault where the program writes it (a division by zero, an
index out of range, a conversion whose value does not fit). It is the operator table's own fact
(`OperatorTraits::mayFault`, the one the C++ sweep reads) and the conversion's (`castMayFault`);
a call, a loop or a gate nobody declared answers true, and an elementwise operator whose
operands' shapes the types state in full answers false. A node that may fault is not a value a
pass may drop, move or merge away, whatever the purity of its operator.

- Example (a fragment, not compiled): `may_fault(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `may_be_rearranged`

```camel
may_be_rearranged: (n: Node) => bool
```

Whether a pass may arrange the node anywhere: drop it, move it, merge it with an identical
call, or leave it with no order edge after an inline. The node must be pure *and* unable to
fault (design principles 3.4); a pure operator that must run where the program writes it, one
that may fault, one nobody declared, a call, a loop or a gate are not free. This is the one
predicate behind that question on both sides of the boundary: `graph::may_be_rearranged`
(camel/runtime/graph.h) is its implementation, the C++ passes read it under its older name
`nodeIsFreelySchedulable`, and a pass written in Camel reads this name. Ask it rather than
writing `is_pure(n) && may_be_recomputed(n) && !may_fault(n)`: the two writings drift apart.

- Example (a fragment, not compiled): `may_be_rearranged(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `is_anchor`

```camel
is_anchor: (n: Node) => bool
```

Whether the node anchors its graph (its exit, output or return, or the end of a branch arm); a
transaction does not replace or erase it.

- Example (a fragment, not compiled): `is_anchor(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `is_written_slot`

```camel
is_written_slot: (n: Node) => bool
```

Whether the value of the node may be written in place: it is passed to a `var` parameter or to
an operator that changes its operand, directly or through gates. A rewrite must not treat such
a node as one value.

- Example (a fragment, not compiled): `is_written_slot(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `is_constant`

```camel
is_constant: (n: Node) => bool
```

Whether the node is a constant of the graph.

- Example (a fragment, not compiled): `is_constant(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `constant_bytes`

```camel
constant_bytes: (n: Node) => int
```

The bytes the node's constant value occupies: the measure `std::opt` and `std::opt::fold` clamp with
`constant_budget`, so that a pass written in Camel can ask the same question the native pass asks. The
cost is the value's elements plus the shape that describes them, the walk follows members 8 deep, and a
node that is no constant costs 0.

- Example (a fragment, not compiled): `constant_bytes(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `type_of`

```camel
type_of: (n: Node) => TypeRef?
```

The type of the node's value, null when it has none.

- Example (a fragment, not compiled): `type_of(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `type_name`

```camel
type_name: (t: TypeRef) => string
```

The type as a program writes it.

- Example (a fragment, not compiled): `type_name(t)` gives `'int'`
- Why it is not compiled: t is the type of a node of the surrounding pass

#### `callee`

```camel
callee: (n: Node) => Graph?
```

The graph a call or function node names, null for any other node.

- Example (a fragment, not compiled): `callee(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `tags`

```camel
tags: (n: Node) => string
```

The attributes of the node as text (empty when there are none).

- Example (a fragment, not compiled): `tags(n)`
- Why it is not compiled: n is a node of the surrounding pass

### The tags a declaration writes

A tag whose argument is a function (`#jvp(rule)`, `#transpose(rule)`, `#vjp(rule)`) is a fact
about the declaration a pass needs the function of, not text about it: `declaration_tags` reads
it back by structure, and `rule_of` names the one a transform asks for.

#### `declaration_tags`

```camel
declaration_tags: (g: Graph) => Tag[]
```

The tags written on the declaration of the function of this graph whose argument is a
function, in the order of their names; empty for a graph that is no declaration (a lambda) and
for a declaration that writes none. The declaration's facts travel with the graph, so a pass
reads them without the module that declares the function.

- Example: `declaration_tags(graph_of((x: int): int => x + 1))`

#### `tag_name`

```camel
tag_name: (t: Tag) => string
```

The name of the tag as the program writes it (`jvp`, `vjp`); the qualified name when the tag is
not declared any more.

- Example (a fragment, not compiled): `tag_name(t)` gives `'jvp'`
- Why it is not compiled: t is a tag read from a declaration

#### `tag_graphs`

```camel
tag_graphs: (t: Tag) => Graph[]
```

The graphs the tag's arguments name, in the order written: `#jvp(mul_jvp)` names one.

- Example (a fragment, not compiled): `tag_graphs(t)`
- Why it is not compiled: t is a tag read from a declaration

#### `rule_of`

```camel
rule_of: (g: Graph, name: string) => Graph?
```

The rule the declaration of `g` writes for the transformation `name`: `jvp` is forward mode,
`transpose` the rule of a linear function, and `vjp` the rule that gives the pullback directly.
Null when the declaration writes none, when it writes that tag twice, and when what the tag
names is not a function. The name is the one the program writes, or its qualified spelling.

- Example: `rule_of(graph_of((x: int): int => x + 1), 'vjp')`

#### `origin`

```camel
origin: (n: Node) => int
```

The source origin id of the node, 0 when unknown.

- Example (a fragment, not compiled): `origin(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `constant`

```camel
constant: (n: Node) => T? when is_ordered::<T>()
```

The value of a constant node as the type T (a number, a bool or a string), null for a node
that is no constant of that type. T is written (`constant::<int>(n)`).

- Example (a fragment, not compiled): `constant::<int>(n)`
- Why it is not compiled: n is a node of the surrounding pass

### Regions

#### `region_of`

```camel
region_of: (n: Node) => Region
```

The innermost region the node is in. Every node is in one: region 0 is the body, also in a
graph whose region table is empty.

- Example (a fragment, not compiled): `region_of(n)`
- Why it is not compiled: n is a node of the surrounding pass

#### `region_kind`

```camel
region_kind: (r: Region) => RegionKind
```

The kind of the region: `Root` (the function body, region 0), `Arm`, `LoopCond`, `LoopBody`,
`Inline`, `Block` or `Dead`.

- Example (a fragment, not compiled): `region_kind(r) == RegionKind::Inline`
- Why it is not compiled: r is a region of the surrounding pass

#### `region_parent`

```camel
region_parent: (r: Region) => Region?
```

The region the region is in; null for the body (region 0).

- Example (a fragment, not compiled): `region_parent(r)`
- Why it is not compiled: r is a region of the surrounding pass

#### `show`

```camel
show: (n: Node) => string
```

The node on one line: its id, kind, operator and type.

- Example (a fragment, not compiled): `show(n)` gives `'%2 Oper :op/mul_l : int'`
- Why it is not compiled: n is a node of the surrounding pass

#### `id`

```camel
id: (h: Graph) => int
id: (h: Node) => int
id: (h: Op) => int
```

The number a graph, a node or an operator is known by inside its function: the GraphId, the
NodeId or the OperId. Stable for the function, so a pass can key a map by it.

- Example (a fragment, not compiled): `id(n)`
- Why it is not compiled: `n` is the graph the pass runs on

### Facts

#### `effects`

```camel
effects: (g: Graph) => Effects
```

What running the graph once does besides computing its value: `external`, `writes_variables`,
`may_fault`, `may_not_terminate`.

- Example: `effects(graph_of((x: int): int => x + 1)).external`

#### `shape_text`

```camel
shape_text: (n: Node) => string?
```

The shape of the node's value as text, null when its value is no array of known element type.

- Example (a fragment, not compiled): `shape_text(n)` gives `'f32 [2, 3]'`
- Why it is not compiled: n is a node of the surrounding pass

#### `permissions`

```camel
permissions: (n: Node) => int
```

The numeric permissions the program granted the node, as a bit set (0 for none).

- Example (a fragment, not compiled): `permissions(n)`
- Why it is not compiled: n is a node of the surrounding pass

### Transactions

#### `open`

```camel
open: (f: F) => Txn<F> when is_function::<F>()
```

Opens a transaction on a function: a private workspace in which its graphs are edited.
Nothing changes until `commit`.

- Example: `let t = open((x: int): int => x + 1)`

#### `replace`

```camel
replace: (t: Txn<F>, old: Node, new: Node) => void uses t
```

Puts the node `new` of the same graph in the place of `old`, which is removed; what `old`
ordered stays ordered.

- Failure: fault `InvalidArgument` when a node anchors its graph, when `new` is computed from `old`, or when the transaction is over.
- Example (a fragment, not compiled): `replace(t, n, inputs(n)[0])`
- Why it is not compiled: t is an open transaction and n a node of its graph

#### `erase`

```camel
erase: (t: Txn<F>, n: Node) => void uses t
```

Removes a node whose value nobody reads.

- Failure: fault `InvalidArgument` when the value is read, when the node anchors its graph, or when the transaction is over.
- Example (a fragment, not compiled): `erase(t, n)`
- Why it is not compiled: t is an open transaction and n a node of its graph

#### `eval`

```camel
eval: (t: Txn<F>, n: Node) => Node? uses t
```

Evaluates the pure operator of the node over its constant operands and gives the node holding
the result, null when there is no value to compute (an operand is no constant of the graph, the
node is no pure operation, or evaluating it faults). The node the answer names is the
transaction's to put in place of `n` with `replace`. A constant expression that can only fault
is left as written and warned about, as the C++ fold does.

- Example (a fragment, not compiled): `eval(t, n)`
- Why it is not compiled: t is an open transaction and n a node of its graph

#### `add_constant`

```camel
add_constant: (t: Txn<F>, g: Graph, value: T) => Node uses t when is_ordered::<T>()
```

Adds a value the transaction creates to the graph's static values and gives the node that
holds it. The value is a number, a bool or a string; a string is copied into the permanent
space because a value a transaction creates may be live at a safepoint where its draft is not
traced.

- Example: `add_constant(open((x: int): int => x + 1), graph_of((x: int): int => x + 1), 7)`

#### `commit`

```camel
commit: (t: Txn<F>) => F! uses t
```

Checks the edits and makes the changed function: the same type as the one that was opened, with
the values it captured, sharing every graph nothing changed. The transaction is over.

- Failure: error value `GraphConflict` when a graph the transaction touched changed since it was opened; error value `GraphInvalid` when an edit broke an invariant (the message names the graph, the node and the edge); error value `TxnUsed` when the transaction was over already.
- Example: `commit(open((x: int): int => x + 1))`

#### `abort`

```camel
abort: (t: Txn<F>) => void uses t
```

Drops the transaction.

- Example: `abort(open((x: int): int => x + 1))`

<a id="rewrite"></a>

## `rewrite`: rules applied to a program

Rewrite engines and their records. `rewrite`, `saturate` and `extract` are passes, functions
from a function to a function of the same type, `(f: F) => F!`, with the rule set and the
choices in angle brackets: `f->rewrite<rules>`, `f->saturate<rules, rounds: 8>`,
`f->extract<rules::nodes>`. A rule set is an ordinary `Rule[]`. `run` is `rewrite` with the
cost kept: it answers a `Run`, the function and what the application cost. `check` tests rules
on random instances. `explain` prints the shortest chain between two values of a run,
`explain_all` every rewrite that was made, and `why_not` says why a rule did not fire at a
value (rewrite design 8.7). A rule that stops a rewrite without changing the function is a
fault, and `strict` restricts the float rules to the ones that hold bit for bit.

The module also exports the reserved groups the language's own `rule`, `rule` with `when`, and
`fact` declarations compile to (`rewrite:rule`, `rewrite:rule_when`, `rewrite:fact`). They have
no callable Camel name, so they are not declared here.

### The passes

#### `rewrite`

```camel
rewrite: <rules: Rule[], strict: bool = false> (f: F) => F! when is_function::<F>()
```

Applies `rules` until no rule changes the function, and gives the rewritten function.

- Failure: error value `RuleInvalid` when a rule does not compile; error value `RuleTwoWay` when a rule is applied in a direction it does not allow.
- Example (a fragment, not compiled): `f->rewrite<rules>`
- Why it is not compiled: a rule set comes from the caller

#### `saturate`

```camel
saturate: <rules: Rule[], rounds: int = 6, strict: bool = false> (f: F) => F! when is_function::<F>()
```

Applies the rearranging rules too, for at most `rounds` rounds, and leaves the function with
every writing the saturation found; `extract` chooses among them.

- Failure: error value `RuleInvalid` when a rule does not compile.
- Example (a fragment, not compiled): `f->saturate<rules, rounds: 20>`
- Why it is not compiled: a rule set comes from the caller

#### `extract`

```camel
extract: <cost: (o: Op, inputs: float[]) => float> (f: F) => F! when is_function::<F>()
```

Chooses one writing of every value that has several, the one of least total cost. The cost of
a writing is `cost(o, inputs)`: the operator and the costs of the writings of its inputs.

- Example (a fragment, not compiled): `f->extract<rules::nodes>`
- Why it is not compiled: the cost function comes from `rules`

#### `run`

```camel
run: <rules: Rule[], rounds: int = 16, strict: bool = false, explain: bool = false> (f: F) => Run<F>! when is_function::<F>()
```

Applies `rules` one way, for at most `rounds` rounds, and gives the function it produced and
what the application cost. This is `rewrite` with the round budget explicit and the cost kept.
`explain: true` opens the attribution record (rewrite design 8.7): `explain` then reads back
the shortest chain between two values, and `explain_all` every rewrite that was made.
Recording is off unless it is asked for, so a plain application pays nothing for it.

- Failure: error value `RuleInvalid` when a rule does not compile; error value `RuleTwoWay` when a rule is applied in a direction it does not allow.
- Example (a fragment, not compiled): `f->run<rules, rounds: 8, explain: true>`
- Why it is not compiled: a rule set comes from the caller

### Checking rules

#### `check`

```camel
check: <samples: int = 100, seed: int = 0> (rules: Rule[]) => CheckReport
```

Checks `rules` on random instances drawn with `seed`: each row of the report carries the
instance (a generic law's type tuple), the verdict, what the verdict is about and the evidence
or the reason for it. The sample stream of a rule follows the rule's identity (its name and its
instance's type tuple), not its place in `rules`, so a rule draws the same samples in any call.
A build without a solver answers `Sampled` and `Refuted` and never `Proved`. A generic law is
checked at the types every operator group registered.

- Example (a fragment, not compiled): `rules->check<samples: 1000, seed: 7>`
- Why it is not compiled: `rules` comes from the caller

#### `check`

```camel
check: <samples: int = 100, seed: int = 0> (rules: Rule[], over: F) => CheckReport when is_function::<F>()
```

The same, with the law also checked at the types of the values `over` has, each once, in the
order its graphs write them. `over` is an ordinary argument, not a `with` one, so that both
overloads of `check` name each `with` position the same way: a named argument
(`check<samples: 1000>`) means one position in every declaration of the set, and a position one
declaration names `samples` and the other names `over` is one the name does not reach
(`OverloadParameterNames`). It cannot stand in the `with` list in front of `samples` and `seed`
either, because a `with` parameter without a default may not follow one that has a default
(`WithParameterAfterDefault`), and a function-typed one takes no default (`null` has type
`void`, and `F?` leaves `F` unbound). Written first, it is the argument the arrow carries:
`rules->check<8, 1>(f)`.

- Example (a fragment, not compiled): `rules->check((x: int) => x + 1)`
- Why it is not compiled: `rules` comes from the caller

#### `check_text`

```camel
check_text: (r: CheckReport) => string
```

The report's fixed rendering, one line per row, for a caller that wants it as a value.

- Example (a fragment, not compiled): `check_text(report)` gives `'sampled add_zero: proposition equality, evidence samples 100, ...'`
- Why it is not compiled: `report` is the report a check gives back: the example writes what reads it, and a doc example has no check to run

#### `coverage_table`

```camel
coverage_table: string
```

The declared coverage of the translation layer: the widths it translates (`int`, `i32`), the
widths the design lists beside them and it does not translate yet (`float`, `f32`, `bf16`,
`f16`), the operators it translates, what happens to integer division and remainder, what is
beyond translation coverage, and that a rule's condition is not a premise yet (rewrite design
8.1). The boundary is a value a reader can read and a test can pin.

- A value: written without parentheses, a constant where it is used.
- Example: `coverage_table` gives `'the coverage of the integer scalar translation\n...'`

### Reading a run

#### `explain`

```camel
explain: <a: Node, b: Node> (r: Run<F>) => Proof!
```

The shortest chain of rewrites of the run `r` that connects the values `a` and `b`, as the
derivation `a = ... = b`: only that chain, not every step the run made. Each line names the
rule and whether the step is read backwards; a chain through a value that was later rewritten
away names it too. When two chains are equally short both are printed, in the order the
rewrites were made.

- Failure: error value `NoAttribution` when the run was made without `explain: true`; error value `InvalidArgument` for a value of another function; error value `NoChain` when no rewrite connects the two values.
- Example (a fragment, not compiled): `r->explain<a, b>`
- Why it is not compiled: a run and two of its values come from the caller

#### `explain_all`

```camel
explain_all: (r: Run<F>) => Proof!
```

Every rewrite of the run `r`, in the order it made them, each naming the rule, the round, the
graph and the nodes that matched, were produced and were erased. This is the full record
`explain` narrows to one chain.

- Failure: error value `NoAttribution` when the run was made without `explain: true`; error value `InvalidArgument` for a value of another function.
- Example (a fragment, not compiled): `explain_all(r)`
- Why it is not compiled: a run comes from the caller

#### `why_not`

```camel
why_not: <rule: Rule, v: Node> (r: Run<F>) => string!
```

Why the rule `rule` did not fire at the value `v` of the run `r`: the first place the left side
fails to match, the value the pattern wanted there and the value the program has, a missing
permission, or the rule's condition being false with the values it read. A rule that did fire
at `v` is reported as such.

- Failure: error value `NoAttribution` when the run was made without `explain: true`; error value `InvalidArgument` for a value of another function.
- Example (a fragment, not compiled): `r->why_not<target, v>`
- Why it is not compiled: a run, a rule and a value come from the caller

### Reading a rule

#### `rule_name`

```camel
rule_name: (r: Rule) => string
```

The name of the rule `r`.

- Example (a fragment, not compiled): `rule_name(r)` gives `'int_add_zero'`
- Why it is not compiled: `r` is a rule of the library: the example writes the question, and a doc example has no library to take one from

#### `rule_two_way`

```camel
rule_two_way: (r: Rule) => bool
```

Whether the rule `r` may also be applied from right to left.

- Example (a fragment, not compiled): `rule_two_way(r)` gives `false`
- Why it is not compiled: `r` is a rule of the library: the example writes the question, and a doc example has no library to take one from

#### `rule_needs`

```camel
rule_needs: (r: Rule) => int
```

How many rewrites the rule `r` needs before it may fire.

- Example (a fragment, not compiled): `rule_needs(r)` gives `0`
- Why it is not compiled: `r` is a rule of the library: the example writes the question, and a doc example has no library to take one from

#### `rule_consts`

```camel
rule_consts: (r: Rule) => int
```

How many constants the rule `r` adds to the function.

- Example (a fragment, not compiled): `rule_consts(r)` gives `0`
- Why it is not compiled: `r` is a rule of the library: the example writes the question, and a doc example has no library to take one from

<a id="tiles"></a>

## `tiles`: programs on a CUDA device

Programs on a CUDA device. Where a computation runs is asked for in the source with the tag
`#gpu`, written on a function, a block or a namespace block (design principles 13.4), and the
card is chosen when the program runs, with `--devices`. The pass `tiles::compile` reads
the tags, outlines the regions the device can run, compiles them and runs the program: an
operator the device cannot run inside a `#gpu` scope is a compile error that names the operator
and the scope, never a quiet fall back to the host. An array on the device is an ordinary array
value whose data block lives there; the host reading it (printing, writing a file, turning it
into a host number) downloads it, and the reports of a run list every such transfer.

What a program does by hand is small: ask whether a device is there (`available`, `device`), move
a value (`upload`, `download`), and look at what would run (`source`, `inspect`, `benchmark`,
`regions`). The device and the driver are one resource, `driver`, so every call here keeps its
written order against the others and is never folded, merged or dropped. The functions to look
at are the `with` argument and the data is the example input, as for `map`:
`inputs->inspect<fn>`.

The functions that compute their type from an argument (`upload`, `download`, `source`,
`inspect`, `benchmark`, `regions`, and `run_preferred_resident`, the entry `tiles::compile` and
the tests use) are in `stdlib/signatures/tiles.cml`.

#### `upload`

```camel
upload: (value: f32[...]) => Device<f32[...]> uses driver
```

Uploads every leaf of the value -- an array, or a scalar of the element type it is written
with, alone or inside a tuple or a struct -- and gives the same tree with each leaf wrapped in
`Device<...>`. A leaf of any other type is refused when the call is compiled.

- Example (a fragment, not compiled): `host->upload` gives `a Device<f32[...]>`
- Why it is not compiled: `host` is a host tensor the caller has: the example writes the move, and a doc example has no device to move a value to

#### `download`

```camel
download: (value: Device<f32[...]>) => f32[...] uses driver
```

Downloads every device leaf of the value and gives the host value it came from. A tree with a
leaf that is not a device value is refused when the call is compiled.

- Example (a fragment, not compiled): `resident->download` gives `the array resident holds`
- Why it is not compiled: `resident` is a value already on the device: the example writes the download, and a doc example has no device to take one from

#### `run_preferred_resident`

```camel
run_preferred_resident: <fn: (a: f32, b: f32) => f32> (inputs: (f32, f32)) => Device<f32> uses driver
```

Runs the function through the device path the pipeline prepared for it -- the device when a
program can be made for it, the host otherwise -- and gives the resident form of its result.
This is the operator `tiles::compile` inserts for an outlined region and the tests use; a
program asks for the device with `#gpu`, not with this.

- Example: `(f32(2.0), f32(3.0))->run_preferred_resident<(a: f32, b: f32): f32 => a + b>` gives `a Device<f32>`

#### `source`

```camel
source: <fn: (a: f32, b: f32) => f32> (inputs: (f32, f32)) => string uses driver
```

The CUDA source the function compiles to, without running it.

- Example: `(f32(2.0), f32(3.0))->source<(a: f32, b: f32): f32 => a + b>`

#### `inspect`

```camel
inspect: <fn: (a: f32, b: f32) => f32> (inputs: (f32, f32)) => string uses driver
```

A report on the function's device plan, without running it: the kernel, its launch shape and
the values it would keep on the device.

- Example: `(f32(2.0), f32(3.0))->inspect<(a: f32, b: f32): f32 => a + b>`

#### `benchmark`

```camel
benchmark: <fn: (a: f32, b: f32) => f32> (inputs: (f32, f32)) => string uses driver
```

Times the function on the device, and on the host for comparison, and gives the report as JSON
text.

- Example: `(f32(2.0), f32(3.0))->benchmark<(a: f32, b: f32): f32 => a + b>`

#### `regions`

```camel
regions: <fn: (a: f32, b: f32) => f32> () => string uses driver
```

The regions the compiler would take for the whole program, as text: which nodes would run on
the device and why the others would not.

- Example: `regions<(a: f32, b: f32): f32 => a + b>()`

#### `available`

```camel
available: () => bool uses driver
```

Whether this machine can run a program on a CUDA device: false when the driver, the toolkit or
a visible device is missing. A capability question only -- a device the run names with
`--devices` and that is not there is a fault at start-up, never `false`.

- Example: `available()`

#### `device`

```camel
device: () => string! uses driver
```

A description of the CUDA device the run selects: its ordinal, name, compute capability and
memory.

- Failure: error value `DeviceUnavailable` when this build or this machine has no CUDA device.
- Example: `device() !! 'no device'`

<a id="pyplot"></a>

## `pyplot`: draw an array

Plots: draw an array of numbers with matplotlib, and fall back to an SVG file when matplotlib
is not installed. The operator writes an image file and is never folded or dropped by a pass.

The declarations of the operator of the C++ module `modules/pyplot` (design principles 6.4).
This file is the one source of its fixed signature; the C++ side
keeps the kernel, the executor, the operator traits and the purity.

`plot` is one operator with one URI, over four element types and two arities: an array of
`i32`, `int`, `f32` or `float`, with or without the name of the output file. A declaration
cannot write "an array of one of these four" as one rule, and a declaration generic over `T`
would accept a `string[]` that the kernel refuses, so the four types are written out for each
arity: eight declarations of the one operator. A declaration cannot write the optional
parameter `filename?: string` either, which is why the two arities are separate.

#### `plot`

```camel
plot: (data: i32[]) => void
plot: (data: int[]) => void
plot: (data: f32[]) => void
plot: (data: float[]) => void
plot: (data: i32[], filename: string) => void
plot: (data: int[], filename: string) => void
plot: (data: f32[], filename: string) => void
plot: (data: float[], filename: string) => void
```

Draws the values of `data` and writes the image to `filename` (`plot.png` when it is omitted).
`data` may be an `i32`, `int`, `f32` or `float` array; an empty array is drawn as an empty
plot. matplotlib is used when it is importable, and an SVG file is written otherwise.

- With effects: writes an image file.
- Example: `plot([1.0, 2.0, 3.0], "myplot.png")`

<a id="python"></a>

## `python`: the embedded interpreter

Camel calling Python: run code in an embedded interpreter, import modules, read attributes and
call what they hold. A `PyObject` is a handle into the interpreter, not a value of the program;
it is released when nothing refers to it any more, so there is nothing to dispose of by hand.
Values cross the boundary by copy: `to_py` makes the Python object of a Camel value, in the
Python form of its type, and `from_py` reads a Python object as a value of the type the call
names.

The Python form of a type:
  - `bool`, the integer types, the float types and `string` are the Python scalars of the same
    name, by value; `Bytes` is `bytes`;
  - a tuple is a `tuple`, a struct a `dict` of its fields by name, an array a `list`, and a map
    with string keys a `dict`, each of them by its parts;
  - `PyObject` itself passes through as it is.
What converts is a table, never whatever Python would accept: `bool` takes a bool only (not `5`),
the integers take an int that fits and not a bool or a float, the floats take a float or an int
and refuse a number the type cannot hold, `string` takes a str and not bytes.

Python code can do anything, including write files and print, and the interpreter holds state
between calls. So no function here names a resource of its own: each is a use of everything, in
the written order, never folded, merged or dropped, and it runs when its result is needed or it
is in a `sync` block. Whatever Python itself refuses -- an exception, a missing module, a missing
attribute -- is an error value of kind `PythonError` whose message is the exception, its text and
its traceback, never a fault of Camel's.

The interpreter is started the first time a function here runs.
The other direction, Python calling Camel, is the package `camel` (`pip install camel-lang`).

#### `exec`

```camel
exec: (code: string) => void!
```

Runs Python statements in the interpreter. Definitions and assignments stay visible to later
calls, as in a Python session.

- Failure: error value `PythonError` when the code raises.
- Example: `exec('x = 1')`

#### `eval`

```camel
eval: (expression: string) => PyObject!
```

Evaluates a Python expression and gives its value.

- Failure: error value `PythonError` when the expression raises.
- Example: `eval('1 + 2 * 3')->to_string !! ''` gives `'7'`

#### `run_file`

```camel
run_file: (path: string) => void!
```

Runs the Python script at the path.

- Failure: error value `PythonError` when the file cannot be read or the script raises.
- Example: `'scripts/hello.py'->run_file`

#### `import_module`

```camel
import_module: (name: string) => PyObject!
```

Imports a Python module (`'math'`, `'numpy'`, `'matplotlib.pyplot'`) and gives it. Importing runs
the body of the module and records it in `sys.modules`.

- Failure: error value `PythonError` when the import raises.
- Example: `import_module('math')->attr<'pi'>->to_string !! ''` gives `'3.141592653589793'`

#### `attr`

```camel
attr: <name: string> (obj: PyObject) => PyObject!
```

The attribute of a Python object; a dotted name walks the chain. Asking may run a property or
a descriptor, so it can raise.

- Failure: error value `PythonError` when the attribute does not exist or its getter raises.
- Example: `import_module('math')->attr<'pi'>`

#### `call`

```camel
call: <fn: PyObject, kwargs: Map<string, PyObject>? = null> (args: PyObject[]) => PyObject!
```

Calls a Python callable with the arguments the array holds, in order, and the keyword arguments
the callable was bound with. `call<fn>` is a function from an array of arguments to a result, so
it can be bound once and applied again.

- Failure: error value `PythonError` when the call raises.
- Example (a fragment, not compiled): `[2.0->to_py !! eval('0')]->call<sqrt>`
- Why it is not compiled: the callable is a Python object from `attr`, which the page does not show

#### `to_string`

```camel
to_string: (obj: PyObject) => string!
```

The `str()` of a Python object, as text.

- Failure: error value `PythonError` when `__str__` raises.
- Example: `eval('[1, 2]')->to_string !! ''` gives `'[1, 2]'`

#### `to_py`

```camel
to_py: (x: T) => PyObject! when has_python_form::<T>()
```

The Python object that stands for a Camel value, in the Python form of its type.

- Failure: error value `PythonError` when the interpreter cannot make the object.
- Example: `2.0->to_py->to_string !! ''` gives `'2.0'`

#### `from_py`

```camel
from_py: (obj: PyObject) => T! when has_python_form::<T>()
```

The Camel value of type T that a Python object holds. T is written at the call
(`from_py::<int>(obj)`) or taken from the type of the position the call stands in.

- Failure: error value `PythonTypeError` when the object does not have the type T (the message gives the path of the mismatch and what was found there); error value `PythonError` when reading it raises.
- Example: `eval('1 + 2')->from_py::<int> !! 0` gives `3`

<a id="nn"></a>

## `nn`: neural-network primitives

Neural-network primitives: 2-D convolution and its gradients, max and average pooling with
their gradients, batch normalization, embedding, the fused softmax cross-entropy loss, the
optimizers, and the checkpoint writer for a parameter tree. The operators work on the core
array type; nothing here needs PyTorch or a GPU.

### Convolution

#### `conv2d`

```camel
conv2d: (input: f32[...], kernel: f32[...], bias: f32[...], stride?: int, padding?: int) => f32[...]
```

2-D convolution: `input` is `[N, C, H, W]` f32, `kernel` is `[O, C, KH, KW]` f32 and `bias` is
`[O]` f32. `stride` defaults to 1 and `padding` to 0; the result is `[N, O, OH, OW]` f32 with
`OH = (H + 2*padding - KH) / stride + 1` and `OW` likewise. An input or kernel that is not
rank 4, or a window that does not fit, is refused when the call is compiled.

- Pure.
- Example: `conv2d(input, kernel, bias, 1, 0)` gives `[N, O, OH, OW]`

#### `conv2d_input_grad`

```camel
conv2d_input_grad: (input: f32[...], kernel: f32[...], dy: f32[...], stride?: int, padding?: int) => f32[...]
```

The gradient of `conv2d` with respect to its input, given the upstream gradient `dy` shaped
like the convolution's result; the result is shaped like `input`.

- Pure.
- Example: `conv2d_input_grad(input, kernel, dy, 1, 0)` gives `like x`

#### `conv2d_kernel_grad`

```camel
conv2d_kernel_grad: (input: f32[...], kernel: f32[...], dy: f32[...], stride?: int, padding?: int) => f32[...]
```

The gradient of `conv2d` with respect to its kernel, given `dy` shaped like the convolution's
result; the result is shaped like `kernel`.

- Pure.
- Example: `conv2d_kernel_grad(input, kernel, dy, 1, 0)` gives `like w`

#### `conv2d_bias_grad`

```camel
conv2d_bias_grad: (bias: f32[...], dy: f32[...]) => f32[...]
```

The gradient of `conv2d` with respect to its bias: the sum of `dy` over the batch and the
spatial axes, shaped like `bias`.

- Pure.
- Example: `conv2d_bias_grad(bias, dy)` gives `like b`

### Pooling

#### `max_pool2d`

```camel
max_pool2d: (input: f32[...], kernel: int, stride?: int, padding?: int) => f32[...]
```

Max pooling over a square window of `kernel` on `input` `[N, C, H, W]` f32. `stride` defaults
to `kernel`, `padding` to 0, and the result is `[N, C, OH, OW]`. A window that lies entirely in
the padding contributes -inf (the identity of the maximum).

- Pure.
- Example: `max_pool2d(input, 2)` gives `[N, C, H/2, W/2]`

#### `avg_pool2d`

```camel
avg_pool2d: (input: f32[...], kernel: int, stride?: int, padding?: int) => f32[...]
```

Average pooling over a square window of `kernel`: the window's elements plus +0 for those in
the padding are summed in an f64 accumulator and divided by `kernel*kernel`. `stride` defaults
to `kernel`, `padding` to 0, and the result is `[N, C, OH, OW]`.

- Pure.
- Example: `avg_pool2d(input, 2)` gives `[N, C, H/2, W/2]`

#### `max_pool2d_grad`

```camel
max_pool2d_grad: (input: f32[...], dy: f32[...], kernel: int, stride?: int, padding?: int) => f32[...]
```

The gradient of `max_pool2d` with respect to its input, given `dy` shaped like the pooling
result; the result is shaped like `input`.

- Pure.
- Example: `max_pool2d_grad(input, dy, 2)` gives `like x`

#### `avg_pool2d_grad`

```camel
avg_pool2d_grad: (input: f32[...], dy: f32[...], kernel: int, stride?: int, padding?: int) => f32[...]
```

The gradient of `avg_pool2d` with respect to its input, given `dy` shaped like the pooling
result; the result is shaped like `input`.

- Pure.
- Example: `avg_pool2d_grad(input, dy, 2)` gives `like x`

### Batch normalization

#### `batch_norm`

```camel
batch_norm: (input: f32[...], mean: f32[...], var: f32[...], gamma: f32[...], beta: f32[...], eps?: number) => f32[...]
```

Inference-mode batch normalization: `(input - mean) / sqrt(var + eps) * gamma + beta`, with
`eps` defaulting to 1e-5. Every tensor is f32 and the result is shaped like `input`.

- Pure.
- Example: `batch_norm(input, running_mean, running_var, gamma, beta)`

#### `batch_norm_train`

```camel
batch_norm_train: (input: f32[...], gamma: f32[...], beta: f32[...], running_mean: f32[...], running_var: f32[...], momentum?: number, eps?: number) => (f32[...], f32[...], f32[...])
```

Training-mode batch normalization: normalizes `input` with the batch statistics, and answers
`(y, new_running_mean, new_running_var)`, where `y` is shaped like `input` and the running
statistics are shaped like `running_mean`/`running_var`. `momentum` defaults to 0.1 and `eps`
to 1e-5.

- Pure.
- Example: `let (y, mean, variance) = batch_norm_train(input, gamma, beta, running_mean, running_var)`

#### `batch_norm_train_grad`

```camel
batch_norm_train_grad: (input: f32[...], gamma: f32[...], dy: f32[...], eps?: number) => (f32[...], f32[...], f32[...])
```

The gradients of training-mode batch normalization: `(dx, dgamma, dbeta)`, shaped like
`input`, `gamma` and `beta`. Only `y` carries gradient; the running-statistics blend is not
differentiated, so the operator takes `dy` (the gradient of `y`) and `eps`.

- Pure.
- Example: `let (dx, dgamma, dbeta) = batch_norm_train_grad(input, gamma, dy)`

### Embedding

#### `embedding`

```camel
embedding: (table: f32[...], indices: f32[...]) => f32[...]
```

Gathers rows of the rank-2 int-or-float table `[rows, dim]` by the rank-1 integer indices; the
result is `[indices.length, dim]`. An index outside `[0, rows)` is a fault.

- Pure.
- Failure: fault `RuntimeError` when an index is outside the table.
- Example: `embedding(table, indices)` gives `[2, dim]`

#### `embedding_table_grad`

```camel
embedding_table_grad: (table: f32[...], indices: f32[...], dy: f32[...]) => f32[...]
```

The gradient of `embedding` with respect to its table: unvisited rows stay zero, and the
result is shaped like `table`.

- Pure.
- Example: `embedding_table_grad(table, indices, dy)` gives `like table`

### Loss

#### `softmax_cross_entropy`

```camel
softmax_cross_entropy: (logits: f32[...], target: f32[...]) => float
softmax_cross_entropy: (logits: f32[...], target: f32[...] | number[]) => float
```

The mean softmax cross-entropy of rank-2 `logits` `[batch, classes]` against a same-shaped
target distribution. When the target is an integer array or a rank-1 integer tensor it is
read as one class label per row (the URI `nn:softmax_cross_entropy_labels`), and the value is
the same as the one-hot form's.

- Pure.
- Failure: fault `RuntimeError` when a label is outside `[0, classes)`.
- Example: `softmax_cross_entropy(logits, target)` gives `a float`

#### `softmax_cross_entropy_grad`

```camel
softmax_cross_entropy_grad: (logits: f32[...], target: f32[...], dy: number) => f32[...]
softmax_cross_entropy_grad: (logits: f32[...], target: f32[...] | number[], dy: number) => f32[...]
```

The gradient of `softmax_cross_entropy` with respect to `logits`, scaled by `dy`; the result is
shaped like `logits`. The label form (the URI `nn:softmax_cross_entropy_labels_grad`) takes
integer class labels instead of a target distribution and answers the same shape.

- Pure.
- Failure: fault `RuntimeError` when a label is outside `[0, classes)`.
- Example: `softmax_cross_entropy_grad(logits, target, 1.0)` gives `like logits`

### Optimizers

#### `sgd`

```camel
sgd: (params: P, grads: P, lr: float) => P
```

One step of stochastic gradient descent on a parameter tree: `params - grads * lr`, with the
result shaped like `params`. `grads` must be the gradient of `params` and `lr` is a number.

- Pure.
- Example: `let next = sgd({ w: 1.0 }, { w: 0.1 }, 0.1)`

#### `adam_state`

```camel
adam_state: (params: P) => OptimizerState
```

The initial `OptimizerState` of a parameter tree: zero first and second moments, and step 0.
The state's moment trees are shaped like `params`.

- Pure.
- Example: `let state = adam_state({ w: 1.0 })`

#### `adam`

```camel
adam: (params: P, grads: P, state: OptimizerState, lr: float, beta1?: number, beta2?: number, eps?: number) => (P, OptimizerState)
```

One step of Adam on a parameter tree: answers `(new_params, new_state)`, both shaped like
`params`/`state`. `beta1` defaults to 0.9, `beta2` to 0.999 and `eps` to 1e-8.

- Pure.
- Example: `let (next, state) = adam({ w: 1.0 }, { w: 0.1 }, adam_state({ w: 1.0 }), 0.001)`

#### `save_params`

```camel
save_params: (params: P, dir: string) => void
```

Saves every tensor leaf of `params` under `dir`, as `<dir>/<path>.npy`, the path joining struct
field names and tuple indices with dots; other leaves are ignored. The directories are
created when missing.

- With effects: writes files under `dir`.
- Failure: fault `RuntimeError` when the directory cannot be created or a leaf cannot be written.
- Example: `save_params({ w: [1.0, 2.0] as float[], b: [0.0] as float[] }, 'checkpoints/step-1')`

<a id="optim"></a>

## `optim`: optimizers written in Camel over `tree`

The optimizers: `sgd` and `adam`, each a value, with `init` and `update` the two pure functions
a training loop calls.

    let opt = adam(cosine_decay(0.001, steps, 0.0001));
    let state = init(opt, model);
    let (model, state) = update(opt, model, gradient, state);

A schedule is a function `(step: int) => float`: `constant(rate)`, `linear_decay(peak, total,
floor)` and `cosine_decay(peak, total, floor)` build one, and the rate the update of step `n`
uses is `schedule(n)`, with `n` numbered from one. `params` is a tree of nested structs and
tuples whose leaves are numbers and tensors, and `grads` is the gradient of that tree, which
`with_grad` or `grad` gives; a tree that merely has the same type as the parameters is refused.

Every number is computed in double and rounded once, when it is stored. The arithmetic follows the
element type the leaf's own type writes: a tensor leaf of `adam` is widened to f64 and updated
there, and stored back at the element type the leaf has, so a trajectory written here is the
trajectory `modules/tensor/kernels/update.h` defines, bit for bit.

#### `constant`

```camel
constant: (rate: float) => (step: int) => float
```

The same rate at every step.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `constant(0.1)(3)` gives `0.1`

#### `linear_decay`

```camel
linear_decay: (peak: float, total: int, floor: float) => (step: int) => float
```

A rate that falls from `peak` to `floor` in a straight line: `peak * (1 - step / total)` below
step `total`, and exactly `floor` from there on. `total` is at least one.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `linear_decay(0.1, 4, 0.0)(2)` gives `0.05`

#### `cosine_decay`

```camel
cosine_decay: (peak: float, total: int, floor: float) => (step: int) => float
```

A rate that falls from `peak` to `floor` along a cosine: `floor + (peak - floor) *
(1 + cos(pi * step / total)) / 2` below step `total`, and exactly `floor` from there on.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `cosine_decay(0.1, 4, 0.0)(1)` gives `0.08535533905932738`

#### `sgd`

```camel
sgd: (schedule: (step: int) => float) => Sgd
```

Plain stochastic gradient descent: `p - rate * g` at every leaf, the rate of the step taken.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `sgd(constant(0.1))`

#### `adam`

```camel
adam: (schedule: (step: int) => float, beta1: float = 0.9, beta2: float = 0.999, eps: float = 0.00000001, decay: float = 0.0) => Adam
```

Adam. The constants default to the ones the reference kernel's callers use: beta1 0.9, beta2
0.999, eps 1e-8, and a decoupled weight decay of zero.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `adam(constant(0.001))`
- Example: `adam(constant(0.001), beta1: 0.5, eps: 0.0001)`

#### `adamw`

```camel
adamw: (schedule: (step: int) => float, beta1: float = 0.9, beta2: float = 0.999, eps: float = 0.00000001, decay: float = 0.01) => Adam
```

`adam` with a decoupled weight decay, 0.01 by default: the parameter is first moved by
`rate * decay` of itself, and the adaptive update then works on the moved parameter; the moments
see the gradient alone, which is what makes the decay decoupled.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `adamw(constant(0.001))`
- Example: `adamw(constant(0.001), decay: 0.1)`

#### `init`

```camel
init: (opt: Sgd, params: P) => SgdState
```

The state `sgd` starts from: no moments to carry, only the step count.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `init(sgd(constant(0.1)), { w: 1.0 })` gives `{ step: 0 }`

#### `init`

```camel
init: (opt: Adam, params: P) => AdamState<P>
```

The state `adam` starts from: the two moment trees at zero, shaped like the parameters, and the
step count.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `init(adam(constant(0.1)), { w: 1.0 })` gives `{ m: { w: 0.0 }, v: { w: 0.0 }, step: 0 }`

#### `update`

```camel
update: (opt: Sgd, params: P, grads: G, state: SgdState) => (P, SgdState)
```

One `sgd` update: `(params, state)`, with the step advanced by one and the rate taken from
`opt.schedule` at the step this update takes, numbered from one.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `update(sgd(constant(0.1)), { w: 1.0 }, { w: 0.5 }, init(sgd(constant(0.1)), { w: 1.0 }))`

#### `update`

```camel
update: (opt: Adam, params: P, grads: G, state: AdamState<P>) => (P, AdamState<P>)
```

One `adam` update: `(params, state)`, with the step advanced by one and the rate taken from
`opt.schedule` at the step this update takes, numbered from one. A `decay` other than zero moves
the parameters by the decoupled weight decay first.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `update(adam(constant(0.1)), { w: 1.0 }, { w: 0.5 }, init(adam(constant(0.1)), { w: 1.0 }))`

<a id="autodiff"></a>

## `autodiff`: gradients of functions

Automatic differentiation: function transforms that turn a function into the function of its
gradient. `grad(f)` and `with_grad(f)` take the function as an ordinary argument (it is what is
transformed, not a configuration) and give a function of the same parameters, so
`with_grad(loss)<model>(x, y)` is the loss together with the gradient of the model, and the two
steps can be written apart: `let step = with_grad(loss)`, then `step<model>(x, y)` in the loop.

What is differentiated is the first `with` parameter of `f` (the weights); every other `with`
parameter is a constant, and so is every ordinary parameter. To differentiate the data, bind it
as a `with` parameter with a lambda. A function with no `with` parameter, or whose first one has
no tangent, or a result that is not a scalar float, is refused where the call is compiled.
There is no `argnums`: which value is differentiated is what the `with` binding says, not a
position, so a call that would name one is refused as the unknown parameter it is.

`has_aux: true` is for a function whose result is the pair `(value, aux)`, the shape JAX uses it
for: the first element is the loss and the second is anything the caller wants carried (a count,
a norm). The pair is split, the first element is differentiated and the second is handed back
unchanged: `grad(f, has_aux: true)` gives `(gradient, aux)` and
`with_grad(f, has_aux: true)` gives `((value, aux), gradient)`, which are JAX's orders.
The argument has to be the constant `true` -- a call has one result type, so whether the pair is
split cannot follow a value -- and `has_aux: false` is refused with the plain call to write.

The gradient has the type of the parameter it is the gradient of: a struct gives a struct of
gradients, a tuple a tuple, an array of floats an array of the same element type and shape, a
float a float of its own type. An integer or a bool leaf is not a continuous quantity: its
gradient is a zero of its own type, so a parameter tree that carries a counter can be updated by
leaving the counter as it is. A string or a function leaf has no gradient and is refused with
the path of the leaf named. A value that depends on the differentiated parameter but has no way
for its gradient to flow (an array of strings read inside a loop) is refused as well, never
dropped.

`grad` and `with_grad` are the transforms of reverse mode, built on the pass mechanism: they
need `std::macro` to have expanded what they differentiate, and they leave a call whose callee is
not known when they run to a run-time refusal. `vjp` is reverse mode for a result that is not a
scalar (it gives the result and the pullback from the cotangent of the result to the gradient),
and `jvp` is forward mode (the result and its tangent along a direction); both land with the
autodiff lane, not before they work.

The memory-for-recomputation transform -- `remat` -- is not here: it is a transform of the
`transforms` module (`stdlib/signatures/transforms.cml`), because what it changes is a property of
a graph and a call site, not a derivative. JAX calls the same transform `jax.checkpoint` and, by
its other name, `jax.remat`; in this tree "checkpoint" is the persistence module
`stdlib/ckpt.cml` and stays that, so the transform takes the other word and there is no second
name for a reader to disambiguate.

`stop_gradient` marks a value as a constant, and the mathematics of the local rules is written
here, where the library keeps one statement of it: `add_tangent` and its siblings are the tangent
of a primitive, `add_cotangent` and its siblings its cotangent. The rules themselves -- the
declarations that attach those statements to a primitive -- live in the ruleset modules, which is
what a transform reads: `stdlib/rulesets/jvp.cml` for the forward rules and
`stdlib/rulesets/transpose.cml` for the transposes. A tag gives a function's own rules
(`#jvp(rule)` forward, `#transpose(rule)` for a linear function, `#vjp(rule)` the pullback) and
is read back by structure (`graph::rule_of`); a primitive's rules are the ruleset's, by the
operator of their left side.

#### `grad`

```camel
grad: (f: F) => Gradient<F> when is_function::<F>()
```

The gradient function of `f`: it takes the parameters of `f` and gives the gradient of `f`'s
result with respect to its first `with` parameter, in the type of that parameter.

- Example (a fragment, not compiled): `let loss_grad = grad(loss)`
- Why it is not compiled: `loss` must have a `with` parameter for its gradient to exist, and that takes a declaration, so the example is a fragment of a program that declares it

#### `grad`

```camel
grad: (f: F, has_aux: bool) => GradientAndAux<F> when is_function::<F>()
```

The same over a function whose result is the pair `(value, aux)`: the first element is
differentiated and the second is handed back unchanged, so the gradient function gives
`(gradient, aux)` -- JAX's `grad(f, has_aux=True)`. `has_aux` has to be the constant `true`:
the pair is split, or the writer means the plain form and writes `grad(f)`.

- Example (a fragment, not compiled): `let loss_grad = grad(loss, has_aux: true)`
- Why it is not compiled: the function must return a pair whose first element is the loss, and that takes a declaration, so the example is a fragment of a program that declares it

#### `with_grad`

```camel
with_grad: (f: F) => ValueAndGradient<F> when is_function::<F>()
```

The value and the gradient together: the function it gives returns `(result of f, gradient)`,
the pair a training step needs from one evaluation. The same compile-time refusals as `grad`.

- Example (a fragment, not compiled): `let step = with_grad(loss)`
- Why it is not compiled: `loss` must have a `with` parameter for its gradient to exist, and that takes a declaration, so the example is a fragment of a program that declares it

#### `with_grad`

```camel
with_grad: (f: F, has_aux: bool) => ValueAndGradientAndAux<F> when is_function::<F>()
```

The value, the auxiliary value and the gradient of a function whose result is `(value, aux)`:
the pair the function gives is returned whole, followed by the gradient --
`((value, aux), gradient)`, JAX's `value_and_grad(f, has_aux=True)`.

- Example (a fragment, not compiled): `let step = with_grad(loss, has_aux: true)`
- Why it is not compiled: the function must return a pair whose first element is the loss, and that takes a declaration, so the example is a fragment of a program that declares it

#### `stop_gradient`

```camel
stop_gradient: (x: T) => T pure
```

Gives its argument unchanged and cuts the gradient at this point: a value passed through
`stop_gradient` is a constant to `grad`. Any value is accepted, and the result has the
argument's own type.

- Example: `stop_gradient(3.0)` gives `3.0`

### The local rules of the scalar arithmetic

One law, written once: the pattern names the primitive and the right side what the transform
makes of it. Forward mode's right side is "the tangents of the arguments => the tangent of the
result", linear in the tangents; a linear primitive's transpose's right side is "the cotangent
of the result => the cotangent of the argument that carries the data". The value the primitive
was given is a value here, not a constant of the rule, so `mul_t` is also the transpose of
`x * 3`.

Each right side is the named function below it, so the tangent a transform produces is a value
a program can call and compare with the derivative it claims, and the library keeps one writing
of the mathematics (design principles: one law, one writing).

A constant of a graph and a reference to a parameter are not primitives: a constant has no
tangent and a parameter's tangent is its own, so a transform lifts the first to a zero tangent
and passes the second through, without a rule.

#### `add_tangent`

```camel
add_tangent: (x: T, w: T, dx: T, dw: T) => T when is_float::<T>()
```

The tangent of `x + w` along `(dx, dw)`: `dx + dw`.

- Example: `add_tangent(3.0, 5.0, 1.0, 0.0)` gives `1.0`

#### `sub_tangent`

```camel
sub_tangent: (x: T, w: T, dx: T, dw: T) => T when is_float::<T>()
```

The tangent of `x - w` along `(dx, dw)`: `dx - dw`.

- Example: `sub_tangent(3.0, 5.0, 1.0, 0.0)` gives `1.0`

#### `mul_tangent`

```camel
mul_tangent: (x: T, w: T, dx: T, dw: T) => T when is_float::<T>()
```

The tangent of `x * w` along `(dx, dw)`: `dx * w + x * dw`.

- Example: `mul_tangent(3.0, 5.0, 1.0, 0.0)` gives `5.0`

#### `div_tangent`

```camel
div_tangent: (x: T, w: T, dx: T, dw: T) => T when is_float::<T>()
```

The tangent of `x / w` along `(dx, dw)`: `dx / w - x * dw / (w * w)`.

- Example: `div_tangent(6.0, 4.0, 1.0, 0.0)` gives `0.25`

#### `neg_tangent`

```camel
neg_tangent: (x: T, dx: T) => T when is_float::<T>()
```

The tangent of `-x` along `dx`: `-dx`.

- Example: `neg_tangent(3.0, 1.0)` gives `-1.0`

#### `add_cotangent`

```camel
add_cotangent: (ct: T) => T when is_float::<T>()
```

The cotangent of `x` in `x + c`: the cotangent of the sum, unchanged.

The first five take only the values their answer is a function of -- `ct`, and the other name
where the answer reads it. A transpose rule's right side names what it calls with exactly these,
so a position whose answer does not read an operand asks for no value of it; that is what lets
the transposed loop body answer a rule whose other operand is the round's own state (design
principles: a value the walk does not carry costs nothing unless the rule reads it).

- Example: `add_cotangent(2.0)` gives `2.0`

#### `sub_cotangent`

```camel
sub_cotangent: (ct: T) => T when is_float::<T>()
```

The cotangent of `x` in `x - c`: the cotangent of the difference, unchanged.

- Example: `sub_cotangent(2.0)` gives `2.0`

#### `mul_cotangent`

```camel
mul_cotangent: (c: T, ct: T) => T when is_float::<T>()
```

The cotangent of `x` in `x * c`: `ct * c`.

- Example: `mul_cotangent(5.0, 2.0)` gives `10.0`

#### `div_cotangent`

```camel
div_cotangent: (c: T, ct: T) => T when is_float::<T>()
```

The cotangent of `x` in `x / c`: `ct / c`.

- Example: `div_cotangent(4.0, 2.0)` gives `0.5`

#### `neg_cotangent`

```camel
neg_cotangent: (ct: T) => T when is_float::<T>()
```

The cotangent of `x` in `-x`: `-ct`.

- Example: `neg_cotangent(2.0)` gives `-2.0`

### The other half: the cotangent of each name of a rule's left side

The five above answer the cotangent of `x`, the first name their rule's left side binds. A rule
like `x - c` has a second name, and its cotangent is not the one above with the arguments swapped:
`sub_cotangent(ct)` is `ct`, while the cotangent of `c` in `x - c` is `-ct`. So each name gets its
own function, named by position, and a rule's right side answers both -- a tuple, in the order the
left side names them -- so the transposed graph calls the one for the name it is writing, and no
transform re-derives the arithmetic in C++.

`x` keeps its own names above (`mul_cotangent` and so on) and nothing here replaces them: `vjp` and
`jvp` call those, and their meaning -- the cotangent of the first name -- is the meaning they keep.
What changed is only their parameters: each takes the values its answer reads, so a rule that can
be answered without an operand does not name it and does not need it.

#### `add_cotangent_c`

```camel
add_cotangent_c: (ct: T) => T when is_float::<T>()
```

The cotangent of `c` in `x + c`: the cotangent of the sum, unchanged.

- Example: `add_cotangent_c(2.0)` gives `2.0`

#### `sub_cotangent_c`

```camel
sub_cotangent_c: (ct: T) => T when is_float::<T>()
```

The cotangent of `c` in `x - c`: `-ct`, the opposite sign of `sub_cotangent(ct)`.

- Example: `sub_cotangent_c(2.0)` gives `-2.0`

#### `mul_cotangent_c`

```camel
mul_cotangent_c: (x: T, ct: T) => T when is_float::<T>()
```

The cotangent of `c` in `x * c`: `ct * x`.

- Example: `mul_cotangent_c(3.0, 2.0)` gives `6.0`

#### `div_cotangent_c`

```camel
div_cotangent_c: (x: T, c: T, ct: T) => T when is_float::<T>()
```

The cotangent of `c` in `x / c`: `-(ct * x / (c * c))`.

- Example: `div_cotangent_c(6.0, 4.0, 2.0)` gives `-0.75`

<a id="rulesets.jvp"></a>

## `rulesets.jvp`: how a forward transform lifts a value

The `jvp` ruleset: how a forward transform lifts a value (design principles 9.9, program
transforms).

    let (y, dy) = lift(3.0);   // 3.0 and its zero tangent

`Lift<T>` is a value and the tangent of that value, and `lift(x)` is the value plus the zero
tangent of its type. A constant and a captured value are lifted this way, so a straight-line
program is lifted node by node and a call hands its parameters on in the same shape.

Every rule here is `export`ed: the caller that attaches one to an operator lives in another
module, and a rule that is not exported is refused where it is imported.

Adding a rule changes docs/stdlib-reference.md; regenerate it with
`node scripts/stdlib-reference.mjs --write`.

#### `lift`

```camel
lift: (x: T) => Lift<T>
```

`x` lifted: the value, and the zero tangent of its type -- the empty tuple for a type that has
no tangent, a tensor of zeros for a tensor, and each member's own zero for a tuple or a struct.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `lift(3.0)` gives `(3.0, 0.0)`

#### `mul_jvp`

```camel
mul_jvp: (x: f32, y: f32, d: (f32, f32)) => (f32, Tangent<f32>)
```

The forward rule of `*` on two 32-bit floats: the product rule, `x*dy + y*dx`.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `mul_jvp(f32(2.0), f32(3.0), (f32(0.5), f32(0.25)))` gives `(6.0, 3.0)`

#### `mul_jvp`

```camel
mul_jvp: (x: float, y: float, d: (float, float)) => (float, Tangent<float>)
```

The forward rule of `*` on two 64-bit floats.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `mul_jvp(2.0, 3.0, (0.5, 0.25))` gives `(6.0, 3.0)`

#### `sub_jvp`

```camel
sub_jvp: (x: f32, y: f32, d: (f32, f32)) => (f32, Tangent<f32>)
```

The forward rule of `-` on two 32-bit floats: the tangents subtract the same way.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `sub_jvp(f32(5.0), f32(3.0), (f32(0.5), f32(0.25)))` gives `(2.0, 0.25)`

#### `sub_jvp`

```camel
sub_jvp: (x: float, y: float, d: (float, float)) => (float, Tangent<float>)
```

The forward rule of `-` on two 64-bit floats.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `sub_jvp(5.0, 3.0, (0.5, 0.25))` gives `(2.0, 0.25)`

#### `div_jvp`

```camel
div_jvp: (x: f32, y: f32, d: (f32, f32)) => (f32, Tangent<f32>)
```

The forward rule of `/` on two 32-bit floats: the quotient rule, `(y*dx - x*dy) / (y*y)`.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `div_jvp(f32(6.0), f32(2.0), (f32(1.0), f32(0.25)))` gives `(3.0, 0.125)`

#### `div_jvp`

```camel
div_jvp: (x: float, y: float, d: (float, float)) => (float, Tangent<float>)
```

The forward rule of `/` on two 64-bit floats.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `div_jvp(6.0, 2.0, (1.0, 0.25))` gives `(3.0, 0.125)`

### The forward rule of `^` (a power)

#### `pow_tangent`

```camel
pow_tangent: (x: T, w: T, dx: T, dw: T) => T when is_float::<T>()
```

The tangent of `x ^ w` along `(dx, dw)`: `w * x^(w-1) * dx + x^w * log(x) * dw`.

The two terms answer two different questions, and keeping them apart is what makes the negative
base honest. The first term is the derivative with respect to the **base**, and it is defined
wherever `x ^ w` is. The second is the derivative with respect to the **exponent**, and it is
`x^w * log(x)`: for `x <= 0` that has no real value, because a real power of a negative number
exists only for integer exponents and has no derivative in the exponent there.

**No branch on a tangent's value.** The author's ruling of 2026-11-04 (`docs/handover/reviews/
2026-11-04-a-guarded-tangent-cannot-be-transposed-what-does-the-power-keep.cn.md`) took the
`if dw == T(0)` guard this helper used to carry away: the zero of a constant's tangent is
**structurally known** -- a constant has no tangent -- and not a value a law computes and
compares. What replaces it happens before anything runs: the rule's right side is expanded with
the structurally-zero tangents named, and the product one of them multiplies is omitted rather
than computed (`modules/transforms/rule_expand.cpp#expandRuleRightSide`). So `(-3.0) ^ 2.0`
still answers `-6.0` and `log(-3.0)` is never asked for its `NaN`, while a law with no branch
is a law the backward walk can turn around: `^`'s pullback answers the same number as `pow`'s
(`test/cases/compile/transforms/pow_gradient_through_the_library.cml` against
`pow_gradient_of_a_caret_through_the_library.cml`).

A program that calls this helper itself hands it a real `dw`, and then the second term is a real
term: at a negative base it answers `NaN`, because the derivative in the exponent does not exist
there. The omission is the rule expander's, not this function's -- there is nothing here that
could omit it, which is why the law below is written out rather than called.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `pow_tangent(2.0, 3.0, 0.0, 1.0)` gives `5.545177444479562`
- Example: `pow_tangent(-3.0, 2.0, 1.0, 0.0)` gives `nan`

<a id="rulesets.vmap"></a>

## `rulesets.vmap`: how a batched transform lifts a value

The `vmap` ruleset: what a batched value is, and how a primitive is written when every operand
carries a batch (`docs/design/program-transforms/README.cn.md` 4.1, 5.4).

    let rows = lift(xs);          // the batch of rows a function of one value takes

`Lift<T>` is `RowsOf<T>`: the one value a primitive works on, with one dimension of unknown length
in front of it (`stdlib/types.cml`), which is exactly the type `vmap`'s parameter has. A scalar
`f32` lifts to the batch of `f32` rows (`f32[]`); a row `f32[3]` lifts to the batch of rows
(`f32[?, 3]`). So a batched program is a program over the same values with one more dimension in
front, and an elementwise primitive needs no new arithmetic for it: `bx + bw` is `x + w` applied
element by element, which is the row-by-row application `map` writes out.

Every rule here is `export`ed: the transform that reads this family is in another module, and a
rule that is not exported is refused where it is imported.

A rule's right side takes the *lifted* operands and answers the *lifted* result. For `jvp` that is
"the tangents in, the tangent out"; for `vmap` it is "the batches in, the batch out". The
elementwise tier is therefore one rule per primitive, each of them the primitive itself: the
batching of an elementwise operator is that operator.

This round writes the elementwise tier, `matmul`, the six reductions along an axis, and the six
over every axis. The first group need a rule that says *which* axis the batch is on: a batch of
rows under `matmul` is the axes before its last two, and a reduction along an axis keeps the axis
it reduces and gains the batch axis in front, so its rule is written in terms of the operator's
own axis argument (`batched_axis`). A reduction over every axis takes no axis at all -- there is
none of the operator's to shift -- so its rule keeps the batch axis in front and folds away the
axes the row had after it, over the rank the value itself carries (`shape`). `sum`, `mean`, `max`
and `min` are written that way. `argmax` and `argmin` answer a *position*, which no fold of axis
positions produces (`argmax` of a `float[2, 3]` row is 5, not `[1, 2]`), so their rule reads the
batch as one line instead: `reshape<[shape(xs)[0], -1]>(xs)` puts a row's elements on its last
axis, and `argmax` along that axis counts them -- see the section below `vmap_rule_min`.

`reshape` and the broadcasting moves are the next tier.

Adding a rule changes docs/stdlib-reference.md; regenerate it with
`node scripts/stdlib-reference.mjs --write`.

#### `lift`

```camel
lift: (x: T) => Lift<T>
```

`x` lifted: a constant or a captured value becomes a batch of one row, which every rule
broadcasts over the batch it meets (the elementwise operators of `tensor` take a value beside an
array as that value at every element).

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `lift(3.0)` gives `[3.0]`

### The elementwise tier

A rule is filed in its ruleset module under the head of its left side -- an operator's token, or
the name a call writes -- and the number of operands that head takes, and a transform reads it
from there (`lookupRule("rulesets.vmap", head, arity)`); a rule is not a function a program calls,
so the rules below and the functions they call are two things with different names.

The right side of each rule *names* the function that does the batched arithmetic
(`vmap_add(bx, bw)`), and that name is the part a batching transform reads. A rule's right side is
two arrows: the outer one takes the primitive's operands, the inner one takes the lifted half. A
batched graph has no unbatched operands to give the outer one -- `Lift<T>` replaced the whole
chain with batches -- so the transform calls the named function with the batches instead, and the
rule mechanism is unchanged. `rhsCalleeOf("rulesets.vmap", "vmap_rule_add")` is `vmap_add`.

Five keys cover the scalar arithmetic: `+`, `-`, `*`, `/` at two operands and `-` at one. `-x` and
`x - w` are two primitives that share one token, which is why the operand count is part of the
key (stdlib/rulesets/jvp.cml files the same five).

#### `vmap_add`

```camel
vmap_add: (a: T[], b: T[]) => T[] when is_numeric::<T>()
```

`x + w` of one row, batched: the same addition, element by element.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_add([1.0, 2.0], [3.0, 4.0])` gives `[4.0, 6.0]`

#### `vmap_sub`

```camel
vmap_sub: (a: T[], b: T[]) => T[] when is_numeric::<T>()
```

`x - w` of one row, batched.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_sub([3.0, 4.0], [1.0, 2.0])` gives `[2.0, 2.0]`

#### `vmap_mul`

```camel
vmap_mul: (a: T[], b: T[]) => T[] when is_numeric::<T>()
```

`x * w` of one row, batched.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_mul([1.0, 2.0], [3.0, 4.0])` gives `[3.0, 8.0]`

#### `vmap_div`

```camel
vmap_div: (a: T[], b: T[]) => T[] when is_numeric::<T>()
```

`x / w` of one row, batched.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_div([3.0, 8.0], [3.0, 4.0])` gives `[1.0, 2.0]`

#### `vmap_neg`

```camel
vmap_neg: (a: T[]) => T[] when is_numeric::<T>()
```

`-x` of one row, batched. The key is `-` at one operand, not `-` at two.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_neg([1.0, -2.0])` gives `[-1.0, 2.0]`

### The product of two arrays

The five keys above are the *scalar* arithmetic: `x * w` on two `f32` is `:op/mul_d`. On two
arrays the same spelling resolves to another primitive, `tensor:multiply`, and the two are one law
at two ranks -- the product, element by element -- but they are not one rule, because a rule is
instantiated at its primitive's *element* type (`ruleElementTypeOf`, modules/transforms/vmap.cpp):
`f32` here, the same `T` the scalar rule gets, while the two operators are different primitives and
a key holds one rule each.

So the operand is written as the open rank `T[...]`: the batch of a row is that row's element type at
any rank, and the operator walks all of the ranks it is given. `mul_tensor(x, w)` is the same
product at whatever rank the row had, and its right side multiplies the whole batch at once -- the
primitive applied to the batch instead of to each row, which is the same operator and so the same
bits.

The key is `mul_tensor`, a call, because the array product has no infix spelling a rule's left side
could be written with -- `r * r` resolves to the operator, but the operator is not a token. A call
is a key like any other (`f(a, b)` is `f` at two operands), and `tensor:multiply` is bound to this
one where the operator is declared: `modules/tensor/module.cpp`, `bindVmapRule` -- the batching
table, which is what a batching transform reads. An operator with no binding is an operator no rule
is reachable for, and the transform says so by name at the primitive. The right side names a
*different* function than the left side does, which the index requires: a name the left side binds
is a pattern variable to the right side, and this family's transform reads the callee's name and
calls it with the batch -- it never binds the pattern.

#### `vmap_mul_tensor`

```camel
vmap_mul_tensor: (a: T[...], b: T[...]) => T[...] when is_numeric::<T>()
```

The product of two batches: the whole batch multiplied at once, which for an elementwise product is
the batch of the row-by-row products. The parameters are the open rank for the reason `vmap_matmul`
gives below: a lifted type does not name the element to a call's inference.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_mul_tensor([[1.0, 2.0], [3.0, 4.0]] as f32[2, 2], [[10.0, 10.0], [10.0, 10.0]] as f32[2, 2])` gives `[[10.0, 20.0], [30.0, 40.0]]`

### The element of a row

`r[0]` on a row is `:op/idx_arr`, and batching it gathers one element per row. This is the one rank
where the rule's type parameter is not the type the operand has: a rule is instantiated at its
primitive's *result* type (`modules/transforms/vmap.cpp`, `elementType = node->dataType()`), which
for an index is the element (`f32`) while the value being indexed is the row (`f32[3]`). So the row
is spelled from the element -- `T[]`, an array of `T` -- and the batch of rows is one dimension in
front of that, `Lift<T[]>`, which for a row of `f32` is `f32[?, ?]`. The index is a batch as well
(a constant in the body lifts to a batch of one row), so the gather reads it through `at`, the
one-row broadcast every helper here uses.

#### `idx_batch`

```camel
idx_batch: (xs: Lift<T[]>, i: int[]) => Lift<T>
```

One element per row: row `j` of the batch contributes `xs[j][i[j]]`, and the results are the batch
`Lift<T>`. Cost is one strided read per row -- `len(xs)` of them, no copy of any row.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `idx_batch::<f32>([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]] as f32[2, 3], [2, 1])` gives `[3.0, 5.0]`

### Matmul

A batched matrix product adds the batch axis in front of both operands (`[b, m, k] x [b, k, n]`),
and those are exactly the axes `matmul` already walks as its batch axes (its last two are the
product's). So the rule is the operator over the lifted operands and nothing else: no row loop, no
reshape. An operand that is a constant of the body is the batch of one row (`lift`), and one row
broadcasts over a batch of many -- the operator's own broadcasting, which is the same rule the
operator states, not a second one of ours.

#### `vmap_matmul`

```camel
vmap_matmul: (lhs: T[...], rhs: T[...]) => T[...] when is_numeric::<T>()
```

`matmul(lhs, rhs)` batched: the product of each row of `lhs` with the row the batch of `rhs` gives
it. A batch of one row is that row at every index.

The parameters are the open rank `T[...]` rather than `Lift<T[...]>` even though the batch is what
they are given: the transform passes the lifted operands, and a parameter written `Lift<T[...]>`
says nothing about `T` to a call's inference (the element is one layer down a type computation),
so the rule's right side could not call this function without naming the type again -- and a
right side that names a type argument is a right side no transform can read the callee from
(`rhsCalleeOf`, include/camel/parse/ast/rule_head.h). An open rank takes the batch all the same:
it is the type that states nothing about the extents, and the batch's own extents are the value's.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_matmul([[1.0, 2.0]] as float[1, 2], [[3.0], [4.0]] as float[2, 1])` gives `[[11.0]]`

### The reductions along an axis

A reduction keeps the axis it reduces -- as an extent of one with `keepdims`, as nothing without
it -- and the batch adds one axis in front. So the rule is written in terms of the operator's own
axis argument, and the only thing to translate is that argument: the row's axis `a` is the axis
one place further in the lifted value, and an axis counted from the last (`-1`) stays what it was,
because the last axis of the lifted value is the last axis of the row. Nothing is reshaped: the
batch is an axis these operators already walk.

#### `vmap_sum_axis`

```camel
vmap_sum_axis: (xs: T[...], axis: int[], keepdims: bool[]) => T[...]
```

`sum<axis, keepdims>(xs)` batched: each row's sum along the axis it was given. The parameters
are the open rank for the reason `vmap_matmul` gives: a lifted type does not name the element to a
call's inference, and a right side may not name it either.

The axis argument is the *row's*, so the example below reduces the row's axis 1 -- the sum of each
row of the value -- and not its axis 0: the batch is one axis in front of the one the row counts
from (`batched_axis`).

- A native operator of this module: an opaque node, pure.
- Example: `vmap_sum_axis([[1.0, 2.0], [3.0, 4.0]] as float[2, 2], [0], [false])` gives `[3.0, 7.0]`

#### `vmap_mean_axis`

```camel
vmap_mean_axis: (xs: T[...], axis: int[], keepdims: bool[]) => T[...]
```

`mean<axis, keepdims>(xs)` batched: each row's mean along the axis it was given.

- A native operator of this module: an opaque node, pure.
- Example: `vmap_mean_axis([[1.0, 2.0], [3.0, 4.0]] as float[2, 2], [0], [false])` gives `[1.5, 3.5]`

#### `vmap_max_axis`

```camel
vmap_max_axis: (xs: T[...], axis: int[], keepdims: bool[]) => T[...]
```

`max<axis, keepdims>(xs)` batched: each row's largest element along the axis it was given.

- A native operator of this module: an opaque node, pure.
- Example: `vmap_max_axis([[1.0, 5.0], [3.0, 4.0]] as float[2, 2], [0], [false])` gives `[5.0, 4.0]`

#### `vmap_min_axis`

```camel
vmap_min_axis: (xs: T[...], axis: int[], keepdims: bool[]) => T[...]
```

`min<axis, keepdims>(xs)` batched: each row's smallest element along the axis it was given.

- A native operator of this module: an opaque node, pure.
- Example: `vmap_min_axis([[1.0, 5.0], [3.0, 4.0]] as float[2, 2], [0], [false])` gives `[1.0, 3.0]`

### The positions along an axis

The axis `argmax` and the axis `argmin` are the reductions whose *result* element is not the
operand's:
they take any numeric tensor and answer `int` positions (the operator's own signature spells that
type `int64`). That is why their rules are the ones that show what a batching rule is generic in
-- the element the operands are made of, read from an operand, never from the type of the node the
result is (`modules/transforms/vmap.cpp`'s `firstOperandTypeOf`). A rule instantiated at the
result's element type would be a rule about `int` arrays applied to floats.

#### `vmap_argmax_axis`

```camel
vmap_argmax_axis: (xs: T[...], axis: int[], keepdims: bool[]) => int[...]
```

`argmax<axis, keepdims>(xs)` batched: each row's position of its largest element along the
axis it was given. The positions are `int` whatever the operand's element is, so the type this
function is generic in is the operand's (`T`), not its result's.
    // [1, 2]

- A native operator of this module: an opaque node, pure.
- Example: `vmap_argmax_axis([[1.0, 9.0, 3.0], [4.0, 5.0, 6.0]] as float[2, 3], [0], [false])`

#### `vmap_argmin_axis`

```camel
vmap_argmin_axis: (xs: T[...], axis: int[], keepdims: bool[]) => int[...]
```

`argmin<axis, keepdims>(xs)` batched: each row's position of its smallest element along the
axis it was given, with the earlier position on a tie.
    // [0, 0]

- A native operator of this module: an opaque node, pure.
- Example: `vmap_argmin_axis([[1.0, 9.0, 3.0], [4.0, 5.0, 6.0]] as float[2, 3], [0], [false])`

### The reductions over every axis

`sum(xs)` and `mean(xs)` take no axis at all, so there is none of the operator's to move one place
in. What they do to a batch is keep the batch axis in front and fold away the axes the row had
after it: a batch of rows arrives as one number per row, which is the shape the batch axis
already is. The fold is written over the value's own rank (`shape`), because the rank is a fact
about the value and not about the type -- `T[...]` says a tensor, never how many axes.

#### `vmap_sum`

```camel
vmap_sum: (xs: T[...]) => T[...] when is_numeric::<T>()
```

`sum(xs)` batched: one sum per row. The batch axis stays in front; each of the row's axes is
folded away in turn, so a batch of `float[3]` rows answers one number per row.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_sum([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]] as float[2, 3])` gives `[6.0, 15.0]`

#### `vmap_mean`

```camel
vmap_mean: (xs: T[...]) => T[...] when is_float::<T>()
```

`mean(xs)` batched: one mean per row, folded the same way `sum` is. A mean is of a float: an
integer row's mean is `f32`, which is not the element the rule would be written in.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_mean([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]] as float[2, 3])` gives `[2.0, 5.0]`

#### `vmap_max`

```camel
vmap_max: (xs: T[...]) => T[...] when is_numeric::<T>()
```

`max(xs)` batched: one maximum per row. The row's axes are flattened into one (`shape(xs)[0]`
is the batch extent, `-1` the rest) and the maximum is taken over that axis in one pass: IEEE
754-2019 maximum carries an element and is exactly associative and commutative (design
principles 7.7), so the axes of a row may be folded away in any order -- or in one pass over
the flattened row -- and the bits are the same: -0 below +0, a NaN anywhere beyond every
number, in either shape.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_max([[1.0, 5.0, 2.0], [4.0, 0.0, 3.0]] as float[2, 3])` gives `[5.0, 4.0]`

#### `vmap_min`

```camel
vmap_min: (xs: T[...]) => T[...] when is_numeric::<T>()
```

`min(xs)` batched: the same one-pass minimum over the flattened row, with the IEEE 754-2019
`minimum`. -0 is below +0 and a NaN is beyond every number, so the answer is the one the
whole-tensor form gives.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_min([[1.0, 5.0, 2.0], [4.0, 0.0, 3.0]] as float[2, 3])` gives `[1.0, 0.0]`

### The positions over every axis

`argmax(xs)` and `argmin(xs)` answer one position over the whole row, counted in row-major order,
and no fold of axis positions produces that number: folding a row's axes hands back a position per
axis (`argmax` of a `float[2, 3]` row is 5, not `[1, 2]`). What produces it is the shape the row's
own elements form as one line. `reshape<[shape(xs)[0], -1]>(xs)` is the batch read as
`[rows, -1]`, which lays the rows' elements end to end, so its *last* axis counts exactly one
row's elements and a position along it is the position over that row.

The shape `reshape` takes is written in angle brackets and may hold a value (`shape(xs)[0]`), not
only a constant: it is checked where the shape is known, so `-1` stands for the extent the value
itself states (design principles 5.4).

#### `vmap_argmax`

```camel
vmap_argmax: (xs: T[...]) => int[...] when is_numeric::<T>()
```

`argmax(xs)` batched: one row-major position per row, read as a reshape of the batch to
`[rows, -1]` and a reduction of its last axis -- which is one row's elements.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_argmax([[1.0, 9.0, 3.0], [4.0, 5.0, 6.0]] as float[2, 3])` gives `[1, 2]`

#### `vmap_argmin`

```camel
vmap_argmin: (xs: T[...]) => int[...] when is_numeric::<T>()
```

`argmin(xs)` batched: the same reading of the batch as `[rows, -1]`, with the earlier position on
a tie.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_argmin([[1.0, 9.0, 3.0], [4.0, 5.0, 6.0]] as float[2, 3])` gives `[0, 0]`

### Reshape

`reshape<dims>(x)` is the batching rule whose answer is a *shape*: a row's elements are already in
row-major order and a batch's rows are contiguous, so the batched reshape is the same elements
with the batch's axis written in front of the row's target.

The target is the operator's second argument, in `with` position (`OpDef::params` is `t` then
`shape`, `withAfterNorm`), and a `with` argument reaches a rule like any other: lifted to the batch
of one row. One row of a batch is contiguous, so its flat reading *is* the target's extents in
order -- that is the whole trick, and it is why the shape position takes a runtime value: the
written extents are a value, not something this rule's text could spell. `reshape<...>` takes an
`int[]` computed at runtime (it already takes `shape(xs)[0]` in the reductions above), so the
batched shape is `[the batch's rows, the written extents...]`.

#### `vmap_reshape`

```camel
vmap_reshape: (xs: T[...], dims: int[...]) => T[...] when is_numeric::<T>()
```

`reshape<dims>(xs)` batched: each row laid out in the shape the call wrote, the batch's axis in
front of it.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_reshape([[1.0, 2.0, 3.0, 4.0]] as float[1, 4], [2, 2])` gives `[[[1.0, 2.0], [3.0, 4.0]]]`

### Unsqueeze

`unsqueeze<axis>(x)` adds an axis of extent one *inside* the row, so the batch's axis is in front
of it: the written axis moves one place in, exactly as a reduction's axis does (`batched_axis`).

#### `vmap_unsqueeze`

```camel
vmap_unsqueeze: (xs: T[...], axis: int[]) => T[...] when is_numeric::<T>()
```

`unsqueeze<axis>(xs)` batched: the row's axis of extent one, one place further in.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_unsqueeze([[1.0, 2.0]] as float[1, 2], [0])` gives `[[[1.0, 2.0]]]`

### Transpose, permute, concat and dim

The rest of the layout tier whose axis or permutation is written in angle brackets: each is a
`with` argument, so each arrives as the batch of one row and the rule shifts it the same way a
reduction's axis is shifted. `transpose` writes no axis at all -- the operator swaps the last two
axes of whatever it is given, and a batch's last two axes are the row's -- so its rule is the
operator over the batch and nothing else.

#### `vmap_transpose`

```camel
vmap_transpose: (xs: T[...]) => T[...] when is_numeric::<T>()
```

`transpose(xs)` batched: the operator swaps the last two axes, and a batch's last two axes are the
row's last two.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_transpose([[[1.0, 2.0], [3.0, 4.0]]] as float[1, 2, 2])` gives `[[[1.0, 3.0], [2.0, 4.0]]]`

#### `vmap_permute`

```camel
vmap_permute: (xs: T[...], perm: int[...]) => T[...] when is_numeric::<T>()
```

`permute<perm>(xs)` batched: the row's axes in the written order, the batch's axis in front.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_permute([[[1.0, 2.0], [3.0, 4.0]]] as float[1, 2, 2], [1, 0])` gives `[[[1.0, 3.0], [2.0, 4.0]]]`

#### `vmap_concat`

```camel
vmap_concat: (a: T[...], b: T[...], axis: int[]) => T[...] when is_numeric::<T>()
```

`concat<axis>(xs, ys)` batched: the axis the row joins along is one place further in, and the two
operands are the batch's rows, so the join is along the row's axis of the batch.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_concat([[1.0]] as float[1, 1], [[2.0]] as float[1, 1], [0])` gives `[[[1.0], [2.0]]]`

#### `vmap_dim`

```camel
vmap_dim: (xs: T[...], axis: int[]) => int[] when is_numeric::<T>()
```

`dim<axis>(xs)` batched: one extent per row, each being the batch's extent one place further in.
The answer of a batched `dim` is a *batch of extents* (an `int[]`), not one `int`: every row has
the same extent, because the batch's axis adds nothing to the row's.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_dim([[[1.0, 2.0], [3.0, 4.0]]] as float[1, 2, 2], [1])` gives `[2]`

### Where

`where(cond, a, b)` is elementwise on three arrays of the row's shape, and the condition is one of
them: the batch's axis is in front of all three, and a condition that is a constant of the row's
shape is lifted to a batch of one row, which broadcasts against the batch. The rule is the
operator over the batch, and it is instantiated on the element of the *arms* -- a condition is a
`bool` and the answer is the arms' element, so the transform reads the first port that is not a
condition to name the rule's `T`.

#### `vmap_where`

```camel
vmap_where: (cond: bool[...], a: T[...], b: T[...]) => T[...] when is_numeric::<T>()
```

`where(cond, a, b)` batched: the operator over the batch, all three operands one axis in front.

- Written in Camel: a subgraph, pure when the functions passed to it are.
- Example: `vmap_where([[true, false, true]] as bool[1, 3], [[1.0, 2.0, 3.0]] as float[1, 3], [[4.0, 5.0, 6.0]] as float[1, 3])` gives `[[1.0, 5.0, 3.0]]`

<a id="sim"></a>

## `sim`: Monte Carlo simulation

Monte Carlo simulation: two kernels that estimate a number from random samples. `pi_hits`
estimates pi from the fraction of points that fall inside the unit circle and
`asian_call_price` prices a one-year Asian call by simulating the underlying's paths. Both
take the sample count and the seed, so a seed reproduces the result exactly and the operators
are pure.

#### `pi_hits`

```camel
pi_hits: (samples: int, seed: int) => int
```

Draws `samples` points uniformly from the square [-1, 1]^2 with a generator seeded by `seed`
and returns how many fall inside the unit circle. The estimate of pi is `4 * hits / samples`;
a negative sample count is a fault.

- Pure.
- Failure: fault `RuntimeError` when `samples` is negative.
- Example: `pi_hits(10000, 42)` gives `7863`

#### `asian_call_price`

```camel
asian_call_price: (paths: int, steps: int, seed: int) => float
```

Prices a one-year Asian call on a geometric random walk with `paths` simulated paths of
`steps` steps each, using the fixed parameters S0 = 100, K = 100, r = 0.05 and sigma = 0.2,
and a generator seeded by `seed`; the result is the discounted average payoff. A negative
path count or a non-positive step count is a fault.

- Pure.
- Failure: fault `RuntimeError` when `paths` is negative or `steps` is not positive.
- Example: `asian_call_price(2000, 128, 42)` gives `5.894325529519635`

<a id="onnx"></a>

## `onnx`: export a program as an ONNX model

Exporting Camel programs as ONNX models: `export_model` writes the model of a function applied
to an example argument, and `supported_operators` lists the operator URIs the backend can
lower. The module is the ONNX exporter, not a runtime: loading it and asking what it can lower
needs neither the ONNX runtime nor a GPU; only a run of `export_model` writes a file.

#### `supported_operators`

```camel
supported_operators: () => string[]
```

Lists the operator URIs the ONNX backend can lower at its default opset, in the order the
lowering table reports them. A capability report only: it reads the table compiled into the
module and never touches the file system or the ONNX runtime.

- Pure.
- Example: `let uris = supported_operators()`

#### `export_model`

```camel
export_model: <out: string, dynamic_axes: int[] = [], target: string = 'onnxruntime-cpu'> (fn: F, example: E) => void! when is_function::<F>()
```

Writes the ONNX model of `fn` applied to arguments like `example` to the file `out`, at the
backend's default opset. `example` is one argument of a one-parameter `fn`, or a tuple with
one example per parameter; the function's graph is translated after the generic passes, and a
node the backend cannot lower is refused. `out`, `dynamic_axes` and `target` are `with`
parameters because they are runtime values: `dynamic_axes` names the axes of the tensor inputs
that are left unknown in the model (which is what lets one model run at several shapes), and
`target` names the runtime whose capability data decides whether a node this backend lowers is
one that runtime has (`'none'` switches the check off).

- With effects: writes a file and reads the function's graph.
- Failure: error value `ExportUnsupported` when `fn` is not a function, when the graph cannot be translated (a call that remains, an operator without an ONNX lowering, a dtype or shape the exporter cannot name), or when the target runtime rejects a node; error value `IOError` when the model cannot be written.
- Example: `export_model<out: "/tmp/model.onnx">((x: float) => x * 2.0, 2.0)`
- Example: `export_model<out: "/tmp/model.onnx", dynamic_axes: [0]>((xs: f32[2, 3]) => xs[0][0], [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]] as f32[2, 3])`
- Example: `export_model<out: "/tmp/model.onnx", target: "onnxruntime-cpu">((x: float) => x * 2.0, 2.0)`