# ilo Language Spec
ilo is a token-optimised programming language for AI agents. Every design choice is evaluated against total token cost: generation + retries + context loading.
---
## File version pragma
Optional.
```
^26.5
-- rest of file
```
Top-of-file declaration of the minimum required runtime. First line, no leading whitespace. Sigil-led (principle 4), ~3 tokens (principle 1). First-class syntax, not a magic comment - the lexer recognises `^<YY.M>` only at file start, so `^` elsewhere keeps its `return err` meaning.
| Case | Verifier |
|----------------------------------------------------------|-------------------------------------|
| Pragma absent | Assume latest installed runtime, no diagnostic |
| File targets older than runtime, breaking change between | Fail with migration pointer |
| File targets newer than runtime | Fail asking to upgrade |
Tooling: `ilo --version-of <file>` reads the pragma (returns nothing when absent); the formatter canonicalises position when present, never inserts one. Ships with the CalVer cut; 0.x files have no pragma and verify silently.
---
## Functions
```
<name> <param>:<type> ...><return-type>;<body>
```
- No parens around params - `>` separates params from return type
- `;` separates statements - no newlines required
- Last expression is the return value (no `return` keyword)
- Zero-arg call: `make-id()`
- Paren-form call (ILO-51): `spl(row, ",")` is sugar for `spl row ","` — same AST, postfix is canonical
- Labelled args (ILO-71): `dtfmt epoch:e fmt:"%Y"` — optional `label:value` form for any callable with declared parameter names. Labels resolve to positional by name; order is free. Mixed positional + labelled is allowed (positional fill from left; labels fill remaining slots by name). Unknown or duplicate labels surface `ILO-P019` at parse time. Works in both postfix and paren form: `f(b:2, a:1)` ≡ `f a:1 b:2`.
**Two body forms — both fully supported:**
```
-- Inline: semicolons separate statements; last expression returns.
add-and-double x:n y:n>n;s=+x y;*s 2
-- Brace-block, single-line: explicit braces wrap the whole body (same semantics).
add-and-double x:n y:n>n { s = +x y; *s 2 }
-- Brace-block, multi-line: newlines inside `{ ... }` act as statement separators
-- (same as `;`). The brace form may be inline or multi-line interchangeably.
add-and-double x:n y:n>n {
s = +x y
*s 2
}
```
Multi-step transforms bind intermediate results as locals:
```
tot p:n q:n r:n>n;s=*p q;t=*s r;+s t
```
Early return: braceless guard (`>=x 0 val` exits the function immediately when true); `ret val` exits from any depth including inside a loop or braced conditional.
Result unwrap mid-body: `v=call!` extracts the Ok value and propagates Err out of the function before continuing.
---
## Types
| Syntax | Meaning |
|--------|---------|
| `n` | number (f64) |
| `t` | text (string) |
| `b` | bool |
| `_` | any/unknown (wildcard type) |
| `L n` | list of number |
| `R n t` | result: ok=number, err=text |
| `O n` | optional number (nil or n) |
| `M t n` | map from text keys to numbers |
| `S red green blue` | sum type - one of named text variants |
| `F n t` | function type: takes n, returns t (used in HOF params) |
| `W` | capability World token — `w:W` declares a capability parameter (ILO-68) |
| `order` | named type |
| `a` | type variable - any single lowercase letter except n, t, b |
### Optional (`O T`)
`O T` accepts either `nil` or a value of type `T`.
```
f x:O n>n;??x 0 -- unwrap optional or default to 0
g>O n;nil -- returns nil (valid O n)
h>O n;42 -- returns 42 (valid O n)
```
`??x default` - nil-coalesce: returns `x` if non-nil, else `default`. Unwraps `O T` to `T`.
### Sum types (`S a b c`)
Closed set of named text variants. Verifier-enforced; runtime value is always `t`.
```
color x:S red green blue > t
?x{red:"ff0000";green:"00ff00";blue:"0000ff"}
```
Sum types are compatible with `t` - a sum value can be passed to any `t` parameter.
### Discriminated union types (`type Foo = A | B(n) | C(t)`)
Named sum types with optional per-variant payloads (Rust-style enums). Each variant is either payload-less or carries exactly one value of a primitive type.
```
type shape = circle(n) | square(n) | point
area s:shape > n
?s{circle(r):*3.14159 *r r;square(side):*side side;point:0}
```
- **Declaration**: `type Name = V1 | V2(payloadType) | ...` at top level.
- **Construction**: `circle 5` (payload variant), `point` (payload-less variant used as value directly).
- **Pattern match**: `?s{circle(r):...; square(side):...; point:...}` using `tag(binding):` or `tag:` arms.
- **Exhaustiveness**: verifier (ILO-T024) checks all variants are covered; the error lists every missing variant by name and suggests the correct arm syntax (`tag(v): <expr>` for payload variants, `tag: <expr>` for payload-less). A wildcard `_:` arm satisfies exhaustiveness. Missing multiple variants produces a single diagnostic naming all of them.
- **VM**: programs using discriminated unions fall back to the tree interpreter (JIT codegen deferred).
### Generic discriminated union types (`type Result<a,b> = ok(a) | err(b)`)
Sum type declarations accept type parameters (ILO-402), enabling reusable polymorphic variants.
```
type result<a,b> = ok(a) | err(b)
type option<a> = some(a) | none
type either<a,b> = left(a) | right(b)
```
- **Syntax**: `type Name<a b>` or `type Name<a,b>` — one or more single-letter type variables (commas optional).
- **Type variables**: declared letters (including `n`, `t`, `b`) are treated as type variables in variant payloads, not as primitives.
- **Erasure**: type variables are erased at runtime — no boxing or specialisation. The verifier accepts any concrete type for a type-variable payload.
- **Usage**: construct and match exactly like non-generic sum types; the concrete type is inferred from context.
```
safe-div x:n y:n>result
=(y) 0{ret err "division by zero"}
ok /x y
main>t
dv=safe-div 10 2
?dv{ok(v):str v;err(msg):msg} -- "5"
```
### Map type (`M k v`)
Dynamic key-value collection. Keys are typed: text (`t`) or integer (`n`). `Int(1)` and `Text("1")` are distinct keys.
```
mmap -- empty map
mset m k v -- return new map with key k set to v
mget m k -- value at key k, or nil
mget-or m k default -- value at key k, or default if missing (never nil)
mhas m k -- b: true if key exists
mkeys m -- L t: sorted list of keys
mvals m -- L v: values sorted by key
mpairs m -- L (L _): sorted [k, v] pairs; mpairs m == zip (mkeys m) (mvals m)
mdel m k -- return new map with key k removed
len m -- number of entries
```
Numeric keys work directly - no `str` conversion needed. Float keys floor to `i64` at the builtin boundary (matching `at xs i`); NaN/Infinity raise at runtime.
```
idx=mmap
idx=mset idx 7 "seven" -- M n t, integer key
mget idx 7 -- "seven"
mhas idx 7 -- true
mhas idx "7" -- false (Int and Text are distinct)
```
`jdmp` stringifies numeric keys for JSON output (JSON object keys are always strings). The round-trip via `jpar` is lossy - numeric keys come back as text.
Example:
```
scores>M t n
m=mmap
m=mset m "alice" 99
m=mset m "bob" 87
mget m "alice" -- 99
```
### Type variables
A single lowercase letter (other than `n`, `t`, `b`) in type position is a type variable. Used for higher-order function signatures:
```
identity x:a>a;x
apply f:F a a x:a>a;f x
```
**Without a bound declaration** type variables are treated as `unknown` during verification — the verifier accepts any type for `a` without consistency checking across call sites (legacy behaviour; backward compatible).
### Bounded generics
Explicit generic type parameters allow the verifier to enforce two properties at call sites:
1. All arguments bound to the same type variable have the same concrete type.
2. The concrete type satisfies the declared bound.
**Syntax:** `name<a:bound b:bound ...>` before the parameter list. Bounds are optional per variable; omitting `:bound` defaults to `any`.
```
gmn<a:comparable> x:a y:a>a -- min of two comparable values
gadd<a:numeric> x:a y:a>a -- addition, numeric values only
grep<a:text> s:a n:n>t -- repeat text
gid<a> x:a>a -- identity, any type
```
**Bound set** (small and fixed):
| Bound | Permitted concrete types |
|--------------|---------------------------------------|
| `any` | any type (default when bound omitted) |
| `comparable` | `n`, `t`, `b` |
| `numeric` | `n` |
| `text` | `t` |
**Call-site checking:**
```
gmn 3 7 -- ok: both n
gmn "a" "b" -- ok: both t
gmn 1 "two" -- ILO-T044: 'a' bound to n then t (inconsistent)
gadd "x" "y" -- ILO-T044: 't' does not satisfy numeric bound
```
Unbounded legacy type-variable usage (`identity x:a>a;x`) continues to work without changes.
### Inline lambdas
Pass a function literal directly to a HOF instead of defining a one-off top-level helper:
```
by-dist xs:L n>L n;srt (x:n>n;abs x) xs
nonempty ws:L t>L t;flt (s:t>b;>(len s) 0) ws
sumsq xs:L n>n;fld (a:n x:n>n;+a *x x) xs 0
```
Syntax: `(<param>:<type> ...><return-type>;<body>)`. Same shape as a top-level function declaration, wrapped in parens, no name.
**Brace-lambda shorthand** (`{params> stmts}`): bare param names (types inferred as `any`) and no explicit return type. Useful for compact multi-statement bodies in `map`/`flt`/`fld`:
```
sumsq xs:L n>n;fld {a x>; tmp=*x x; +a tmp} xs 0
dbl xs:L n>L n;map {x> *x 2} xs
pos xs:L n>L n;flt {x> >x 0} xs
```
The `;` after `>` is optional. The body supports the same `;`-chained statement forms as the paren lambda and top-level function bodies (let-bindings, guards, match, loops, `ret`/`brk`/`cnt`). Closure capture also works — any name that isn't a param or body-local is snapshot from the enclosing scope.
**Phase 1 (no captures)** lifts the literal to a synthetic top-level decl and works across every engine (tree, VM, Cranelift JIT, AOT). The body's free variables must all be params, locals defined inside the lambda body, or known top-level fns.
**Phase 2 (closure capture)** lets the body reference variables from the enclosing scope:
```
f xs:L n thr:n>L n;flt (x:n>b;>x thr) xs -- captures `thr` (paren form)
f xs:L n thr:n>L n;flt {x> >x thr} xs -- captures `thr` (brace form)
```
**Builtins are not first-class values.** Builtin names (`sha256`, `hmac-sha256`, `b64`, etc. — every name in the builtin table) are call-only: they can appear in call position but cannot be passed by name to a HOF. `map sha256 xs` fails ILO-T004 ("undefined variable 'sha256'") with a hint pointing to the canonical wrap-as-lambda rewrite. Wrap the builtin in an inline lambda instead:
```
hashes xs:L t>L t;map (x:t>t;sha256 x) xs -- paren form
hashes xs:L t>L t;map {x> sha256 x} xs -- brace form
```
A handful of arithmetic/string builtins (`abs`, `min`, `max`, `mod`, `sum`, `prod`, `len`, `upr`, `lwr`, `trm`, `cap`, `padl`, `padr`, `ord`, `chr`, `chars`, `str`, `num`, `jdmp`, `fmod`, `flr`, `cel`, `rou`, `avg`, `median`, `stdev`, `variance`) are promoted to `Ty::Fn` at the verifier so they *can* be passed directly (see `builtins-as-hof.ilo`); everything else needs the lambda wrap.
Phase 2 captures run natively on every engine: the tree interpreter, the register VM, the Cranelift JIT, and the Cranelift AOT backend. Each free variable is snapshot by value at the call site (`Expr::MakeClosure`) and appended to the call frame's arg slice on dispatch. The AOT backend additionally embeds the postcard-serialised `CompiledProgram` into the binary's `.rodata` and publishes TLS pointers on startup, so dispatch helpers can re-enter the VM on user-fn callbacks. The ctx-arg form (`srt fn ctx xs`) remains the cross-engine alternative when you want explicit state without forming a closure.
**Braceless guards are rejected inside lambda bodies (`ILO-P023`).** A braceless guard at statement position (`>=x 0 val`, `=x 0 val`, etc.) early-returns from the *enclosing function*, not from the lambda — see "Early Return" below. Inside a lambda body that semantics is almost never what the author meant; the lambda body would silently skip past the guard and the outer caller would return out from under the higher-order call. The parser therefore rejects braceless guards inside lambda bodies and asks for one of two expression-shaped rewrites:
- **Prefix ternary** when both arms are values: `map (x:n>n;?>=x 0 0 x) xs`
- **Braced match** when arms need statements: `map (x:n>n;?>=x 0{0}{x}) xs`
Braceless guards at top-level function bodies continue to work — this restriction is lambda-body only. A future runtime change (follow-up to ILO-473) may switch the early-return target inside lambdas; until then the diagnostic prevents the silent miscompile.
**Rejected lambda shapes (ILO-456).** Only the paren form `(x:t>r;body)` and the bare-param brace form `{x> body}` are accepted. Three shapes from other functional languages look plausible but are deliberately rejected — each emits a targeted hint naming both canonical forms and the call-site rewrite:
| Shape (rejected) | Use instead |
| ----------------------------- | ------------------------------------------------------ |
| `flt {x:t> body} xs` | `flt (x:t>r;body) xs` (paren is the typed form) |
| `flt \x:t>body xs` | `flt (x:t>r;body) xs` or `flt {x> body} xs` |
| `flt fn x:t>r;body xs` | `flt (x:t>r;body) xs` or `flt {x> body} xs` |
The brace form is the *bare-param* shorthand — its params are inferred as `any`, so `{x:n> body}` is a category error rather than a typed-brace lambda.
---
### Trailing-semicolon semantics
`;` is the **statement separator** in ilo. A trailing `;` — one that appears after the last statement with nothing following it before the next structural boundary — is **always silently consumed** (ignored). It is never required, never an error, and never changes the meaning of the body. This applies uniformly across all three body contexts:
| Context | Header/body separator | Trailing `;` handling |
|---------|----------------------|----------------------|
| Top-level function declaration | `name params>return;body` — the `;` after the return type separates the header from the body; it is **optional** when a newline is present | A trailing `;` after the last statement is consumed and ignored |
| Inline lambda | `(params>return;body)` — the `;` after the return type separates the header from the body; it is **optional** | A trailing `;` before the closing `)` is consumed and ignored |
| Match / guard arm body | `arm:body;` — `;` terminates an arm and starts the next; a trailing `;` before `}` is consumed and ignored | Consumed silently; arm body is parsed as-is |
The parser calls `parse_body_with` (for function bodies) and `parse_lambda_body` (for inline-lambda bodies). After consuming each `;` separator between statements, if the next token is at a body-end boundary (`EOF`, `}`, `)`, or the start of a new sibling function declaration) the loop breaks without error. No statement is emitted for the trailing `;`.
**Practical rules:**
- `f>n;42` and `f>n;42;` are identical — both parse to a single-statement body returning `42`.
- `(x:n>n;+x 1)` and `(x:n>n;+x 1;)` are identical inline lambdas.
- `?x{a:1;b:2;}` and `?x{a:1;b:2}` parse identically — the trailing `;` before `}` is silently dropped.
- A `;` at the very start of a body (before any statement) is **not** a trailing semicolon — it is a missing-statement parse error (`ILO-P001`/`ILO-P003`). Only a `;` after a valid statement is silently consumed.
- The header/body separator `;` in `name params>return;body` is similarly optional when the token stream contains a newline at that boundary (the lexer converts indented newlines to `;`). The parser checks `peek() == Semi` and advances past it if present.
- fn declarations are **top-level only**; for a one-off helper that needs a local, use an inline lambda. A `name params>type;body` shape inside another function's body is rejected with `ILO-P024` (ILO-460); the closure-capture variant is tracked separately.
---
## Naming
Short names everywhere. 1–3 chars.
| Long | Short | Rule |
|------|-------|------|
| `order` | `ord` | truncate |
| `customers` | `cs` | consonants |
| `data` | `d` | single letter |
| `level` | `lv` | drop vowels |
| `discount` | `dc` | initials |
| `final` | `fin` | first 3 |
| `items` | `its` | first 3 |
Function names follow the same rules. Field names in constructors and external tool names keep their full form - they define the public interface.
### Identifier syntax
Identifiers are lowercase ASCII only, optionally with hyphenated segments. Formally: `[a-z][a-z0-9]*(-[a-z0-9]+)*`. Capital letters and underscores are rejected at the binding and call site.
```
run -- OK
run-d -- OK (hyphen separates segments)
r2 -- OK (digit after first letter)
runD -- ERROR (capital letter)
RunD -- ERROR (leading capital)
run_d -- ERROR (underscore not allowed in bindings)
-run -- ERROR (must start with a letter)
```
`runD` in the interactive CLI surfaces as `ILO-L003 unexpected token` with a suggestion to use `run-d` or `rund`. The constraint is intentional: a single lexical shape per identifier keeps the token stream predictable for agents and avoids style debates over camelCase vs snake_case vs kebab-case.
**Hyphen vs subtraction.** A hyphen with no surrounding whitespace is always part of an identifier — `best-d` is one token, never `best - d`. Subtraction requires whitespace on at least the operator side: `- best d` (prefix form) or `best - d` (infix form). When an unbound kebab ident has every segment bound, `ILO-T004` adds a hint pointing at the prefix form. When an unbound kebab ident splits uniquely into two bound names (e.g. `zr-sq-zi-sq` → `zr-sq` and `zi-sq`), the hint shows both the prefix form (`- zr-sq zi-sq`) and the infix-with-spaces form (`zr-sq - zi-sq`).
The only place capital letters and underscores are accepted is **after `.` or `.?`** at field-access position, so heterogeneous JSON keys from real APIs work without rewriting. See [Field names at dot-access](#field-names-at-dot-access) for the full list of post-dot relaxations (`r.URL`, `r.AccessKey`, `r.user_name`, etc.). Binding names (`AccessKey = ...`) and function names (`AccessKey x:n>n;...`) still error.
### Reserved words
The following identifiers are reserved and cannot be used as names: `if`, `return`, `let`, `fn`, `def`, `var`, `const`. Using them produces a friendly error with the ilo equivalent:
```
-- ERROR: `if` is a reserved word. Use: ?cond{true:...;false:...}
-- ERROR: `return` is a reserved word. Last expression is the return value.
-- ERROR: `let` is a reserved word. Use: name = expr
-- ERROR: `fn`/`def` is a reserved word. Use: name param:type > rettype; body
```
These checks fire at parse time across every context the keyword can appear in: top-level declaration head (`fn>n;...`), binding LHS (`fn=5`), and **parameter position** (`g fn:n>n;fn` rejects with ILO-P011 against the param name, not a cryptic ILO-P003 against the missing `>`).
Builtin names (`flat`, `frq`, `map`, `flt`, `cat`, `len`, `srt`, `hd`, `tl`, `ord`, `fld`, `lst`, ...) are also rejected as user-function names and as local-binding LHS. Without this, calls to the user fn or use sites of the local binding silently mis-dispatch to the builtin and surface as a confusing `ILO-T006` arity mismatch. The parser intercepts at the declaration site with ILO-P011 and a rename hint:
```
flat n:n>n;n
-- ERROR ILO-P011: `flat` is a builtin and cannot be used as a function name
-- hint: rename to something like `myflat` or `flatof`.
main>n;flat=cat xs " ";spl flat ". "
-- ERROR ILO-P011: `flat` is a builtin and cannot be used as a binding name
-- hint: rename to something like `myflat` or `flatv`.
```
### Reserved namespaces
Short builtin names are precious surface and ilo reserves a stable subset of them. To save agents (and their carry-forward scripts) from "what got reserved this release?" debugging cycles, the language publishes the full short-name reserve list plus a forward-compatibility rule for future builtins.
**Type-sigil letters are not reserved as identifiers.** The primitive type letters `n` (number), `t` (text), `b` (bool) — and the compound sigils `L`, `R`, `O`, `M`, `S`, `F` — are *position*-scoped. They are recognised as types only after `:` in a parameter binding or after `>` in a return-type annotation. Everywhere else (binding LHS, expression operand, fn name) they are normal lowercase identifiers. `t = 5` binds a local `t`; the canonical first example `tot p:n q:n r:n>n;s=*p q;t=*s r;+s t` uses `t` as a scratch local. Agents are free to use `n`, `t`, `b` as variables. Capital letters remain rejected as user identifiers (the rule `[a-z][a-z0-9]*(-[a-z0-9]+)*` is the source of truth). See [ILO-478](https://linear.app/ilo-lang/issue/ILO-478) for the in-flight migration that makes the primitive sigils uppercase (`N`/`T`/`B`) and removes this positional caveat.
**Currently reserved short names (1-3 characters).** Every name in this list is a builtin today and triggers `ILO-P011` if used as a binding or user-function name:
```
1-char e
2-char at hd pi tl rd wr ct
3-char abs avg b64 bor cap cat cel chr cos del det dot env ewm exp fft fld flr
flt fmt frq get grp has hed hex inv len log lsd lst lwr map max min
mod now num opt ord pat pow pst put rdb rdl rep rev rgx rng rnd rou
run sin slc spl srt str sum tan tau trm unq upr wra wrl wro zip
```
All builtin aliases (`head`, `length`, `filter`, `concat`, `tail`, `sort`, `reverse`, `flatten`, `contains`, `group`, `average`, `print`, `trim`, `split`, `format`, `regex`, `read`, `readlines`, `readbuf`, `write`, `writelines`, `lset`, `floor`, `ceil`, `round`, `rand`, `random`, `rng`, `string`, `number`, `slice`, `unique`, `fold`) are reserved with the same shadow-prevention semantics as canonical builtin names. Binding an alias name or using it as a user-function name fires `ILO-P011` at parse time with the canonical form in the diagnostic, since the call-site rewrite to the canonical builtin silently bypasses any user binding of the same name. Previously only `rng` and `rand` had individual guards; as of 0.12.1 every alias in the table above is covered by a single `resolve_alias` check, so new aliases automatically inherit the protection when added to the table.
Longer builtin names (`acos`, `asin`, `atan`, `flat`, `take`, `drop`, `mget`, `mset`, `mmap`, `prnt`, `mapr`, `solve`, `lstsq`, `clamp`, `cumsum`, `cprod`, `median`, `matmul`, `range`, `window`, `chunks`, `walk`, `glob`, `prod`, `fsize`, `mtime`, `isfile`, `isdir`, `band`, `bxor`, `bnot`, `bshl`, `bshr`, `brot`, …) are also reserved and rejected by `ILO-P011`, but the short-name namespace above is where carry-forward scripts most often collide, so it gets explicit enumeration.
Longer builtin names (`acos`, `asin`, `atan`, `flat`, `take`, `drop`, `mget`, `mset`, `mmap`, `prnt`, `mapr`, `solve`, `clamp`, `cumsum`, `cprod`, `median`, `matmul`, `range`, `window`, `chunks`, `walk`, `glob`, `prod`, `fsize`, `mtime`, `isfile`, `isdir`, `ones`, `linspace`, …) are also reserved and rejected by `ILO-P011`, but the short-name namespace above is where carry-forward scripts most often collide, so it gets explicit enumeration.
**Forward-compatibility rule.** Future ilo releases add new builtins under names **4 characters or longer**. A 2-character name that is not on this list today is safe to use as a binding or function name and stays safe across releases. A 3-character name that is not on this list is _highly likely_ to stay safe but is not a hard promise - the 3-char surface is already dense, and a rare ergonomic win may justify an addition, called out in the changelog.
This gives agents a deterministic safe-name strategy:
- **2 chars**: any unreserved 2-char name is permanently fine for bindings (`ce` for "category", `ix` for index, `mn` for "mean", `pq` for "priority queue", …). Names on the reserved list above never get removed.
- **3 chars**: prefer unreserved 3-char names where possible. If a future release reserves one, the migration is a 1-character rename plus a changelog entry.
- **4+ chars**: always safe. New builtins land here first; any short alias is added later only if the long name is unambiguous and the short doesn't shadow a plausible user binding.
When a collision does happen, `ILO-P011` surfaces it at the binding site with a rename suggestion - never silently mis-dispatches at the call site (see the `flat=cat xs " "` example above). Combined with the reserve list, that turns every name-collision incident into a single-character rename instead of a debugging spiral.
### Cross-language gotchas
Common shapes reached for from other languages. The parser and lexer surface each with a friendly hint:
| Mistake | Canonical ilo form | Error code |
| -------------------------------- | ---------------------------------------- | ----------- |
| `AND a b`, `OR a b`, `NOT a` | `&a b`, `\|a b`, `!a` | `ILO-L001` |
| `=<a b`, `=>a b` | `<=a b`, `>=a b` (single token) | `ILO-P003` |
| `f=fn x:n>n;+x 1` (lambda) | `(x:n>n;+x 1)` (parenthesised lambda) | `ILO-P009` |
| `\x{+x 1}` (Haskell/Rust lambda) | `(x:n>n;+x 1)` (parenthesised lambda) | `ILO-L001` |
| `flt {x:t> body} xs` (typed-brace at HOF) | `flt (x:t>r;body) xs` (paren = typed; brace = bare params) | `ILO-P001` |
| `flt \x:t>body xs` (typed backslash) | `flt (x:t>r;body) xs` or `flt {x> body} xs` | `ILO-L001` |
| `flt fn x:t>r;body xs` (`fn`-keyword inline) | `flt (x:t>r;body) xs` or `flt {x> body} xs` | `ILO-P009` |
| `main:>n;body` | `main>n;body` (no `:` before `>`) | `ILO-P003` |
| Multi-line body without braces | `@k xs{body}`, `cond{body}` on one line | `ILO-P003` |
| `cond{^"err"}` braced-cond | Braceless `cond ^"err"` for early return | hint only |
| `- -*a b *c d` (double-minus) | `- 0 +*a b *c d` (negate the sum) | `ILO-P021` |
| `[k fmt2 v 2]` (call in list) | `[k (fmt2 v 2)]` or bind-first | `ILO-P101` |
| `[login "a" logout "b"]` (variant ctor in list) | `[(login "a") (logout "b")]` or bind-first | `ILO-T047` |
| `pts=gen-pts;cs0=[...];prnt cs0` at top level | `main>_;pts=gen-pts;cs0=[...];prnt cs0` (wrap in `main>_;`) | `ILO-P102` |
| `((((...((1+1))))...))` 1000 deep | bind intermediates, or pass `--max-ast-depth N` | `ILO-P103` |
| `dx=xj 0-xi` (call vs binop) | `-xj xi` or pre-bind: `nxi=0-xi;+xj nxi` | `ILO-T005` |
| `wc==q ""` (no space, binding+equality) | `wc = =q ""` (single `=` to bind, then prefix `=a b` for equality) | `ILO-T005` |
| `tup.0` / `pair.0` (tuple access) | bind from `zip`-pair, then `at pair 0` (no tuple type) | `ILO-T004` |
| `?? (num s) 0` (`??` on `R T E`) | `default-on-err (num s) 0` or `?(num s){~v:v;^_:0}` | `ILO-T041` |
| `?bool{body}` (bool-conditional) | guard `=bool true body`, braced `=bool true{body}`, ternary `?bool a b`, or match `?bool{true:a; false:b}` | `ILO-P011` |
| `(x:n>n;>=x 0 0;x)` (braceless guard inside lambda) | `(x:n>n;?>=x 0 0 x)` (prefix ternary) or `(x:n>n;?>=x 0{0}{x})` (braced match) | `ILO-P023` |
| `+a+" "+b+c` (infix-style chain with leading prefix `+`) | drop the leading `+`: `a+" "+b+c`; or `fmt "{} {} {}" a b c`; or nested prefix `+a +" " +b c`; or bind intermediates | `ILO-P010` |
| `fmt "{}" +0.1 0.2` -> `0.30000000000000004` (float Display = full IEEE 754) | `fmt "{:.2f}" (+0.1 0.2)` for human-readable; `fmt2 v N` for precise dp | docs only |
| `*/ sz 0.3 0` ("scale then div by 0") | `*/a b c` is `(a/b)*c` — b is the divisor; for `(a*b)/c` use `/*sz 0.3 0` or bind `r=*sz 0.3;/r 0` | hint only |
| `?h <bool-ref> a b` (keyword form on bare ref) | `?<bool-ref> a b` (bare-bool prefix ternary) | `ILO-W003` |
| `pred q:t>b;=q "" 1;false` (guard tail literal) | `=q "" true;false` (tail value must match declared return type) | `ILO-T008` |
| Nested `helper x:n>n;body` inside another function body | inline lambda `helper=(x:n>n;body)` (captures locals), or lift to top-level and thread the local as an explicit param | `ILO-P023` |
| Nested `helper x:n>n;body` inside another function body | inline lambda `helper=(x:n>n;body)` (captures locals), or lift to top-level and thread the local as an explicit param | `ILO-P024` |
Each case fires a hint pointing at the canonical form; the agent's first retry should be the right one. Identifier-shaped collisions with builtin names (`len=...`, `sin=...`) are rejected with `ILO-P011` plus a rename suggestion.
The list-literal call trap (`ILO-P101`) catches the case where a variadic builtin (`fmt`, `fmt2`) appears bare inside `[...]`. Fixed-arity builtins (`str`, `at`, `map`, ...) auto-expand to a call as one element, but variadic ones can't (the parser doesn't know where their args end), so the bare form would silently fall through as multiple elements with the builtin name as an undefined Ref. Fix by wrapping the call in parens (`[k (fmt2 v 2)]`) or binding first.
The top-level chain trap (`ILO-P102`) catches a bare `name=expr` at the top level. ilo requires every binding to live inside a function body; a top-level `pts=gen-pts;cs0=[[...]]; ...; prnt cs2` without a `main>_;` (or any) header used to either die on the `=` (a bare `ILO-P003`) or get slurped into a previous function's body and emit a wall of misleading `ILO-T005` cascades on the wrong line. `ILO-P102` collapses both shapes into a single diagnostic that names the offending binding and suggests the canonical `main>_;` wrapper.
The double-minus trap (`ILO-P021`) catches the silent-miscompile shape `- -<op> a b <op> c d` for `<op>` in `{+,*,/}`. Read intuitively as `-(a*b) - (c*d)` but parses as `-((a*b) - (c*d)) = -(a*b) + (c*d)` because the inner `-` greedily consumes both prefix-binop groups as binary subtract and the outer `-` falls back to unary negate. Fix by negating the sum (`- 0 +*a b *c d`) or binding first (`p=*a b;q=*c d;- 0 +p q`). Single-atom variants like `- -a b` remain accepted since they're unambiguous.
The glued-`==` binding trap (`ILO-T005` with the ILO-469 hint) catches `name==expr` written without a space. Both `=` and `==` lex as a single `Token::Eq`, so `wc==q ""` parses as the binding `wc = (q "")` — a call on `q` — and the verifier fails because `q` isn't a function. The hint names the missing space and shows the canonical rewrite `wc = =q ""` (single `=` for the binding, then prefix `=a b` for equality). ilo does not fuse `==` into a single bind-then-equality token; the diagnostic is a nudge, not a syntactic concession.
The call-vs-binop trap (`ILO-T005` with tailored hint) catches the assignment-RHS shape `name expr` where `name` is a bound non-fn value (typically a parameter). Whitespace-juxtaposition is the call syntax in ilo, so `dx=xj 0-xi` parses as `dx=(xj 0)-xi` — a call to `xj` with argument `0`. Verification fails because `xj` isn't a function. The hint surfaces the prefix-operator alternatives (`-xj xi`, `+xj <operand>`) and the pre-bind workaround. The misparse is most common when an agent reaches for infix arithmetic between a parameter and a subexpression; pre-binding the operand always resolves the ambiguity. `ilo --explain ILO-T005` includes the full gotcha walkthrough.
The tuple-access trap (`ILO-T004` with the `at <name> <N>` hint) catches `tup.0` / `pair.0` shapes where `tup` / `pair` was never bound. ilo has no tuple type. `zip xs ys` returns `L (L n)` — a list of two-element lists — so destructuring a pair is `at pair 0` / `at pair 1`, not `pair.0` / `pair.1`. The hint names the exact `at` call to write. (`pair.0` itself is still valid sugar for list indexing once `pair` is bound to an `L T`; the diagnostic only fires when the identifier is unbound.)
The AST depth cap (`ILO-P103`) catches deeply nested source that would otherwise blow the parser stack. Any context that compiles untrusted text - `ilo serv`, the bare-positional dispatch, the `--ast` dump - is exposed to a payload of the shape `((((...((1+1))))...))` 1000 levels deep that recurses straight through the OS thread stack. The default cap of 256 is far above anything hand-written (the in-tree examples top out under 20) and low enough to keep the worst-case stack frame in `parse_atom`/`parse_expr` inside the default 8 MB main-thread stack. Override with `--max-ast-depth N` on `ilo`, `ilo run`, `ilo check`, `ilo build`, and `ilo serv` when a legitimate program needs deeper nesting.
---
## Comments
```
-- full line comment
+a b -- end of line comment
-- no multi-line comments; use consecutive -- lines
-- like this
```
Single-line only. `--` to end of line. No multi-line comment syntax - newlines are a human display concern, not a language concern. An entire ilo program can be one line. Use consecutive `--` lines when humans need multi-line comments. Stripped at the lexer level before parsing - comments produce no AST nodes and cost zero runtime tokens. Generating `--` costs 1 LLM token, so comments are essentially free.
**Gotcha:** `--x 1` is a comment, not "negate (x minus 1)". The lexer matches `--` greedily as a comment and eats the rest of the line. To negate a subtraction, use a space or bind first:
```
-- DON'T: --x 1 (comment, not negate-subtract)
-- DO: - -x 1 (space separates the two minus operators)
-- DO: r=-x 1;-r (bind first)
```
---
## Operators
Both prefix and infix notation are supported. **Prefix is preferred** - it is the token-optimal form that eliminates parentheses and produces denser code. Infix is available for readability when needed.
### Binary
| Prefix | Infix | Meaning | Types |
|--------|-------|---------|-------|
| `+a b` | `a + b` | add / concat / list concat | `n`, `t`, `L` |
| `+=a v` | | append to list (returns new list, see [Append semantics](#append-semantics-+=)) | `L` |
| `-a b` | `a - b` | subtract | `n` |
| `*a b` | `a * b` | multiply | `n` |
| `/a b` | `a / b` | divide | `n` |
| `=a b` | `a == b` | equal (prefix `=` is preferred; `==a b` also accepted) | any |
| `!=a b` | `a != b` | not equal | any |
| `>a b` | `a > b` | greater than | `n`, `t` |
| `<a b` | `a < b` | less than | `n`, `t` |
| `>=a b` | `a >= b` | greater or equal | `n`, `t` |
| `<=a b` | `a <= b` | less or equal | `n`, `t` |
| `&a b` | `a & b` | logical AND (short-circuit) | any (truthy) |
| `\|a b` | `a \| b` | logical OR (short-circuit) | any (truthy) |
### Append semantics (`+=`)
`+=xs v` is **pure-shaped**, despite the imperative-looking syntax. It returns a new list with `v` appended and does **not** mutate `xs` in the caller's scope. It works in every position a value-producing expression works:
```
-- 1. Rebind (canonical accumulator pattern)
xs=[];@i 0..3{xs=+=xs i};xs -- [0, 1, 2]
-- 2. Non-rebind assignment (xs preserved)
xs=[1, 2, 3];ys=+=xs 99 -- xs is still [1, 2, 3]; ys is [1, 2, 3, 99]
-- 3. Pipeline / argument position
len +=xs 99 -- length of [xs..., 99]
sum +=xs 99 -- sum of [xs..., 99]
```
The rebind shape `xs = +=xs v` is the standard foreach-build accumulator. When the binding is RC=1 the engines mutate the underlying buffer in place (amortised O(1) per push) - but this is a behind-the-scenes optimisation. To any observer the operation is still functional: nothing outside the rebind sees the old `xs`. The non-rebind shape `ys = +=xs v` always allocates a fresh list and leaves `xs` untouched, so source aliases are safe.
There is no separate `push` builtin. `+=` covers every use case and is shorter; adding an alias would mean two ways to spell the same operation, costing reasoning tokens and surface area.
### Unary
| Op | Meaning | Types |
|----|---------|-------|
| `-x` | negate | `n` |
| `!x` | logical NOT | any (truthy) |
### Special infix
| Op | Meaning | Types |
|----|---------|-------|
| `a??b` | nil-coalesce (if a is nil, return b) | any |
| `a>>f` | pipe (desugar to `f(a)`) | any |
**`??` precedence.** Infix `??` is parsed by `maybe_nil_coalesce` after
the primary expression — it binds **looser than every arithmetic,
comparison, and boolean operator**, and tighter than `>>` (pipe). So
`c??0+1` is `c ?? (0+1)`, not `(c??0) + 1`. Prefix `??x default` mirrors
the infix form: the default slot is a full expression, exactly like the
right operand of any other prefix binop.
This means **`??` inside a prefix-binop chain follows the standard
prefix-binop rule**: the outer op consumes its left atom, and `??` then
binds the next atom as its value and the rest as its default. To get
`(a ?? d) + b` you must bind first or wrap in parens:
```
+a ??d b -- = a + (d ?? b) ← parses as prefix `??d b`
+(a??d) b -- = (a ?? d) + b ← parens force the grouping
x=a??d;+x b -- = (a ?? d) + b ← bind-first, manifesto-preferred
```
The same shape applies to every prefix binop (`-a ??d b`, `*x ??y z`,
`>p ??d r`, etc.). The grouping is consistent with `+a *b c` = `a + (b*c)`
— a prefix op in the right-operand slot consumes its own operands greedily.
The trap is that `??` reads visually like it should be sticky to the
preceding atom; it isn't. When the LHS of `??` is the value being
defaulted, bind first or wrap in parens.
The analogous shape with the boolean operators (`+a |0 b`, `*a &1 b`)
parses the same way, but those produce a type error at verify time
(`+` / `*` on a bool result), so they fail loudly rather than silently
miscompiling. The `??` shape is the dangerous one: both sides of `??`
can be `n`, so the parse silently produces the wrong arithmetic.
### Prefix nesting (no parens needed)
```
+*a b c -- (a * b) + c
*a +b c -- a * (b + c)
>=+x y 100 -- (x + y) >= 100
-*a b *c d -- (a * b) - (c * d)
+a ??c 0 -- a + (c ?? 0) ← not (a ?? 0) + c
*x ??y 1 -- x * (y ?? 1) ← not (x ?? y) * 1
```
The outer prefix op binds the inner prefix subexpression as its **left** operand, regardless of operator precedence. With two same-precedence ops side by side this is easy to misread:
```
*/a b c -- (a/b) * c ← NOT (a*b)/c, NOT a 3-arg compound op
/*a b c -- (a*b) / c ← NOT (a/b)*c
+-a b c -- (a-b) + c ← NOT (a+b)-c
-+a b c -- (a+b) - c ← NOT (a-b)+c
```
`*/` is **not** a 3-arg compound multiply-then-divide. It is the prefix-`*` op with a nested prefix-`/` subexpression as its left operand, so the divisor is the **second** atom (`b`), not the third (`c`). Reading agents commonly mis-write `*/ sz 0.3 0` expecting `sz * 0.3 / 0` and trip a divide-by-zero from the `/0.3`-shaped subexpression once the inputs make `b` zero, since they assumed the trailing `0` was the divisor.
The runtime emits a `hint:` diagnostic when one of these four pairs appears at a prefix position, since the parse order disagrees with the natural left-to-right reading. To force the other grouping, swap the ops or bind the inner result first:
```
-- Want (a*b)/c with a=6, b=2, c=3:
r=*a b;/r c -- bind, then divide → 4
/*a b c -- equivalent, swapping the prefix-pair order
```
### Infix-style chained `+` with a leading prefix `+`
Infix `a+b+c` parses cleanly. But adding a leading `+` (`+a+b+c`) flips the
expression into **prefix mode**: the parser reads `+a` as a prefix binop, so
the immediately-following `+b` orphans and the chain unwinds into
`ILO-P010` (expected expression, got EOF). The parser detects the
`+atom+atom+...` shape (adjacent `+` between atoms) and attaches a hint
pointing at the canonical rewrites:
```
+a+" "+b+" "+c -- rejected (ILO-P010 + targeted hint)
a+" "+b+" "+c -- OK (pure infix concat)
fmt "{} {} {}" a b c -- OK (formatted string)
+a +" " +b +" " c -- OK (nested prefix, right-associative)
s1=+a " ";s2=+s1 b;s3=+s2 " ";+s3 c -- OK (bind intermediates)
```
The same rule applies to numeric chains (`+a+b+c` regardless of operand
type). The fix is always one of: drop the leading `+`, switch to `fmt`,
nest prefix ops with spaces, or bind intermediates.
### Infix precedence
Standard mathematical precedence (higher binds tighter):
| Level | Operators |
|-------|-----------|
| 6 | `*` `/` |
| 5 | `+` `-` `+=` |
| 4 | `>` `<` `>=` `<=` |
| 3 | `=` `!=` |
| 2 | `&` |
| 1 | `\|` |
| 0 | `??` (binds looser than every arithmetic/boolean op; tighter than `>>`) |
Function application binds tighter than all infix operators:
```
f a + b -- (f a) + b, NOT f(a + b)
x * y + 1 -- (x * y) + 1
(x + y) * 2 -- parens override precedence
```
Each nested prefix operator saves 2 tokens (no `(` `)` needed). Flat prefix like `+a b` saves 1 char vs `a + b`. Across 25 expression patterns, prefix notation saves **22% tokens** and **42% characters** vs infix. See [research/explorations/prefix-vs-infix/](research/explorations/prefix-vs-infix/) for the full benchmark.
Disambiguation: `-` followed by one atom is unary negate, followed by two atoms is binary subtract.
### Operands
Operator operands are **atoms** (literals, refs, field access), **nested prefix operators**, or **known-arity function calls**. The prefix-binop operand parser dispatches to call parsing when the ident at the cursor is a known-arity user fn or builtin AND the next token can start another operand:
```
wh >len q 0{body} -- parses as wh > (len q) 0 { body }
+f g h -- if f is 1-arity: BinOp(+, Call(f, [g]), h)
-lnx 5 lnx 3 -- BinOp(-, Call(lnx, [5]), Call(lnx, [3]))
- dbl 5 -- Negate(Call(dbl, [5])) - unary on a call
```
This parallels the `??` precedent: `??x default` accepts a call expression on the value side. Applies to every prefix-binop family member - `+`, `-`, `*`, `/`, comparisons, `&`, `|`, `+=` - and to unary negate when the call consumes the only operand. The same expansion also applies to the then/else slots of the prefix-ternary family (`?=cond a b`, `?>cond a b`, …) and the `?h cond a b` keyword form, so `?h =a b sev sc "NONE"` parses `sev sc` as a nested call without parens or a bind-first. Bare locals that shadow a user fn name still resolve via `Ref` rather than expanding into a zero-arg call, so `&e f{...}` where `f` is a local still parses as the bool operator with two refs.
When the call expansion isn't available (the ident is a local that shadows a fn name, or the call's arity doesn't fit the remaining tokens), bind the call result first:
```
r=fac p;*n r -- bind, then operate - always unambiguous
```
**Negative literals vs binary minus**: the lexer greedily includes a leading `-` into number tokens. `-1`, `-7`, `-0` are all number literals at fresh-expression positions. To subtract from zero at the start of a statement, use a space: `- 0 v` (Minus token, then `0`, then `v`).
```
f v:n>n;-0 v -- WRONG: -0 is Number(-0.0); v is a stray token
f v:n>n;- 0 v -- OK: binary subtract: 0 - v = -v
```
The lexer splits a glued negative literal back into `Minus + Number` when the previous token is one of `;`, `\n`, `=`, `{`, `(`, or `-`. The `-` context covers the operand slot of an outer prefix-minus, so `- -0 a b` lexes as `-, -, 0, a, b` and parses as `Subtract(Subtract(0, a), b)` = `-a - b` rather than tripping `ILO-P020`. Negative literals after an Ident, `[`, or another prefix binop (`+`, `*`, `/`) stay glued so call args (`at xs -1`), list literals (`[-2 1 3]`), and binary operands (`+a -3`) read naturally.
**Subtraction spacing convention**: for general subtraction at statement position, write `a - b` with spaces on **both** sides. `a -b` (glued, no space before the `-`) is not a binary subtract: the lexer packs `-b` into a negative-literal token because the previous token (`a`, an Ident) is one of the keep-glued contexts above. That's deliberate so call args and list elements read naturally, but it means `0 -1.5` is a parse error (`ILO-P001: expected declaration, got number `-1.5`` with a tailored hint pointing at this rule). For a bare negative value as an expression, wrap in parens: `(-1.5)`.
---
## String Literals
Text values are written in double quotes. Escape sequences:
| Sequence | Meaning |
|----------|---------|
| `\n` | newline (0x0A) |
| `\t` | tab (0x09) |
| `\r` | carriage return (0x0D) |
| `\f` | form feed (0x0C, PDF page separator) |
| `\b` | backspace (0x08) |
| `\v` | vertical tab (0x0B) |
| `\a` | bell (0x07) |
| `\0` | null (0x00) |
| `\"` | literal double quote |
| `\\` | literal backslash |
| `\/` | literal forward slash (JSON passthrough) |
Unknown escapes (e.g. `\z`) preserve the backslash + char verbatim.
```
"hello\nworld" -- two-line string
"col1\tcol2" -- tab-separated
spl text "\n" -- split file content into lines
spl pdf "\f" -- split pdftotext output into pages
```
### Triple-quoted strings: `"""..."""`
Same surface as `"..."` (same escape decoding, same `{name}` interpolation)
with two extra affordances:
1. Raw newlines are allowed inside the literal, so multi-line content
does not need `cat`-concatenation or `\n` escapes.
2. When the closing `"""` sits on its own line, the leading newline is
dropped and the common leading whitespace (matching the indent of
the closing-`"""` line) is stripped from every content line. The
terminating `\n` of the last content line is preserved. This is the
Python PEP 257 / Rust `indoc!` convention, so indented source produces
clean output.
```
banner>t
"""
line one
line two
""" -- value is "line one\nline two\n"
inline>t
"""foo
bar""" -- value is "foo\n bar" (no dedent: closing inline)
len """hello""" -- 5 (single-line form, no newline)
len """""" -- 0 (empty body)
```
Inside `"""..."""` a single `"` is literal: only `"""` ends the literal.
Escapes (`\n`, `\t`, ...) and `{name}` interpolation decode identically
to the single-quoted form, so triple-quoted is a drop-in upgrade rather
than a parallel surface.
### Interpolation: `{name}`
A bare `{name}` slot inside a double-quoted string desugars at parse time
to a `fmt` call with the binding looked up by name. Manifesto principle 1:
`"hello {name}"` is cheaper for an agent to write than the verbose
`fmt "hello {}" name`, and both produce the same AST so they cost
nothing extra at verify or run time.
```
greet name:t>t
fmt "hello {name}" -- desugars to: fmt "hello {}" name
pair a:t b:t>t
fmt "{a} and {b}" -- multiple slots, resolved left-to-right
with-braces name:t>t
fmt "{{json}} {name}" -- {{ / }} escape to literal { / }
```
Scope (deliberately tight to keep the surface predictable):
- Only single-identifier slots matching the ident regex
(`[a-z][a-z0-9]*(-[a-z0-9]+)*`). `{a-b}` works; `{Foo}`, `{x + 1}`,
`{ }` pass through verbatim.
- `{{` / `}}` escape to literal `{` / `}` in **every** double-quoted
string literal (Rust `format!` / Python `str.format` convention). The
agent always has a way to emit a literal `{` or `}` without dropping
to `chr 123` + concat.
- A lone unmatched `{` or `}` in a string literal is a parse error
(`ILO-P024`) whose hint points at `{{` / `}}` as the canonical escape.
Matched but non-ident `{...}` (e.g. `{Foo}`, `{x+1}`) still passes
through verbatim so existing `fmt` templates keep working.
- Bare `{}` keeps its existing meaning as a positional placeholder filled
by trailing args of the enclosing `fmt` call.
- Mixing `{ident}` and bare `{}` in the same string is left verbatim:
pick one style per string. Use `fmt "{name} {} done" other` and the
parser keeps the `{name}` literal so the bare `{}` resolves to `other`,
or write `"{name} {other} done"` and drop the trailing arg.
- Undefined `{name}` slots surface as a normal ILO-T004 undefined-variable
diagnostic against the desugared `fmt` arg, not a silent empty
substitution.
- Interpolation does not apply in pattern literals (`"foo":` arm of a
match) - literal patterns stay literal.
---
## Builtins
Called like functions, compiled to dedicated opcodes.
| Call | Meaning | Returns |
|------|---------|---------|
| `len x` | length of string (bytes) or list (elements) | `n` |
| `str n` | number to text (integers format without `.0`) | `t` |
| `num x` | polymorphic: text → parsed number (trims leading/trailing ASCII whitespace; Err if unparseable). number → identity-wrapped Ok. Accepting both saves the `num (str x)` roundtrip when `x` already came back numeric (e.g. from `jpar!` on a JSON number). | `R n t` |
| `abs n` | absolute value | `n` |
| `min a b` | minimum of two numbers | `n` |
| `min xs` | minimum element of a numeric list (error if empty) | `n` |
| `max a b` | maximum of two numbers | `n` |
| `max xs` | maximum element of a numeric list (error if empty) | `n` |
| `mod a b` | C-style signed remainder; result sign matches dividend. Errors on zero divisor. For negative inputs use `fmod`. | `n` |
| `fmod a b` | Floor-mod: always non-negative when `b > 0`. Equivalent to Python `a % b`. Errors on zero divisor. NaN/Inf inputs propagate via IEEE 754 (same policy as every other math builtin). Use instead of `(a % b + b) % b` workarounds for weekday/timezone arithmetic. | `n` |
| `flr n` | floor (round toward negative infinity) | `n` |
| `cel n` | ceiling (round toward positive infinity) | `n` |
| `rnd` | random float in [0, 1). NOT round - for round use `rou` (alias: `round`). Aliases: `rand`, `random`. | `n` |
| `rnd a b` | random integer in [a, b] (inclusive) | `n` |
| `rand-bytes n` | cryptographically random bytes from the platform CSPRNG (via `getrandom`), encoded as base64url-no-pad text. Distinct from `rnd` (seedable uniform float for simulations): this is the path for JWT `jti`, CSRF tokens, session IDs, nonces. Output is URL-safe so it drops straight into headers / cookies / query strings. Capped at 1 MiB; non-negative `n` only. | `t` |
| `rndn mu sigma` | one sample from N(mu, sigma) (Box-Muller) | `n` |
| `seed n` | set the shared PRNG state to `n` (SplitMix64); all subsequent `rnd`/`rndn` calls in every engine use this state. Default seed is deterministic (no wall-clock). Returns `_`. | `_` |
| `now` | current Unix timestamp (seconds) | `n` |
| `now-ms` | current Unix timestamp (milliseconds) | `n` |
| `get url` | HTTP GET | `R t t` |
| `get url headers` | HTTP GET with custom headers (`M t t` map) | `R t t` |
| `get-to url timeout-ms` | HTTP GET with explicit timeout (milliseconds); Err if deadline exceeded | `R t t` |
| `pst url body` | HTTP POST with text body (renamed from `post` in 0.12.0) | `R t t` |
| `pst url body headers` | HTTP POST with body and custom headers (`M t t` map) | `R t t` |
| `pst-to url body timeout-ms` | HTTP POST with explicit timeout (milliseconds); Err if deadline exceeded | `R t t` |
| `getx url` | HTTP GET, rich response: Ok-map with `status` (n), `headers` (M t t), `body` (t). Non-2xx is still Ok with the status code surfaced, only transport failure is Err. Use for conditional requests, redirect following, pagination Link headers, rate-limit headers. | `R (M t _) t` |
| `getx url headers` | as `getx`, with request headers (`M t t` map) | `R (M t _) t` |
| `pstx url body` | HTTP POST with rich response. Same Ok-map shape as `getx`. | `R (M t _) t` |
| `pstx url body headers` | as `pstx`, with request headers (`M t t` map) | `R (M t _) t` |
| `get-stream url` | HTTP GET, lazy line iterator over the response body — bytes drain as they arrive, never buffered (ILO-46). Consume via `@line (get-stream url){...}`. Each iteration yields one chunk-line with the trailing newline stripped. Cap-checked via `--allow-net` before opening the connection. On WASM returns Err. Mid-stream I/O errors surface as ILO-R009. Tree + VM only (Cranelift JIT follow-up). | `L t` |
| `get-stream-h url headers` | as `get-stream`, with request headers (`M t t` map) | `L t` |
| `pst-stream url body` | HTTP POST that streams the response body as a lazy line iterator. Same semantics as `get-stream`. | `L t` |
| `pst-stream-h url body headers` | as `pst-stream`, with request headers (`M t t` map) | `L t` |
| `put url body` | HTTP PUT with text body | `R t t` |
| `put url body headers` | HTTP PUT with body and custom headers (`M t t` map) | `R t t` |
| `pat url body` | HTTP PATCH with text body | `R t t` |
| `pat url body headers` | HTTP PATCH with body and custom headers (`M t t` map) | `R t t` |
| `del url` | HTTP DELETE | `R t t` |
| `del url headers` | HTTP DELETE with custom headers (`M t t` map) | `R t t` |
| `hed url` | HTTP HEAD (response body typically empty; success via Ok/Err) | `R t t` |
| `hed url headers` | HTTP HEAD with custom headers (`M t t` map) | `R t t` |
| `opt url` | HTTP OPTIONS | `R t t` |
| `opt url headers` | HTTP OPTIONS with custom headers (`M t t` map) | `R t t` |
| `urlenc s` | RFC 3986 percent-encode; unreserved chars (ALPHA/DIGIT/`-._~`) pass through, everything else as `%HH`. Total. | `t` |
| `urldec s` | inverse of `urlenc`; Err on invalid percent escape or non-UTF-8 decoded bytes | `R t t` |
| `b64u s` | base64url-encode UTF-8 bytes of `s` (RFC 4648 §5, no padding, `-`/`_` alphabet). Total. | `t` |
| `b64u-dec s` | inverse of `b64u`; Err on invalid base64url or non-UTF-8 decoded bytes | `R t t` |
| `sha256 s` | SHA-256 digest of the UTF-8 bytes of `s`, lowercase hex (64 chars). Total. | `t` |
| `sha256-hex h` | SHA-256 of hex-decoded bytes of `h`, lowercase hex (64 chars). Errors (ILO-R009) on odd-length or non-hex input. Use for raw-binary hashing (wire formats, key material, Bitcoin scripts). | `t` |
| `sha256d h` | double-SHA256 of hex-decoded bytes (`sha256(sha256(h))`), lowercase hex. Bitcoin Merkle protocol shape. Errors (ILO-R009) on odd-length or non-hex input. | `t` |
| `hmac-sha256 key msg` | HMAC-SHA256 of `msg` under `key`; lowercase hex (64 chars). Pair with `ct-eq` to verify signatures without timing leaks. | `t` |
| `b64 s` | standard base64 encode of UTF-8 bytes of `s` (RFC 4648 §4, with `=` padding). Distinct from `b64u` which is URL-safe + no padding. Total. | `t` |
| `b64-dec s` | inverse of `b64`; Err on invalid base64 input or non-UTF-8 decoded bytes | `R t t` |
| `hex s` | lowercase hex encode of UTF-8 bytes of `s` (every byte → 2 hex chars). Total. | `t` |
| `hex-rev s` | reverse the byte order of a hex-encoded string (byte-pair-wise). Input length must be even; odd length errors ILO-T013. Case preserved: `abCD` → `CDab`. Use for little-endian ↔ big-endian conversions (e.g. Bitcoin txid). | `t` |
| `ct-eq a b` | constant-time text equality. Returns true iff `a == b` without short-circuiting on the first differing byte. Use when comparing secrets (HMAC digests, tokens). | `b` |
| `tokcount s` | approximate cl100k_base token count of string `s`. On native targets uses tiktoken-rs cl100k_base BPE (exact OpenAI tokenisation); on WASM falls back to bytes/3.4 stub (within ~5% for English prose). Pure text-in / number-out; tree-bridge eligible. *Experimental* (PR #716, ILO-413). | `n` |
| `run cmd argv` | spawn `cmd` with argv list — secrets scrubbed from child env by default; see [Process spawn](#process-spawn) | `R (M t t) t` |
| `run2 cmd argv` | like `run` but returns a typed `RunResult` record (`r.stdout`, `r.stderr`, `r.exit` as `n`); secrets scrubbed from child env by default | `R RunResult t` |
| `run-full-env cmd argv` | like `run` but inherits the full parent env (opt-in; use when child legitimately needs secrets) | `R (M t t) t` |
| `run2-full-env cmd argv` | like `run2` but inherits the full parent env (opt-in) | `R RunResult t` |
| `env key` | read environment variable | `R t t` |
| `env-all` | snapshot the full process environment as `M t t` | `R (M t t) t` |
| `world` | return the current capability World token (see [Capability World](#capability-world)) | `W` |
| `rd path` | read file; format auto-detected from extension (`.csv`/`.tsv`→grid, `.json`→graph, else text) | `R _ t` |
| `rd path fmt` | read file with explicit format override (`"csv"`, `"tsv"`, `"json"`, `"raw"`) | `R _ t` |
| `rdl path` | read file as list of lines | `R (L t) t` |
| `rdin` | read all of stdin as text; Err on I/O failure or WASM | `R t t` |
| `rdinl` | read stdin as list of lines (newlines stripped); Err on I/O failure or WASM | `R (L t) t` |
| `for-line stdin` | lazy line iterator over stdin — unlike `rdinl`, lines are pulled one at a time so unbounded streams (e.g. `tail -f`) can be processed without buffering. The argument must be the text `"stdin"`. Iterable with `@binding (for-line "stdin"){body}`. On WASM returns Err. I/O errors during iteration surface as ILO-R012. Partial trailing line at EOF is emitted unchanged. Tree + VM only in this release (ILO-70; Cranelift JIT follow-up) | `LazyStdinLines` |
| `lsd dir` | list directory entries (filenames only, not full paths; sorted lexicographically; includes both files and subdirs; empty dirs return `[]`, not Err). Renamed from `ls` in 0.12.1 so the natural `ls=rdl! p` binding for "lines" stays free. | `R (L t) t` |
| `walk dir` | recursive depth-first traversal; paths returned relative to `dir`, sorted; includes both file and directory entries; symlinks not followed. Unreadable subdirectories (e.g. permission denied) are silently skipped so one locked sibling does not poison the whole walk; an unreadable root still returns `Err` | `R (L t) t` |
| `glob dir pat` | shell-style filter under `dir`: `*`/`?`/`[abc]` within a path segment, `**` across segments; relative-path output, sorted; no matches returns `[]` (not Err). Shares `walk`'s traversal so unreadable subdirectories are skipped silently | `R (L t) t` |
| `dirname path` | POSIX-style parent directory. `dirname "/a/b/c.txt"` → `"/a/b"`, `dirname "/"` → `"/"`, `dirname "foo.txt"` → `""` (POSIX returns `"."` here; ilo returns `""` so `pathjoin [dirname p basename p]` round-trips a plain filename without a phantom `./` prefix), `dirname "foo/"` → `""` (trailing slash stripped, then no directory component remains), `dirname "/a"` → `"/"`. Pure text op, no I/O, no Result. Unix forward-slash semantics; Windows separator handling is a 0.13.0 concern | `t` |
| `basename path` | POSIX-style final path segment. `basename "/a/b/c.txt"` → `"c.txt"`, `basename "/"` → `"/"`, `basename "foo/"` → `"foo"` (trailing slash stripped), `basename ""` → `""`. Pure text op, total | `t` |
| `pathjoin parts` | join a list of path segments with `/`, collapsing duplicate separators at joints and dropping empty segments. `pathjoin ["a" "b" "c.txt"]` → `"a/b/c.txt"`, `pathjoin ["a/" "/b/" "c.txt"]` → `"a/b/c.txt"`, `pathjoin []` → `""`, `pathjoin ["/" "a"]` → `"/a"` (leading absolute root preserved). List form (not variadic) so arity inference stays predictable; matches `cat xs sep`'s shape | `t` |
| `fsize path` | file size in bytes (follows symlinks); `Err` on missing, permission-denied, or path-is-directory. Paired predicate `isfile` collapses the error tier into `false` for one-token branches | `R n t` |
| `mtime path` | last modification time as Unix epoch seconds (`f64`, fractional preserved; follows symlinks); `Err` on missing or permission-denied. Pairs with `now` for "is this file older than N seconds" checks | `R n t` |
| `isfile path` | `true` iff `path` resolves to a regular file (follows symlinks). Missing, permission-denied, or non-file all collapse to `false` — natural shape for `?isfile p{…}`. Asymmetric vs `fsize`/`mtime` (which return `R n t`) by design: predicates want a one-token branch, size/mtime callers want to distinguish missing from perm-denied | `b` |
| `isdir path` | `true` iff `path` resolves to a directory (follows symlinks). Same `false`-on-failure collapse as `isfile` | `b` |
| `rdb s fmt` | parse string/buffer in given format - for data from HTTP, env vars, etc. | `R _ t` |
| `wr path s` | write text to file (overwrite) | `R t t` |
| `wr path data "csv"` | write list-of-lists as CSV (with proper quoting) | `R t t` |
| `wr path data "tsv"` | write list-of-lists as TSV | `R t t` |
| `wr path data "json"` | write any value as pretty JSON | `R t t` |
| `wra path s` | append text to file (create if missing); see also `wro` for overwrite | `R t t` |
| `wro path s` | truncate file at path and write s (create if missing); see also `wra` for append | `R t t` |
| `wrl path xs` | write list of lines to file (joins with `\n`) | `R t t` |
| `trm s` | trim leading and trailing whitespace | `t` |
| `spl t sep` | split text by separator | `L t` |
| `fmt tmpl args…` | format string - supports `{}` (Display), `{.Nf}` / `{:.Nf}` (N decimals), `{:N}` (right-align width), `{:Nd}` (integer width), `{:<N}` (left-align width). Filled left-to-right; placeholder count must equal arg count. Out-of-scope specs (zero-pad `{:06d}`, sign `{:+}`, hex `{:x}`) are rejected; compose `fmt2` / `padl` / `padr` for those. Literal-template mismatches surface at verify-time (`ILO-T013`); computed-template errors surface at runtime (`ILO-R009`). Lists are formatted as a single value, not splatted: `fmt "{} {}" [a, b]` is an error - use `fmt "{} {}" a b` instead | `t` |
| `cat xs sep` | join list of text with separator | `t` |
| `has xs v` | membership test (list: element, text: substring) | `b` |
| `idxof s sub` | Unicode code-point index of the first occurrence of `sub` in `s`; returns nil when not found (use `??` for a default). Index is in code-point units (same as `at`), not raw bytes. Tree-bridge eligible. (0.13.0) | `O n` |
| `hd xs` | head (first element/char) of list or text | element / `t` |
| `tl xs` | tail (all but first) of list or text | `L` / `t` |
| `rev xs` | reverse list or text | same type |
| `srt xs` | sort list (all-number or all-text) or text chars (stable: equal elements keep their input order) | same type |
| `srt fn xs` | sort list by key function (returns number or text key); stable: items with equal keys keep their input order | `L` |
| `unq xs` | remove duplicates, preserve order (list or text chars) | same type |
| `slc xs a b` | slice list or text from index a to b (a, b accept negative indices counting from end; bounds clamp). Sugar: when `a >= 0` and `b == -1`, `b` reads as `len xs` (Python/JS "to end" shape). Other negative `b` values (e.g. `-2`) keep the relative-offset semantics; use `take -1 xs` if you want "drop last". | same type |
| `jpth json path` | JSON dot-path lookup, dot-separated keys + numeric array indices (e.g. `"a.b.0.c"`), not JSONPath - leading `$`, `*`, or `[...]` rejected with a diagnostic. Result is typed: arrays → list, objects → record, scalars → matching primitive. | `R _ t` |
| `jkeys json path` | sorted top-level keys of the JSON object at `path` (empty path = root). Err if the value at the path is not an object. | `R (L t) t` |
| `jdmp value` | serialise ilo value to JSON text | `t` |
| `prnt value` | print value to stdout, return it unchanged (passthrough) | same type |
| `jpar text` | parse JSON text into ilo values | `R _ t` |
| `jpar-list text` | parse JSON text, assert top-level is array, return typed list | `R (L _) t` |
| `grp fn xs` | group list by key function | `M t (L a)` |
| `flat xs` | flatten one level of nesting | `L a` |
| `sum xs` | sum of numeric list (0 for empty) | `n` |
| `prod xs` | product of numeric list (1 for empty) | `n` |
| `avg xs` | mean of numeric list (error if empty) | `n` |
| `rgx pat s` | regex: no groups→all matches; groups→first match captures | `L t` |
| `mmap` | create empty map | `M t _` |
| `mget m k` | value at key k (nil if missing) | element or nil |
| `mset m k v` | new map with key k set to v | `M k v` |
| `mhas m k` | true if key exists | `b` |
| `mkeys m` | sorted list of keys | `L t` |
| `mvals m` | values sorted by key | `L v` |
| `mpairs m` | sorted [k, v] pairs; `mpairs m == zip (mkeys m) (mvals m)` | `L (L _)` |
| `mdel m k` | new map with key k removed | `M k v` |
| `mget-or m k default` | value at key k, or `default` if missing (never nil; default type must match value type) | `v` |
| `at xs i` | i-th element of list or text (0-indexed; negative counts from end; float `i` auto-floors) | element |
| `lget-or xs i default` | element at index `i`, or `default` if OOB (negative indices like `at`; never errors on OOB) | `a` |
| `lst xs i v` | list-set: returns a new list with index `i` replaced by `v` (the canonical list-update builtin; same role as `lset`/`setat`/`set-at` in other languages — `lset` is the long-form alias) | `L a` |
| `take n xs` | first `n` elements/chars of list or text (n>=0 truncates if n>len; n<0 keeps all but the last `abs n`, Python `xs[:n]`) | same type |
| `drop n xs` | skip first `n` elements/chars (n>=0 returns the rest; n<0 keeps only the last `abs n`, Python `xs[n:]`) | same type |
| `rsrt xs` | sort descending (list or text chars) | same type |
| `rsrt fn xs` | sort descending by key function (returns number or text key) | `L` |
| `rsrt fn ctx xs` | sort descending by key function with explicit ctx arg (closure-bind alternative; `fn` takes `(elem, ctx)`) | `L` |
| `uniqby fn xs` | dedupe by key function (first occurrence wins) | `L a` |
| `zip xs ys` | pairwise pairs of two lists; truncates to shorter input | `L (L _)` |
| `enumerate xs` | pair each element with its index → `[[i, v], ...]` | `L (L _)` |
| `range a b` | half-open numeric range `[a, a+1, ..., b-1]`; empty when `a >= b` | `L n` |
| `linspace a b n` | `n` evenly-spaced floats from `a` to `b` inclusive (numpy `endpoint=True`). `n=0` returns `[]`; `n=1` returns `[a]`; `n>=2` includes both endpoints (last element pinned to `b` to avoid float drift) | `L n` |
| `ones n` | `n` copies of `1.0`; `n=0` returns `[]`. Saves `map (i:n>n;1) (range 0 n)` for design-matrix columns | `L n` |
| `rep n v` | `n` copies of `v`; element type follows `v`. `n=0` returns `[]`. Saves `map (i:n>T;v) (range 0 n)` for accumulator seeding and constant tables | `L T` |
| `map fn xs` | apply `fn` to each element | `L b` |
| `flt fn xs` | keep elements where `fn x` is true | `L a` |
| `ct fn xs` | count elements where `fn x` is true (avoids `len (flt fn xs)`'s intermediate list alloc) | `n` |
| `fld fn xs init` | left fold: `fn (fn (fn init x0) x1) ...`. Outer order is `fn xs init` (NOT `fn init xs` like Haskell/Python `reduce`). Lambda is `{acc el> ...}` — accumulator first, element second (NOT element-first like JS `Array.reduce`). Example: `fld {a x> +a x} [1 2 3] 0` → `6` | accumulator |
| `flatmap fn xs` | map then flatten one level | `L b` |
| `mapr fn xs` | map with short-circuit Result propagation: collects Ok values, returns first Err | `R (L b) e` |
| `default-on-err r d` | unwrap `R T E` to `T`, returning `d` if Err; verifier requires `d` matches Ok type. Mirror of `??` for Result (`??` is nil-coalesce for `O T` only - use `default-on-err` for Result). Prefer over `?r{~v:v;^_:d}` when no error payload is needed. ILO-T040 when first arg is not `R T E` (hint steers at `??` only when first arg is Optional); ILO-T042 when the default's type doesn't match the Ok type; ILO-T041 when `??` is used on a Result. T041 is suppressed when the lhs type is `Unknown` (e.g. type-variable params) to avoid false positives on generic code | `T` |
| `partition fn xs` | split list into `[passing, failing]` by predicate | `L (L a)` |
| `chunks n xs` | non-overlapping chunks of size `n` (final chunk may be shorter) | `L (L a)` |
| `window n xs` | sliding windows of size `n` (drops trailing partial; empty if n > len) | `L (L a)` |
| `clamp x lo hi` | restrict `x` to `[lo, hi]` (lower bound wins when `lo > hi`) | `n` |
| `cumsum xs` | running sum; output length matches input | `L n` |
| `cprod xs` | running product; output length matches input | `L n` |
| `ewm xs a` | exponential moving average: `ewm[0] = xs[0]`, `ewm[i] = a*xs[i] + (1-a)*ewm[i-1]`; `a` in `[0, 1]`, out-of-range errors `ILO-R009` | `L n` |
| `rsum n xs` | rolling sum over a window of size `n`; output length `len xs - n + 1` (empty when `n > len xs`). O(n) total via running-sum, not O(n*w) like `map (i:n>n;sum (slc xs i (+ i n))) ...`. `n < 1` errors `ILO-R009` | `L n` |
| `ravg n xs` | rolling mean over a window of size `n`; same shape + cost as `rsum`. `n < 1` errors `ILO-R009` | `L n` |
| `rmin n xs` | rolling minimum over a window of size `n`; O(n) amortised via a monotonic deque, not O(n*w) like a per-window scan. `n < 1` errors `ILO-R009` | `L n` |
| `where cond xs ys` | parallel-list conditional select (NumPy `np.where`): `output[i] = xs[i] if cond[i] else ys[i]`; all three lists same length (mismatch errors `ILO-R009`); element type of `xs`/`ys` preserved | `L a` |
| `frq xs` | frequency map of elements (keys are bare stringified values) | `M t n` |
| `median xs` | median of numeric list | `n` |
| `quantile xs p` | sample quantile (linear interp; `p` clamped to `[0, 1]`) | `n` |
| `stdev xs` | sample standard deviation (divides by N-1) | `n` |
| `variance xs` | sample variance (divides by N-1) | `n` |
| `argmax xs` | index of the maximum element (first occurrence wins on ties; errors on empty list) | `n` |
| `argmin xs` | index of the minimum element (first occurrence wins on ties; errors on empty list) | `n` |
| `argsort xs` | sorted-index permutation ascending - stable sort, indices of smallest to largest (empty list returns `[]`) | `L n` |
| `bisect xs target` | O(log N) leftmost insertion point in a sorted numeric list (Python `bisect_left`): returns `i` such that `xs[0..i] < target <= xs[i..]`. Empty list returns `0`; target greater than every element returns `len xs`; ties resolve leftmost. Caller owns sortedness precondition - not validated. NaN target propagates as NaN. | `n` |
| `setunion a b` | set union of two lists (deduped, sorted output) | `L a` |
| `setinter a b` | set intersection (deduped, sorted) | `L a` |
| `setdiff a b` | set difference `a - b` (deduped, sorted) | `L a` |
| `chars s` | explode a string into single-char strings (one per Unicode scalar) | `L t` |
| `ord s` | Unicode codepoint of the first character of `s` | `n` |
| `chr n` | single-character string for codepoint `n` | `t` |
| `upr s` | uppercase (ASCII) | `t` |
| `lwr s` | lowercase (ASCII) | `t` |
| `cap s` | capitalise first char (ASCII) | `t` |
| `padl s w` | left-pad to width `w` with spaces (no-op if already wider) | `t` |
| `padr s w` | right-pad to width `w` with spaces (no-op if already wider) | `t` |
| `padl s w pc` | left-pad to width `w` with 1-character string `pc` (e.g. `"0"` for sortable zero-padded keys) | `t` |
| `padr s w pc` | right-pad to width `w` with 1-character string `pc` (e.g. `"."` for dot-leader alignment). Idiom: `padr "" w pc` repeats `pc` w times (histogram bars, divider lines) | `t` |
| `padr s w pc` | right-pad to width `w` with 1-character string `pc` (e.g. `"."` for dot-leader alignment; `padr "" n "#"` repeats `n` copies of `#`) | `t` |
| `rgxall pat s` | every regex match as `L (L t)` (no-group: each match in a 1-elem list) | `L (L t)` |
| `rgxall1 pat s` | flat first-capture-group convenience: 0 groups → `L t` of whole matches; 1 group → `L t` of capture-1 strings; 2+ groups errors | `L t` |
| `rgxall-multi pats s` | multi-pattern flat-match: apply each pattern in `pats:L t` to `s`, concat all hits in pattern order; per-pattern semantics follow `rgxall1` (0 groups → whole matches; 1 group → capture-1 strings; 2+ groups errors) | `L t` |
| `rgxsub pat repl s` | regex substitute all matches; `$1`, `$2`, ... reference capture groups | `t` |
| `dtfmt epoch fmt` | format Unix epoch as text (strftime, UTC) | `R t t` |
| `dtparse s fmt` | parse text to Unix epoch (strftime, UTC) | `R n t` |
| `dtparse-rel s now` | parse relative-date phrase to epoch; `now` is the anchor epoch | `R n t` |
| `dur-parse s` | parse human duration string ("3h 30m", "1 week 2 days", "1.5 hours", "90s") into seconds. Lenient: accepts abbreviations `s`/`m`/`h`/`d`/`w`, full names (singular + plural), decimal quantities, mixed sequences. Err if empty or no unit found | `R n t` |
| `dur-fmt n` | format seconds as human-readable duration ("2h 42m", "1 day", "30s"). Drops zero parts; uses largest applicable units. Zero returns "0s". Negative values format with a leading "-" | `t` |
| `add-mo dt n` | add N calendar months to epoch `dt`, snapping to last day of month when needed (e.g. Jan 31 + 1 = Feb 28/29). N may be negative. Returns epoch at 00:00 UTC | `n` |
| `last-dom dt` | epoch of the last day of the month containing `dt`, at 00:00 UTC (e.g. any Feb 2024 epoch → 2024-02-29 00:00 UTC) | `n` |
| `next-business-day dt` | next weekday after `dt` (skips Sat/Sun). Fri→Mon, Sat→Mon, Sun→Mon, Mon-Thu→next day. Returns epoch at 00:00 UTC | `n` |
| `day-of-week dt` | day of week for epoch `dt`: 0=Sun, 1=Mon, 2=Tue, 3=Wed, 4=Thu, 5=Fri, 6=Sat | `n` |
| `rdjl path` | read JSONL file as `L (R _ t)`: one parse result per non-empty line | `L (R _ t)` |
| `get-many urls` | concurrent HTTP GET fan-out (max 10 parallel), preserves order | `L (R t t)` |
| `par-map fn xs` | apply `fn` to each element of `xs` in parallel (default concurrency = num_cpus; override with `ILO_PAR_MAP_CONCURRENCY`), order-preserving; per-item errors surface as `Err` in result list | `L (R b t)` |
| `par-map fn xs n` | like `par-map fn xs` with explicit concurrency `n`; `n=0` falls back to num_cpus | `L (R b t)` |
| `sleep ms` | pause current engine for `ms` milliseconds; returns nil | `_` |
| `spawn fn args...` | run `fn args...` on a background OS thread, fire-and-forget; returns nil immediately. Errors and panics inside the thread go to stderr; the parent is unaffected. Caps are inherited from the parent. No join, no channels, no supervision, no cancellation in v1, see ILO-477. Tree-walker only at runtime; VM and Cranelift inherit via the tree bridge | `_` |
| `tz-offset tz epoch` | UTC offset in seconds for the named IANA timezone at the given Unix epoch. DST-aware (chrono-tz). Positive = east of UTC. `Err` on unknown timezone name | `R n t` |
| `rou n` | round to nearest integer (banker's rounding) | `n` |
| `rndn mu sigma` | one sample from normal distribution `N(mu, sigma)` (Box-Muller) | `n` |
| `pow b e` | `b` raised to power `e` | `n` |
| `sqrt n` | square root | `n` |
| `exp n` | natural exponent `e^n` | `n` |
| `log n` | natural logarithm | `n` |
| `log10 n` | base-10 logarithm | `n` |
| `log2 n` | base-2 logarithm | `n` |
| `sin n` | sine (radians) | `n` |
| `cos n` | cosine (radians) | `n` |
| `tan n` | tangent (radians) | `n` |
| `asin n` | arcsine, returns radians in `[-pi/2, pi/2]`; NaN outside `[-1, 1]` | `n` |
| `acos n` | arccosine, returns radians in `[0, pi]`; NaN outside `[-1, 1]` | `n` |
| `atan n` | arctangent, returns radians in `[-pi/2, pi/2]` | `n` |
| `atan2 y x` | two-argument arctangent (y, x order; radians) | `n` |
| `pi` | 3.141592653589793 (IEEE-754 f64, `f64::consts::PI`) | `n` |
| `tau` | 6.283185307179586 (== 2\*pi; one full turn in radians) | `n` |
| `e` | 2.718281828459045 (Euler's number, `f64::consts::E`) | `n` |
| `transpose m` | transpose row-major matrix | `L (L n)` |
| `matmul a b` | matrix product | `L (L n)` |
| `matvec xm ys` | matrix-vector product (`r[i] = sum_j xm[i][j] * ys[j]`); skips the wrap-as-column + flatten ceremony around `matmul` | `L n` |
| `dot a b` | vector dot product | `n` |
| `solve a b` | solve `Ax = b` via LU with partial pivoting; errors on singular/non-square | `L n` |
| `inv a` | matrix inverse; errors on singular/non-square | `L (L n)` |
| `det a` | determinant; errors on non-square | `n` |
| `lstsq xm ys` | ordinary least squares: returns coefficients `b` minimising `\|xm·b - ys\|²` via the normal equations (`solve (Xᵀ X) (Xᵀ y)`). Errors on rank-deficient design, underdetermined system (cols > rows), or row/length mismatch | `L n` |
| `fft xs` | discrete FFT: real samples → `L [re, im]`; zero-padded to next power of 2 | `L (L n)` |
| `ifft pairs` | inverse FFT; imaginary part dropped on return | `L n` |
| `fmt2 x digits` | format number `x` to `digits` decimal places (half-to-even rounding; `digits` clamped to `0..=20`). Compose with `fmt` for template + precision: `fmt "x={}" (fmt2 v 2)` | `t` |
> **Float `{}` = full IEEE 754 precision.** `fmt "{}" v` on a non-integer float emits the shortest round-trip representation: `fmt "GC={}" 0.54166666 ` -> `"GC=0.54166666"`, `fmt "{}" +0.1 0.2` -> `"0.30000000000000004"`. For human-readable output use a precision spec (`fmt "GC={:.2f}%" pct` -> `"GC=54.17%"`, `fmt "{:.4f}" 3.14159` -> `"3.1416"`) or compose `fmt2` (`fmt "x={}" (fmt2 v 6)`). Integer-valued floats render without a decimal point (`fmt "{}" 2.0` -> `"2"`), so the trap only fires on non-integer values. This is intentional and language-stable — every `-- out:` annotation and golden test in the repo depends on it; changing the default would silently invalidate them.
> **`fmt` does not print.** `fmt` and `fmt2` are pure-functional string builders, not `println!`. A bare `fmt "..." v` statement evaluates and discards the resulting text on every engine - nothing reaches stdout. Print with `prnt fmt "..." v` or capture with `line = fmt "..." v`. The verifier emits **ILO-T032** when `fmt`/`fmt2` is a non-tail statement with no binding. Tail position is fine: `say-x v:n>t;fmt "x={}" v` returns the string to the caller as documented.
> **`+=`, `mset`, and `mdel` return a new value, they do not mutate in place.** `+=xs v` returns a new list; `mset m k v` and `mdel m k` return a new map. As a bare statement (`@i 0..3{+=out i}`, `mset m "a" 1;m`) the result is silently discarded and the source binding is unchanged. The verifier emits **ILO-T033** when these calls appear at a discarded position - any non-tail statement, or anywhere inside a loop body. Fix is the assignment form: `out=+=out i`, `m=mset m k v`, `m=mdel m k`. Tail position in a function/`?{}` arm is fine - the value flows out as the return. If discarding the result is genuinely intentional (e.g. calling for a side effect you know returns a new map), use `_=mset m k v` — the explicit discard sigil suppresses T033.
> **`wr` and `wrl` return the written path, not a status.** Both succeed with `~path` (the file path you passed in), not `~"ok"` or nil. A `save` helper that ends with a bare `wrl "tasks.txt" xs` therefore returns `~"tasks.txt"`, and every successful mutation echoes the state-file path to stdout - noise for any caller piping output. Discard the path and return a clean status string instead: `save xs:L t>R t t;r=wrl "tasks.txt" xs;?r{~_:~"ok";^e:^e}`. The error arm still propagates `wrl`'s message. See [`examples/cli-tasks-save-ok.ilo`](examples/cli-tasks-save-ok.ilo) for the full shape.
### Datetime (`dtfmt` / `dtparse` / `dtparse-rel`)
UTC only. Format strings follow strftime conventions (`%Y-%m-%d %H:%M:%S`, `%s`, etc).
```
dtfmt 1700000000 "%Y-%m-%d" -- R t t: Ok="2023-11-14", Err if out of range
dtparse "2024-01-15" "%Y-%m-%d" -- R n t: Ok=epoch seconds, Err if unparseable
dtfmt! e "%H:%M:%S" -- auto-unwrap inside R-returning fn
```
`dtparse-rel s now` resolves a natural-language relative-date phrase to a Unix epoch anchored at `now`. Phrases supported:
- `today`, `yesterday`, `tomorrow`
- `N days ago`, `in N days` (also `N day ago`, `in N day`)
- `N weeks ago`, `in N weeks`
- `N months ago`, `in N months` (end-of-month clamping: `Jan 31 + 1 month = Feb 28/29`)
- `last <weekday>`, `next <weekday>`, `this <weekday>` — weekdays as `monday`–`sunday` or short `mon`–`sun`; `last`/`next` never return today
- ISO-8601 date literal `YYYY-MM-DD` — passthrough to `dtparse` (ignores `now`)
```
-- now = 1705276800 (2024-01-15, Monday)
dtparse-rel!! "yesterday" (now) -- 2024-01-14 00:00 UTC
dtparse-rel!! "3 days ago" (now) -- 2024-01-12 00:00 UTC
dtparse-rel!! "in 2 weeks" (now) -- 2024-01-29 00:00 UTC
dtparse-rel!! "last friday" (now) -- 2024-01-12 00:00 UTC
dtparse-rel!! "next wednesday" (now) -- 2024-01-17 00:00 UTC
dtparse-rel!! "2023-12-25" (now) -- 1703462400 (ignores now)
```
Unrecognised phrases return `Err` with a message listing valid forms. All times are midnight UTC.
### Duration (`dur-parse` / `dur-fmt`)
`dur-parse s > R n t` — parse a human-readable duration string into total seconds as a float.
`dur-fmt n > t` — format seconds as a human-readable duration string.
Both are tree-bridge eligible: VM and Cranelift dispatch through the same interpreter arm.
Accepted units for `dur-parse`:
| abbreviation | full names |
|---|---|
| `w` | week, weeks |
| `d` | day, days |
| `h` | hour, hours, hr, hrs |
| `m` | min, mins, minute, minutes |
| `s` | sec, secs, second, seconds |
```
dur-parse "3h 30m" -- R n t: Ok=12600, Err if no unit found
dur-parse "1 week 2 days" -- R n t: Ok=777600
dur-parse "1.5 hours" -- R n t: Ok=5400
dur-parse "4h32m" -- no space between number and unit: Ok=16320
dur-parse! s -- auto-unwrap inside R-returning fn
dur-fmt 9720 -- "2h 42m"
dur-fmt 86400 -- "1 day"
dur-fmt 90 -- "1m 30s"
dur-fmt 90.5 -- "1m 30.5s" (fractional seconds preserved)
dur-fmt 0 -- "0s"
dur-fmt -90 -- "-1m 30s" (single leading minus)
-- Round-trip: parse -> seconds -> format
n = dur-parse! "2 days 3 hours"
dur-fmt n -- "2 days 3h"
```
**Months are not supported.** `mo`, `month`, `months`, `M` are deliberately
omitted because a month is not a fixed number of seconds. Strings like
`"3mo"` or `"3 months"` produce a `no recognised unit` error. Use explicit
day counts (e.g. `"30 days"`, `"90 days"`).
**Sticky sign.** A leading `-` in `dur-parse` is sticky: it applies to every
following token until an explicit `+` resets it. So `"-1m 30s"` parses to
`-90`, and `"-1h +10m"` parses to `-3000`. This makes the round-trip
`dur-fmt -> dur-parse` symmetric for negative durations, where `dur-fmt`
emits a single leading minus rather than signing each part.
**Fractional seconds.** `dur-fmt` renders sub-second fractions with up to
3 decimal places (trailing zeros stripped), both for sub-second inputs
(`0.5 -> "0.5s"`) and for mixed values where the seconds component carries
a fraction (`90.5 -> "1m 30.5s"`). Fractional minutes / hours / days / weeks
are decomposed into smaller units before formatting.
### Calendar arithmetic (`add-mo`, `last-dom`, `next-business-day`, `day-of-week`)
Four builtins for month-level and business-day date arithmetic. All take Unix epoch seconds (as returned by `now`, `dtparse`, etc.) and return epoch seconds at 00:00 UTC. All are tree-bridge eligible: VM and Cranelift dispatch through the same interpreter arm without extra opcodes.
`add-mo dt:n n:n > n` — add N calendar months to epoch `dt`. N may be negative. End-of-month snap: if the resulting month is shorter than the source day, the day is clamped to the last valid day (e.g. Jan 31 + 1 mo = Feb 28/29).
`last-dom dt:n > n` — epoch of the last day of the month that contains `dt`, at 00:00 UTC. Uses the first-of-next-minus-one algorithm so it handles Dec correctly.
`next-business-day dt:n > n` — the next weekday after `dt` (i.e. `dt + 1` for Mon-Thu, `dt + 3` for Fri, `dt + 2` for Sat, `dt + 1` for Sun). Returns 00:00 UTC on the result date.
`day-of-week dt:n > n` — 0=Sun, 1=Mon, 2=Tue, 3=Wed, 4=Thu, 5=Fri, 6=Sat. Zero-based with Sunday=0 (JS/POSIX convention), giving a direct index into 7-element arrays.
```
-- Epoch anchors used below
jan31_2024 = 1706659200 -- 2024-01-31 00:00 UTC
add-mo jan31_2024 1 -- 1709164800 (2024-02-29, leap year snap)
add-mo jan31_2024 -1 -- 1703980800 (2023-12-31)
add-mo jan31_2024 12 -- 1738281600 (2025-01-31, same day next year)
last-dom jan31_2024 -- 1706659200 (already the last day, returns itself)
last-dom 1707955200 -- 1709164800 (2024-02-15 -> last day of Feb 2024 = Feb 29)
next-business-day 1705622400 -- 1705881600 (Fri 2024-01-19 -> Mon 2024-01-22)
next-business-day 1705795200 -- 1705881600 (Sun 2024-01-21 -> Mon 2024-01-22)
day-of-week jan31_2024 -- 3 (Wednesday)
day-of-week 1705276800 -- 1 (2024-01-15, Monday)
day-of-week 0 -- 4 (1970-01-01, Thursday)
```
### Set operations
`setunion`, `setinter`, `setdiff` operate on lists of `t`, `n`, or `b` (same constraint as `uniqby`). Output is deduped and sorted by a type-prefixed string key, so results are deterministic across runs and engines. Sort is lexicographic on the key, not numeric - re-sort with `srt` afterwards if you need numeric order.
### Linear algebra
`transpose`, `matmul`, `matvec`, `dot`, `solve`, `inv`, `det`, `lstsq` operate on row-major matrices (`L (L n)`) and flat vectors (`L n`). `solve`, `inv`, `det` use LU decomposition with partial pivoting and raise on singular or non-square inputs. `matvec xm ys` is matrix-vector product as a flat vector; it skips the `flatten matmul xm (map (y:n>L n;[y]) ys)` ceremony needed to coerce a vector into a column matrix. `lstsq` is a thin wrapper around the normal equations (`solve (Xᵀ X) (Xᵀ y)`) — closed-form OLS at the same precision tier as `solve`; numerically inferior to QR/SVD for ill-conditioned designs. These ship as host-vetted builtins because hand-rolled implementations risk silent precision loss.
### FFT
`fft xs` runs an iterative Cooley-Tukey radix-2 transform on real samples, zero-padding to the next power of two. Output is `L [re, im]` with one inner pair per frequency bin. `ifft pairs` is the inverse, dropping the imaginary part on return.
### Builtin aliases
All builtins accept one or more alias names that resolve to the canonical name after parsing. Using an alias triggers a hint suggesting the canonical form. Most aliases go from a familiar long form (e.g. `length`) to the canonical short (`len`), letting newcomers write readable code while learning the canonical names. A small number go the other direction: where the canonical name is already 4+ characters and there is a natural short form with no plausible-user-binding collision, the short form is carved out as a permanent ergonomic alias.
| Alias | → | Canonical |
|-------|---|-----------|
| `floor` | → | `flr` |
| `ceil` | → | `cel` |
| `round` | → | `rou` |
| `rand` | → | `rnd` |
| `random` | → | `rnd` |
| `rng` | → | `range` |
| `lset` | → | `lst` |
| `regex_all` | → | `rgxall` |
| `regex_sub` | → | `rgxsub` |
| `string` | → | `str` |
| `number` | → | `num` |
| `length` | → | `len` |
| `head` | → | `hd` |
| `tail` | → | `tl` |
| `reverse` | → | `rev` |
| `sort` | → | `srt` |
| `slice` | → | `slc` |
| `unique` | → | `unq` |
| `filter` | → | `flt` |
| `fold` | → | `fld` |
| `flatten` | → | `flat` |
| `concat` | → | `cat` |
| `contains` | → | `has` |
| `group` | → | `grp` |
| `average` | → | `avg` |
| `print` | → | `prnt` |
| `trim` | → | `trm` |
| `split` | → | `spl` |
| `format` | → | `fmt` |
| `regex` | → | `rgx` |
| `read` | → | `rd` |
| `readlines` | → | `rdl` |
| `readbuf` | → | `rdb` |
| `write` | → | `wr` |
| `writelines` | → | `wrl` |
```
length xs -- works, but emits: hint: `length` → `len` (canonical form)
len xs -- canonical - no hint
rng 0 10 -- works, but emits: hint: `rng` → `range` (canonical form)
range 0 10 -- canonical - no hint
```
Every alias - both short-form (`rng`, `rand`) and long-form (`head`, `length`, `filter`, `concat`, ...) - follows the same shadow-prevention rule as canonical builtins: using an alias name as a binding LHS or user-function name is rejected at parse time with `ILO-P011`. The alias resolver rewrites call-position uses to the canonical builtin, so if the bind were allowed the user variable would be silently bypassed and the builtin called instead. For example, `head=fmt "### {}" t` then `cat [head body] "\n"` would rewrite `head` in call position to `hd`, emitting empty output with no error. The parser intercepts every alias in all three positions (top-level binding, local binding inside a function, user function declaration) with a rename hint. The full alias table is listed above; every entry triggers `ILO-P011` in all three contexts.
`get` and `pst` return `Ok(body)` on success, `Err(message)` on failure (connection error, timeout, DNS failure, etc).
In 0.12.0 the `$` sigil was rebound from `get` (parochial — `$` for HTTP is unique to ilo) to the new `run` builtin (argv-list process spawn). `$` for shell-exec reads cross-language — bash, Perl, Ruby, Python, PowerShell, and Zx all use `$` for command substitution. HTTP `get` is still called by name; the `$` shortcut is for process exec only. `post` was renamed to `pst` to bring it into line with the I/O compression family (`rd`, `wr`, `srt`, `flt`, `fld`, `fmt`).
```
get url -- R t t: Ok=response body, Err=error message
get! url -- auto-unwrap: Ok→body, Err→propagate to caller
pst url body -- R t t: HTTP POST with text body
pst url body headers -- R t t: HTTP POST with body and custom headers
-- Custom headers: build an M t t map with mmap/mset
h=mmap
h=mset h "x-api-key" "secret"
r=get url h -- GET with x-api-key header
r=pst url body h -- POST with x-api-key header
-- Explicit timeouts (milliseconds; rounds up to nearest second internally)
r=get-to url 5000 -- GET with 5 s timeout; Err if exceeded
r=pst-to url body 3000 -- POST with 3 s timeout
-- Rich-response variants: getx / pstx return an Ok-map with status, headers,
-- and body. Use these when you need status-code branching (304 Not Modified,
-- 429 Too Many Requests), response-header access (ETag, Link, X-RateLimit-*),
-- or redirect following. Existing `get` / `pst` body-only shapes are untouched.
r=getx url -- R (M t _) t: Ok={status:n, headers:M t t, body:t}
r=getx url h -- with request headers (h is M t t)
r=pstx url body -- R (M t _) t: POST with rich response
r=pstx url body h -- with request headers
-- Status-code branching: non-2xx surfaces as a status, not Err
?r{~m:?(=(mget!! m "status") 304){"not modified"};^_:"transport err"}
-- Header read: response header names are lowercased
etag=mget!! (mget!! m "headers") "etag"
```
Behind the `http` feature flag (on by default). Without the feature, `get`/`pst`/`get-to`/`pst-to`/`getx`/`pstx` return `Err("http feature not enabled")`.
### Process spawn
ilo provides two process-spawn primitives: `run` and `run2`. Both share the same no-shell-no-glob security model and the same concurrency / cap / UTF-8 policy; they differ only in what the `Ok` payload looks like.
**`run cmd argv > R (M t t) t`** — loose Map with text fields `stdout`, `stderr`, `code` (exit code as text):
**Output map schema.** On `Ok`, the map has exactly these three keys, all `t`-valued:
| key | type | meaning |
|----------|------|---------------------------------------------------------------|
| `stdout` | `t` | captured stdout bytes decoded as UTF-8 (lossy), as written |
| `stderr` | `t` | captured stderr bytes decoded as UTF-8 (lossy), as written |
| `code` | `t` | exit code as decimal text (`"0"`, `"1"`, …); on unix a signal-terminated child reports `"signal:<n>"` (e.g. `"signal:9"`), and an unknown status reports `"unknown"` |
The map is always shaped this way on success: callers can rely on `mget m "stdout"`, `mget m "stderr"`, and `mget m "code"` all being non-nil text. Trailing newlines from the child are preserved verbatim, so use `trm` if you want to compare against a stripped value.
```
r=run "echo" ["hi"] -- Ok({"stdout":"hi\n","stderr":"","code":"0"})
out=mget r.! "stdout" -- "hi\n"
code=mget r.! "code" -- "0"
err=mget r.! "stderr" -- ""
$"git" ["status", "--short"] -- equivalent: $ is the sigil shortcut for run
```
**`run2 cmd argv > R RunResult t`** — typed Record with dot-access (`r.stdout`, `r.stderr`, `r.exit`). `exit` is a number (`n`), not text, so numeric comparisons work directly:
```
r=run2!! "echo" ["hi"] -- RunResult{stdout:"hi\n"; stderr:""; exit:0}
r.stdout -- "hi\n"
r.exit -- 0 (number, not "0")
?{<0 r.exit : "signal-killed" ; =0 r.exit : "ok" ; "failed"}
```
Prefer `run2` for new code. `run` is kept for compatibility.
**No shell, no interpolation, no glob.** The argv list is passed directly to `std::process::Command::args`. There is no `sh -c`, no string concatenation between `cmd` and `argv`, and no glob expansion. This is the principled defence against shell injection: ilo refuses to provide an injection vector while still providing controlled exec. Compared to bash + `jq`, the argv-list discipline and the typed Result + Record/Map handle make `run`/`run2` materially safer for agent orchestration.
**Non-zero exit is NOT an error.** `Err` is reserved for spawn failures (command not found, permission denied, kernel-level pipe failure, output cap exceeded). A child that returns a non-zero exit code surfaces as `Ok`; the caller inspects `exit` (or `code` for `run`) and branches as needed. This matches Python's `subprocess.run` semantics.
**`run2` exit on signal.** On Unix, a signal-killed process has no exit code. `run2` surfaces this as `exit: -1` so the caller can branch on `<0 r.exit`. `run` uses the string `"signal:<n>"` for the same case.
**Env scrubbing (ILO-346).** `run` and `run2` scrub the following env vars from the child process by default so that secrets set in the agent's environment cannot leak to untrusted children:
- `ANTHROPIC_*` and `CLAUDE_*` — Anthropic / Claude credentials
- `GITHUB_TOKEN`, `GITHUB_PAT` — GitHub PATs
- Any var whose name ends with `_TOKEN`, `_KEY`, `_SECRET`, `_PASSWORD`, `_PASSWD`, `_CREDENTIAL`, or `_CREDENTIALS`
All other vars (including `PATH`, `HOME`, `LANG`, `TZ`) are inherited normally. To opt in to passing the full environment — for example when a child script legitimately needs `ANTHROPIC_API_KEY` — use the `run-full-env` or `run2-full-env` builtins instead:
```
m = run-full-env "my-agent" ["--task" task] -- full env passes through
```
**Inherits parent cwd.** Neither primitive provides a cwd override; set the parent cwd before invoking ilo if you need a different working directory.
**Captured output is capped at 10 MiB per stream.** Either stream exceeding the cap returns an `Err` rather than partial capture so downstream JSON pipelines never see a truncated payload.
**Stdin for child processes.** Both primitives spawn children with stdin closed. Use `rdin` / `rdinl` to read the **parent** program's own stdin from the shell pipeline. `rdin` reads all of stdin as text; `rdinl` reads it line by line.
Behind the same default build profile as `get`/`pst`; on `wasm32` targets, both return `Err("run: process spawn not available on wasm")`.
`env` reads an environment variable by name, returning `Ok(value)` or `Err("env var 'KEY' not set")`:
```
env key -- R t t: Ok=value, Err=not set message
env! key -- auto-unwrap: Ok→value, Err→propagate to caller
```
`env-all` returns the full process environment as a `M t t` map wrapped in `R`, mirroring the `env` shape so `env-all!` auto-unwraps inside a Result-returning function. Use it for "merge env over config" patterns where the agent does not know which keys to read up-front:
```
env-all -- R (M t t) t: Ok=map of every env var, Err reserved for future failures
env-all! -- auto-unwrap to M t t
```
Non-UTF-8 environment variables are silently skipped (same policy as Rust's `std::env::vars`); the snapshot is always `Ok` today.
### Capability World
`world` returns the capability World token, a value of type `W`. It encodes the four CLI capability flags — `net`, `read`, `write`, `run` — as boolean fields, making the side-effect surface of a function visible in its signature.
```
w=world -- W: capability World token (constructed from --allow-* flags)
w.net -- b: true iff net access is permitted
w.read -- b: true iff filesystem read is permitted
w.write -- b: true iff filesystem write is permitted
w.run -- b: true iff process spawn is permitted
```
`W` is a first-class type token used in function signatures:
```
fetch-page w:W url:t>R t t;get w.net url -- error: net=false caught at caller
send-mail w:W body:t>_;... -- signals: uses network
pure-fn x:n>n;+x 1 -- no W param: provably no I/O
```
**Capability values match CLI flags.** Under the permissive default (no `--allow-*` flags) all four flags are `true`. Under `--allow-net=*` only, `net=true`; the other three remain `true` because unspecified flags default to permissive. To restrict a dimension to nothing, pass `--allow-read=` (empty string = block all reads).
**Static enforcement for known-denied Worlds.** `world-no-net` constructs a `W` token with `net=false` known at compile time. The verifier emits **ILO-T044** if any net builtin (`get`, `pst`, `put`, `pat`, `del`, `hed`, `opt`, `getx`, `pstx`, `get-many`, `get-to`, `pst-to`) is called in the same scope:
```
wn = world-no-net -- W: net=false, read/write/run=true
wn.net -- b: false
fetch url:t>R t t
wn = world-no-net
get url -- ERROR ILO-T044: 'wn' is a World with net=false
```
Dynamic worlds (from `world` or `w:W` parameters) are not checked statically — their cap values are determined at runtime via `--allow-*` flags.
```
fetch w:W url:t>R t t;get url -- ok: w is dynamic, enforced at runtime
main>t;
w=world
r=fetch w "https://api.example.com/data"
...
```
See `examples/capability-world.ilo` and `examples/world-static-enforce.ilo` for working examples.
### JSON builtins
`jpth` extracts a value from a JSON string by dot-separated path. Array elements are accessed by numeric index. **Note: `jpth` is dot-path only, not JSONPath.** A leading `$`, `*` wildcard, or `[...]` bracket selector triggers a diagnostic error pointing at the dot-path form; iterate arrays yourself with `@i` or `map` if you need wildcard behaviour.
Since 0.12.1 the Ok variant is **typed**: a JSON array comes back as a list (`@`-iterable, `len`-able), a JSON object comes back as a record (`jdmp`-roundtrippable, `jkeys`-enumerable), and scalars come back as the matching ilo primitive (number, text, bool, nil). Pre-0.12.1 every non-string leaf was stringified, forcing a re-parse via `jpar` to iterate. The signature is now `R _ t`.
```
jpth json "name" -- R _ t: Ok=typed value, Err=error message
jpth json "user.name" -- nested path lookup
jpth json "items.0.name" -- array index access (dot before index, not [0])
jpth json "spans" -- Ok=L _ when the leaf is a JSON array (iterable!)
jpth json "deps" -- Ok=record when the leaf is a JSON object
jpth json "n" -- Ok=Number 42 (not Text "42") on a numeric leaf
jpth! json "name" -- auto-unwrap
jpth json "$.a.b" -- ^"jpth is dot-path only ..." (JSONPath rejected)
jpth json "items.*.name" -- ^"jpth is dot-path only ..." (no wildcards)
```
`jkeys json path` returns the **sorted** top-level keys of the JSON object at the dot-path as `L t`. Empty path means root. Errs if the value at the path is not an object. Pairs with `mkeys` (which works on ilo `M` maps) so an agent can enumerate JSON object keys without re-parsing through `jpar`.
```
jkeys json "" -- R (L t) t: Ok=sorted root keys
jkeys json "deps" -- sorted keys of the "deps" object
jkeys! json "deps" -- auto-unwrap
jkeys json "items" -- ^"jkeys: value at path is not a JSON object"
```
`jdmp` serialises any ilo value to a JSON string:
```
jdmp 42 -- "42"
jdmp "hello" -- "\"hello\""
jdmp [1 2 3] -- "[1,2,3]"
jdmp (pt x:1 y:2) -- "{\"x\":1,\"y\":2}"
```
`jpar` parses a JSON string into ilo values. JSON objects become records with type name `json`, arrays become lists, strings/numbers/bools/null map directly:
```
jpar text -- R _ t: Ok=parsed value, Err=parse error
r=jpar! "{\"x\":1}" -- r is a json record, access with r.x
```
`jpar-list` is a typed companion: it parses the JSON string and **asserts the top-level value is an array**. The result is `R (L _) t`, so `jpar-list! body` unwraps directly to a list that `@` can iterate — no intermediate binding or type annotation needed:
```
jpar-list text -- R (L _) t: Ok=list of parsed values, Err=parse or type error
-- iterate a JSON array response body:
@x (jpar-list! body){prnt x}
-- or bind first:
xs=jpar-list! body;@i 0..len xs{prnt (at xs i)}
```
Use `jpar` when the JSON top-level shape is unknown (object, array, scalar). Use `jpar-list` when you know the response is an array and want to iterate it immediately. Writing `@x (jpar! body){...}` directly triggers `ILO-W002` steering you at `jpar-list!`: the `jpar` Ok type is polymorphic so it threads `?` through wrapping functions, and runtime iteration only succeeds when the JSON happens to be an array.
### URL and base64url encoding
Token-cheap primitives for OAuth, JWT, and webhook-signature workflows. All four are tree-bridge eligible: pure text-in / text-out with no I/O and no FnRef args, so the VM and Cranelift backends inherit them automatically.
`urlenc s > t` percent-encodes per RFC 3986. The unreserved set (`ALPHA` / `DIGIT` / `-` / `.` / `_` / `~`) passes through literally; every other byte is emitted as `%HH`. Multi-byte UTF-8 is encoded byte-by-byte.
`urldec s > R t t` is the inverse. It returns `Err` on a stray `%` not followed by two hex digits, or on decoded bytes that aren't valid UTF-8.
`b64u s > t` base64url-encodes the UTF-8 bytes of `s` using the URL-safe alphabet (RFC 4648 §5: `-` and `_` substituted for `+` and `/`) with padding stripped.
`b64u-dec s > R t t` is the inverse. It returns `Err` on input that contains characters outside the base64url alphabet, on `=` padding (the encode side strips padding, so the decode side rejects it for a strict round-trip), or on decoded bytes that aren't valid UTF-8.
```ilo
urlenc "a b&c=d" -- "a%20b%26c%3Dd"
urldec! "a%20b%26c%3Dd" -- "a b&c=d"
b64u "{\"alg\":\"HS256\",\"typ\":\"JWT\"}" -- "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
b64u-dec! (b64u "hello, world!") -- "hello, world!"
```
Both decoders return `Result` so malformed input surfaces typed at the boundary; both encoders are total. Use `!` to auto-unwrap inside an `R`-returning function, or pattern-match on the Result to handle the Err arm explicitly.
### Bitwise ops
`band`, `bor`, `bxor`, `bnot`, `bshl`, `bshr`, `brot` are the bitwise builtin cluster (ILO-58 MVP). All operate on `f64` values via `u32` mod 2^32 conversion and return `f64`. This bridges the crypto-track gap without introducing a new integer type.
| builtin | signature | description |
|---------|-----------|-------------|
| `band x y` | `n n > n` | bitwise AND |
| `bor x y` | `n n > n` | bitwise OR |
| `bxor x y` | `n n > n` | bitwise XOR |
| `bnot x` | `n > n` | bitwise NOT (32-bit: all 32 bits flipped) |
| `bshl x n` | `n n > n` | logical shift left (shift amount mod 32) |
| `bshr x n` | `n n > n` | logical shift right (shift amount mod 32) |
| `brot x n` | `n n > n` | rotate left 32-bit (rotate count mod 32) |
All inputs are converted to `u32` via `(x as i64) as u32`, which gives mod 2^32 truncation for positive values. Shift and rotate counts are taken mod 32 so out-of-range amounts don't panic. All seven are tree-bridge eligible — VM and Cranelift inherit through the bridge without new opcodes.
```ilo
band 12 10 -- 8 (0b1100 & 0b1010)
bor 12 10 -- 14 (0b1100 | 0b1010)
bxor 12 10 -- 6 (0b1100 ^ 0b1010)
bnot 0 -- 4294967295 (all 32 bits set)
bshl 1 4 -- 16
bshr 256 3 -- 32
brot 1 1 -- 2
brot 1 31 -- 2147483648 (bit 31 set)
```
Note: these ops use 32-bit semantics for portability across platforms. Values above 2^32 are truncated. For full 64-bit bitwise math see `band64` and friends below.
---
### Bitwise ops (64-bit)
`band64`, `bor64`, `bxor64`, `bnot64`, `bshl64`, `bshr64`, `brot64` are the 64-bit bitwise builtin cluster (ILO-395). Same shape as the 32-bit cluster but mask inputs to `u64` instead of `u32`.
**Precision note:** `f64` can exactly represent integers up to 2^53. Operations on values >= 2^53 may lose precision on the `f64`↔`u64` round-trip. Powers of 2 up to 2^63 are always exact. Keep inputs within safe range when precision matters.
| builtin | signature | description |
|---------|-----------|-------------|
| `band64 x y` | `n n > n` | bitwise AND (64-bit) |
| `bor64 x y` | `n n > n` | bitwise OR (64-bit) |
| `bxor64 x y` | `n n > n` | bitwise XOR (64-bit) |
| `bnot64 x` | `n > n` | bitwise NOT (64-bit: all 64 bits flipped) |
| `bshl64 x n` | `n n > n` | logical shift left (shift amount mod 64) |
| `bshr64 x n` | `n n > n` | logical shift right (shift amount mod 64) |
| `brot64 x n` | `n n > n` | rotate left 64-bit (rotate count mod 64) |
All inputs are converted to `u64` via `(x as i64) as u64`. Shift and rotate counts are taken mod 64. All seven are tree-bridge eligible — VM and Cranelift inherit through the bridge without new opcodes.
```ilo
band64 12 10 -- 8
bor64 12 10 -- 14
bxor64 12 10 -- 6
band64 (bnot64 0) 255 -- 255 (low 8 bits of all-ones)
bshl64 1 33 -- 8589934592 (2^33, within 2^53 safe range)
bshr64 8589934592 33 -- 1
brot64 1 1 -- 2
bshr64 (brot64 1 63) 63 -- 1 (rotate left 63 then right 63 round-trips)
```
---
### Crypto primitives
`sha256`, `sha256-hex`, `sha256d`, `hmac-sha256`, `b64`, `b64-dec`, `hex`, `hex-rev`, `ct-eq` form the crypto-primitives cluster — the path agents need for webhook signature verification, JWT signing, Bitcoin Merkle tree computation, endian conversions, and any time a secret is compared to a known value. All are tree-bridge eligible so VM and Cranelift share the tree interpreter's semantics.
`sha256 s > t` returns the SHA-256 digest of the UTF-8 bytes of `s` as a lowercase hex string (64 chars). Total — no error path. NIST FIPS-180 anchor: `sha256 ""` = `e3b0c4...b855`.
`sha256-hex h > t` decodes `h` as a hex string and returns the SHA-256 digest of the raw bytes as lowercase hex (64 chars). Use when you need to hash binary data that is represented in hex — wire format keys, Bitcoin script pushdata, arbitrary byte sequences. Errors (ILO-R009) on odd-length or non-hex input. For ASCII input, `sha256-hex (hex s)` agrees with `sha256 s`.
`sha256d h > t` applies double-SHA256 (`sha256(sha256(h))`) over the hex-decoded bytes of `h`, returning lowercase hex. This is the Bitcoin Merkle tree protocol shape: pairs of 32-byte txids are concatenated and double-hashed to produce each parent node. Errors (ILO-R009) on odd-length or non-hex input. `sha256d h` is exactly `sha256-hex (sha256-hex h)` but provided as a named builtin because the double-hash pattern is idiomatic in crypto protocols and the composition is easy to transpose incorrectly.
`hmac-sha256 key:t msg:t > t` returns the HMAC-SHA256 of `msg` under `key`, lowercase hex (64 chars). Any key length is accepted (HMAC handles padding internally). Pair with `ct-eq` to verify signatures without leaking timing info through `=`.
`b64 s > t` encodes the UTF-8 bytes of `s` as standard base64 with `=` padding (RFC 4648 §4). Distinct from `b64u`: standard alphabet (`+`/`/`) and padded vs URL-safe (`-`/`_`) and stripped. `b64-dec s > R t t` is the inverse and returns `Err` on input outside the standard alphabet or on decoded bytes that aren't valid UTF-8.
`hex s > t` encodes the UTF-8 bytes of `s` as a lowercase hex string. Every byte becomes exactly two chars, so `len (hex s)` is `2 * len s` for ASCII input.
`hex-rev s > t` reverses the byte order of a hex-encoded string by swapping adjacent byte-pairs. Input must have even length (2 chars = 1 byte); odd-length input errors `ILO-T013` with a padding hint. Case is preserved: `"abCD"` reversed is `"CDab"`. Primary use case: Bitcoin txids are stored in wire little-endian order but displayed big-endian — `hex-rev txid` converts between the two. Double reversal is identity: `hex-rev (hex-rev s) == s`.
```ilo
hex-rev "12345678" -- "78563412" (4-byte little→big endian)
hex-rev "deadbeef" -- "efbeadde"
hex-rev "" -- "" (empty is fine)
```
`ct-eq a:t b:t > b` is constant-time text equality. A naive `=` short-circuits on the first differing byte, leaking the prefix length through timing; `ct-eq` always scans the full byte range when lengths match, so a timing attacker can't binary-search the secret one byte at a time. Use it whenever you're comparing HMAC digests, session tokens, or API keys. Different-length inputs short-circuit to `false` — length isn't secret in any realistic protocol (HMAC digests are fixed-size).
```ilo
-- HMAC verification (the canonical use case)
sig=hmac-sha256 secret payload -- compute expected MAC
ct-eq sig signature-from-request -- true iff request was signed with secret
-- SHA-256 fingerprint of a file's contents
fp=sha256 (rd "config.json")! -- 64 hex chars
-- Base64 round-trip
b64 "Ma" -- "TWE=" (1 padding char)
b64-dec! "TWE=" -- "Ma"
-- Hex encode
hex "abc" -- "616263"
-- Raw-bytes SHA-256 (same result as sha256 for ASCII input)
sha256-hex "616263" -- ba7816...15ad (= sha256 "abc")
-- Bitcoin Merkle root of two txids (internal byte order, concatenated)
sha256d (+ tx1 tx2) -- double-SHA256 of the 64-byte pair
```
`b64-dec` returns `Result` so malformed input surfaces typed at the boundary; `sha256-hex` and `sha256d` raise ILO-R009 on invalid hex; the remaining encoders and `ct-eq` are total.
---
## Lists
```
xs=[1 2 3] -- space-separated (preferred)
xs=[1, 2, 3] -- commas also work
mixed=["search" 10] -- heterogeneous lists allowed (type: L _)
w="world"
words=["hi" w] -- variables work in list literals
empty=[]
```
Elements are expressions in brackets, separated by spaces or commas. Variables and expressions are allowed as elements. Lists may contain mixed types (inferred as `L _`). Use with `@` to iterate:
```
@x xs{+x 1}
```
The binding's type is inferred from the list's element type; record-field access works on typed lists (`xs:L Rec`) without annotation, e.g. `@e errs{e.path}` over `errs:L Err` resolves `e.path` against the `Err` record. Lists typed `L _` (e.g. `jpar!` results) bind the element as `_` and `.field` access stays Unknown-typed, surfacing the usual diagnostic at the call site that consumes it.
Index by integer literal or variable (dot notation):
```
xs.0 # first element (literal index)
xs.2 # third element (literal index)
xs.i # i-th element when `i` is a bound variable in scope
```
The variable-index form `xs.i` is sugar for `at xs i` - the parser builds
a field-access node and a post-parse desugar pass rewrites it whenever the
field identifier resolves to a binding in scope (parameter, let, foreach,
range, match-arm). Record field access keeps working: if the identifier is
also a declared field on any record type in the program, the rewrite is
skipped and the strict `.field` semantics apply.
**CLI list arguments:** Pass lists from the command line with commas (brackets also accepted):
```
ilo 'f xs:L n>n;len xs' 1,2,3 → 3
ilo 'f xs:L t>t;xs.0' 'a,b,c' → a
```
---
## Statements
Guards and conditionals replace `if`/`else if`/`else`. They are flat statements - no nesting, no closing braces to match. There are three forms:
- **Braceless guard** (`cond expr`): early return - if condition is true, returns the expression from the function.
- **Braced conditional** (`cond{body}`): conditional execution - if condition is true, body runs but execution continues (no early return). Use `ret` inside the body for explicit early return.
- **Ternary** (`cond{then}{else}`): value expression - evaluates then or else branch, no early return.
Multiple braceless guards chain vertically for guard clauses, keeping indentation depth constant.
Match replaces `switch`. There is no fall-through - each arm is independent. The `_` arm is the default catch-all.
| Form | Meaning |
|------|---------|
| `x=expr` | bind |
| `_=expr` | explicit discard — evaluate `expr` for side effects, result dropped. Suppresses ILO-T033 so `_=mset m k v` or `_=+=xs v` is not flagged as an accidental discard. |
| `cond{body}` | conditional execution: run body if cond true (no early return) |
| `cond expr` | braceless guard: early return expr if cond true |
| `cond{then}{else}` | ternary: evaluate then or else (no early return) |
| `?bool{then}{else}` | bare-bool ternary: `?h{1}{0}` (no early return) |
| `?cond then else` | prefix ternary: `?=x 0 10 20` (no early return) |
| `?h cond a b` | general prefix-ternary keyword: `?h cn "y" "n"` (3 operand atoms after literal `?h`) |
| `!cond{body}` | negated conditional execution (no early return) |
| `!cond expr` | braceless negated guard (early return) |
| `!cond{then}{else}` | negated ternary |
| `?x{arms}` | match named value |
| `?fn args{arms}` | match the result of a call inline: `?safe-div a b{~v:...;^e:...}` (parens optional - `?(fn args){arms}` equivalent) |
| `?{arms}` | match last result |
| `@v list{body}` | iterate list |
| `@i a..b{body}` | range iteration: i from a (inclusive) to b (exclusive) |
| `ret expr` | early return from function |
| `~expr` | return ok |
| `^expr` | return err |
| `func! args` | call + auto-unwrap Result, propagate Err to caller |
| `func!! args` | call + auto-unwrap Result, abort on Err with exit 1 |
| `wh cond{body}` | while loop |
| `brk` / `brk expr` | exit enclosing loop (optional value) |
| `cnt` | skip to next iteration of enclosing loop |
| `expr>>func` | pipe: pass result as last arg to func |
---
## Match Arms
| Pattern | Meaning |
|---------|---------|
| `"gold":body` | literal text |
| `42:body` | literal number |
| `~v:body` | ok - bind inner value to `v` |
| `^e:body` | err - bind inner value to `e` |
| `n v:body` | number - branch if value is a number, bind to `v` |
| `t v:body` | text - branch if value is text, bind to `v` |
| `b v:body` | bool - branch if value is a bool, bind to `v` |
| `l v:body` | list - branch if value is a list, bind to `v` |
| `_:body` | wildcard, binds matched subject to `_` |
Arms separated by `;`. First match wins.
**Gotcha (ILO-P011, ILO-461):** `?bool{body}` reads as match-on-bool, *not* a bool-conditional. The brace contents are parsed as pattern arms, so `?fits{io}` chokes on `io` because it isn't a `true:` / `false:` arm. There is no special bool-conditional reading of `?bool{...}` — one shape per construct (P2). For a bool condition pick the canonical form: guard `=bool true body` (early-return / short value), braced-conditional `=bool true{body}` (or negated `!bool{body}`), prefix ternary `?bool a b` / brace ternary `?bool{a}{b}` (value), or explicit match `?bool{true:a; false:b}`.
**Exhaustiveness.** Matches on closed sum-shaped types must cover every variant or include `_:`. For a `R T E` subject, `~v: + ^e:` is exhaustive on its own - no `_:` wildcard required (verifier rule, mirrors `S`-typed matches). For a `b` (bool) subject, `true: + false:` is exhaustive. For numbers and text, `_:` is required.
```
parse>t;r=num "3.14";?r{~v:str v;^e:e} -- canonical two-arm Result match
```
Zero-arg user functions called bare in a value position auto-expand to a call, so `r=mk` where `mk>R t t;...` makes `r` the Result, not a function reference.
In any binding position the name `_` is permitted and binds normally - `~_:body`, `^_:body`, `n _:body` etc. expose the matched inner value to `body` under the name `_`. Bodies that don't reference `_` are unaffected.
```
cls sp:n>t;>=sp 1000 "gold";>=sp 500 "silver";"bronze"
```
### Braceless Guards (Early Return)
When the guard condition is a comparison or logical operator (`>=`, `<=`, `>`, `<`, `=`, `!=`, `&`, `|`) and the body is a single expression, braces are optional. **Braceless guards cause early return from the function:**
```
cls sp:n>t;>=sp 1000 "gold";>=sp 500 "silver";"bronze"
```
Negated braceless guards also work: `!<=n 0 ^"must be positive"`.
**Comparison operators always start a guard at statement position.** You cannot use `=`, `<`, `>`, `<=`, `>=` etc. as a standalone return expression - the parser treats them as a guard condition and expects a following return value. To return a comparison result, bind it first:
```
-- WRONG: r=has xs v;=r true -- =r true is parsed as a guard, not a return expression
-- OK: r=has xs v;r -- return the bool directly (only safe as the last statement)
-- OK: has xs v -- bare call is safe as last statement in last function
```
### Braced Conditionals (No Early Return)
A braced guard `cond{body}` is **conditional execution** - the body runs if the condition is true, but execution always continues to the next statement (no early return):
```
f x:n>n;>x 0{99};+x 1 -- {99} runs when x>0 but is discarded; always returns +x 1
```
This makes braced conditionals natural in loops:
```
f xs:L n>n;m=0;@x xs{>x m{m=x}};m -- find max: update m when x > m
```
Use `ret` inside a braced conditional for explicit early return:
```
f x:n>n;>x 0{ret x};-x -- return x early if positive, else negate
```
> **Common footgun.** `=cond{val}` reads like "if cond, return val" but it isn't. The braces are conditional execution: `val` is evaluated, discarded, and execution falls through to the next statement. If you want early return, use the braceless form `=cond val` (when val is a single expression) or wrap with `ret` inside the braces: `=cond{ret val}`.
>
> ```
> f x:n>n;=x 1{99};0 -- f 1 → 0 (99 is discarded, falls through)
> f x:n>n;=x 1 99;0 -- f 1 → 99 (braceless guard: early return)
> f x:n>n;=x 1{ret 99};0 -- f 1 → 99 (explicit ret inside braces)
> ```
### Ternary (Guard-Else)
A guard followed by a second brace block becomes a ternary - it produces a value without early return:
```
f x:n>t;=x 1{"yes"}{"no"}
```
Like braced conditionals, ternary does **not** return from the function. Code after the ternary continues executing:
```
f x:n>n;=x 0{10}{20};+x 1 -- always returns x+1, ternary value is discarded
```
Negated ternary: `!=x 1{"not one"}{"one"}`.
**Bare-bool ternary** uses `?` with a bool-valued expression as the condition - no comparison operator required:
```
f h:b>n;?h{1}{0} -- if h then 1 else 0
f x:n>t;c=>x 0;?c{"pos"}{"nonpos"} -- bool from comparison, then ternary
```
This is the natural shape when the condition is already a bool (function param, comparison result, predicate call) and saves the explicit `=h true` step that the `=cond{a}{b}` form would otherwise require. Detected purely by shape: `?subj{a}{b}` where both braces contain a single colon-and-semi-free expression. Match-arm forms (`?x{1:a;2:b;_:c}`, `?h{true:a;false:b}`) are unaffected - the colon or semicolon at the outer brace level routes them to match parsing.
**Prefix ternary** uses `?` with a comparison operator for a fully prefix-style conditional:
```
f x:n>n;?=x 0 10 20 -- if x==0 then 10 else 20
f x:n>n;v=?>x 100 1 0;v -- assign result to v
```
The condition must start with a comparison operator (`=`, `>`, `<`, `>=`, `<=`, `!=`).
**Bare-bool prefix ternary** uses `?` with a bool-valued subject (param, comparison result, predicate call) followed by two operand atoms - the parens-free, brace-free shape:
```
f h:b>n;?h 1 0 -- if h then 1 else 0
f h:b>n;v=?h 1 0;v -- assign result to v
```
This is the cheapest shape when the condition is already a bool - 6 chars for `?h 1 0` vs 8 for the brace form `?h{1}{0}` and 12 for the eq-prefix form `?=h true 1 0`. The match-vs-ternary disambiguator routes `?subj{arms-with-colon-or-semi}` to match parsing, `?subj{a}{b}` to brace bare-bool ternary, and `?subj a b` (two bare operands at the cursor, no leading brace) to bare-bool prefix ternary. `?subj` alone with no following operand still errors the same way as before.
**`?h cond a b` general prefix-ternary keyword** uses the literal subject ident `h` plus three operand atoms - the condition is the first operand and `a`/`b` are the arms, analogous to the `?=`/`?>`/`?<` family of comparison-prefix-ternaries but with the condition as an arbitrary bool-valued atom rather than a comparison expression:
```
f x:n>t;cn=>x 0;?h cn "pos" "nonpos" -- comparison-derived bool as condition
f t:t>t;ok=has ["a" "b" "c"] t;?h ok "yes" "no" -- predicate result as condition
f mn:t>t;cn=(=mn "v40");sc1=?h cn "v4" "v3";sc1 -- in let-RHS
```
The disambiguator is operand count: **two** operand atoms after `?h` keeps the bool-subject reading above (`?h a b` → `if h then a else b`); **three** operand atoms promotes `?h` to the fixed keyword form (`?h cond a b` → `if cond then a else b`). The keyword reading triggers only for the literal ident `h`, so every other bool-named subject (`?ready a b`, `?ok 1 0`, …) keeps the PR #330 semantics regardless of how many operands follow. Use the keyword form when the condition is a more complex bool expression than a single ref and you want the cheapest prefix shape; the brace form `?cond{a}{b}` works too but is two characters longer per occurrence.
**`?h <bare-ref> a b` is the trap.** When the condition is already a bare bool ref the keyword form parses and runs identically to the cheaper bare-bool prefix ternary `?<ref> a b`. The verifier surfaces `ILO-W003` at every keyword-form site whose first operand is a single `Ref`, pointing the agent at the two-character-shorter shape. Motivating shape (ILO-463, `http-keepalive-pool`): `?h reusing 1 0` typechecks and produces the right value, but the canonical write is `?reusing 1 0`. The advisory does not fire when the first operand is a comparison (`?h =x 0 a b`), a call (`?h ok-pred? a b`), or any non-Ref atom — those are the keyword form's legitimate use cases.
Each of the three operand slots accepts the same shapes as a prefix-binop operand - atom, nested prefix operator, or known-arity call. `?h =a b sev sc "NONE"` parses `sev sc` as `Call(sev, [sc])` in the then-slot, so `Call` results don't have to be bound first or paren-grouped (paren form `(sev sc)` still works as an explicit alternative).
**Condition must be `b`.** The verifier rejects (`ILO-T038`) any ternary whose cond doesn't type-check to `b` - number, text, function-ref, `R T E` without unwrap, etc. This catches the silent-truthy family of bugs where a non-bool cond would otherwise always take the then-branch at runtime. If the cond is more complex than a single ref or comparison, bind it first (`c=<expr>;?h c a b`) or use the brace-delimited ternary `?cond{then}{else}`. The original 0.12.0 bug that motivated this check: `?h (> p 0.5) 1 0` parsed the paren-grouped prefix-comparison as a zero-param inline lambda, lifted it into a synthetic decl, and silently always took the then-branch - both layers (parser disambiguator + verifier type-check) are now hardened against the family.
**Branches must share a type.** ILO-T003 fires when the then- and else-branches have different known types. The hint is targeted: for `n` vs `t` it surfaces both directions (`str <num-branch>` to make both text, or `default-on-err (num <text-branch>) <fallback>` to make both number, since `num` returns `R n t`); for any other mismatch (bool vs text, list vs map, two named records, `R T E` vs `n`, …) it suggests restructuring rather than offering a coercion that would just trip ILO-T013. Common restructure shapes: wrap each branch in `[...]`, a record with a tagged field, or `O T` / `R T E` to model the two-shape case explicitly.
### Early Return
`ret expr` explicitly returns from the current function:
```
f x:n>n;>x 0{ret x};0 -- return x early if positive, else 0
f xs:L n>n;@x xs{>=x 10{ret x}};0 -- return first element >= 10
g xs:L n tgt:n>n;@i 0..(len xs){=(at xs i) tgt{ret i}};-1 -- index of first match, else -1
```
Braceless guards provide early return for simple cases. Use `ret` inside braced conditionals when you need early return with more complex logic or inside loops.
**`ret` works from any loop body.** `ret` from inside `@x xs{...}`, `@i a..b{...}`, or `wh cond{...}` returns from the enclosing function directly - no sentinel-flag pattern needed. Use `brk` only when you want to stop the loop and let execution fall through to a post-loop expression (e.g. accumulating a partial result, then computing a final value from it). Example contrast:
```
-- ret: stop and return from the function
find xs:L n tgt:n>n;@x xs{=x tgt{ret x}};-1
-- brk: stop the loop, keep going in the function
count-until xs:L n tgt:n>n;c=0;@x xs{=x tgt{brk};c=+c 1};c
```
### Range Iteration
`@i a..b{body}` iterates `i` from `a` (inclusive) to `b` (exclusive). Both bounds can be atoms, prefix-op expressions, or function calls. The index variable is a fresh binding per iteration; other variables in the body update the enclosing scope:
```
f>n;s=0;@i 0..5{s=+s i};s -- sum 0+1+2+3+4 = 10
f>n;xs=[];@i 0..3{xs=+=xs i};xs -- [0, 1, 2]
f n:n>n;s=0;@i 0..n{s=+s i};s -- dynamic end bound
g xs:L n>n;s=0;@j 0..len xs{s=+s j};s -- call-form bound
h i:n n:n>L n;xs=[];@j +i 2..n{xs=+=xs j};xs -- prefix-op bound
```
### While Loop
`wh cond{body}` loops while condition is truthy:
```
f>n;i=0;s=0;wh <i 5{i=+i 1;s=+s i};s -- sum 1..5 = 15
f>n;i=0;wh true{i=+i 1;>=i 3{ret i}};0 -- ret inside braced guard: early return from loop
```
Variable rebinding inside loops updates the existing variable rather than creating a new binding.
### Break and Continue
`brk` exits the enclosing `wh` or `@` loop. `cnt` skips to the next iteration:
```
f>n;i=0;wh true{i=+i 1;>=i 3{brk}};i -- i = 3
f>n;i=0;s=0;wh <i 5{i=+i 1;>=i 3{cnt};s=+s i};s -- s = 3 (skips i>=3)
```
`brk expr` provides an optional value (currently discarded - the loop result is the last body value before the break).
Both `brk` and `cnt` work inside braced conditionals within loops. Using them outside a loop is a compile-time error (no-op in current implementation).
### Pipe Operator
`>>` chains calls by passing the left side as the last argument to the right side:
```
str x>>len -- desugars to: len (str x)
add x 1>>add 2 -- desugars to: add 2 (add x 1)
f x>>g>>h -- desugars to: h (g (f x))
```
Pipes desugar at parse time - no new AST node. Works with `!` for auto-unwrap: `f x>>g!>>h`.
### Safe Field Navigation
`.?` is the tolerant field accessor. It returns nil whenever the access can't
yield a real value, instead of erroring:
- object is nil → nil
- object is a present record but the field is missing → nil
- object is not a record at all (list, text, number) → nil
```
user.?name -- nil if user is nil, else user.name (or nil if absent)
user.?addr.?city -- chained: nil propagates through chain
x.?name??"unknown" -- combine with ?? for defaults
r.?optMetric.?v40 -- heterogeneous JSON (jpar): optional fields stay nil
```
Strict `.field` access still errors on missing fields, so typo detection on
user-defined record types survives at verify time (ILO-T019) and at runtime
(ILO-R005). Use `.field` when you want the strictness, `.?field` when the
field is optional or the record shape is dynamic.
### Nil-Coalesce Operator
`??` evaluates the left side; if nil, evaluates and returns the right side:
```
x??42 -- if x is nil, returns 42
a??b??99 -- chained: first non-nil wins, else 99
mk 0??"default" -- works with function results
```
Compiled via `OP_JMPNN` (jump if not nil) - right side is only evaluated when left is nil.
Use braces when the body has multiple statements:
```
>=sp 1000{a=classify sp;a}
```
```
?r{^e:^+"failed: "e;~v:v}
```
---
## Calls
Positional args, space-separated, no parens:
```
get-user uid
send-email d.email "Notification" msg
charge pid amt
```
### Paren-form call syntax (ILO-51)
Agents trained on Python/JS/Rust/TS often reach for parentheses by reflex. ilo accepts paren-form calls as sugar — both forms produce identical AST nodes:
```
spl(row, ",") -- same as: spl row ","
abs(x) -- same as: abs x
f(a, b, c) -- same as: f a b c
f(g(x), h(y)) -- nested paren-calls also work
```
**Disambiguation rule** — adjacency determines whether `(` starts a paren-call or a grouped-expr argument:
- `f(x)` — `(` immediately adjacent to ident → paren-call: `Call { function: f, args: [x] }`
- `f (x)` — space before `(` → postfix call with `(x)` as a grouped-expr argument (same AST for single-arg; differs for multi-arg where `f (a, b)` would be a parse error)
**Trailing commas are accepted:** `f(a, b,)` is valid (Rust/JS convention).
**Postfix stays canonical.** `ilo fmt` does not rewrite paren-form to postfix; both styles are accepted everywhere.
### Call Arguments
Call arguments can be atoms or prefix expressions:
```
fac -n 1 -- Call(fac, [Subtract(n, 1)])
fac +a b -- Call(fac, [Add(a, b)])
g +a b c -- Call(g, [Add(a,b), c]) - 2 args
fac p -- Call(fac, [Ref(p)])
```
Use parentheses when you need a full expression (including another call) as an argument:
```
f (g x) -- Call(f, [Call(g, [x])])
```
Known-arity calls can also chain directly without parens — the parser consumes exactly the inner call's arity when an ident with a registered arity follows the outer call:
```
abs atan2 1 1 -- Call(abs, [Call(atan2, [1, 1])])
abs rndn 0 0.1 -- Call(abs, [Call(rndn, [0, 0.1])])
abs clamp 5 0 10 -- Call(abs, [Call(clamp, [5, 0, 10])])
pow atan2 1 1 2 -- Call(pow, [Call(atan2, [1, 1]), 2])
```
This works for every builtin and user fn whose arity is known at parse time. If the inner call is variadic or unknown-arity (e.g. `fmt`, custom name with no signature on this side of the file), wrap it in parens to disambiguate.
---
## Records
Named, nominal product types - the structured-data shape (cf. `M k v` maps, which are dynamic and homogeneous). Reach for a record when fields are fixed and statically known; reach for a map when keys are dynamic or the shape varies at runtime.
Define:
```
type point{x:n;y:n}
```
Fields separated by `;`. Each field is `name:type`. Type sigils match the rest of the language (`n`, `t`, `b`, `L n`, `O t`, `M t n`, another record name).
Construct (type name as constructor):
```
p=point x:10 y:20
```
Space-separated `field:value` pairs, no braces, no commas. Constructor arity and field types are checked at verify time (ILO-T021/T022 surface at update sites; ILO-T019 on missing field at access).
Access:
```
p.x -- strict: missing field is verifier error ILO-T019 / runtime ILO-R005
p.?x -- tolerant: nil if field missing, value is nil, or value isn't a record. Returns `O T`. See [Safe Field Navigation].
ord.addr.country -- chains across nested records
```
Records are **nominal**: `type a{x:n}` and `type b{x:n}` are distinct types even though their fields match. A function `f p:point>n` won't accept a `b` value. Pass `_` (Unknown) when you genuinely want to accept any record shape.
The `.field` / `.N` chain also applies to any parenthesised expression, so a call result can be read directly without binding to a name first:
```
(at rows i).2 -- numeric dot-index on a call result
(p with x:30).x -- field access on a record-update
map (i:n>n;(at rs i).2) ixs -- inside an inline lambda body
```
The chain also reattaches to a **multi-token call result without parens** when the trailing `.N` follows a literal arg at the call's last slot. The args loop stops at the leading `.` (Dot doesn't start an operand), and the trailing `.N` is reattached to the call expression rather than dangling:
```
spl "a.b.c" "." .0 -- (spl "a.b.c" ".").0 → "a"
num spl "1.2.3" ".".1 -- num ((spl "1.2.3" ".").1) → 2 (wrapped)
at rows 0 .1 -- (at rows 0).1
```
This is a pure syntax convenience — the runtime sees the same `Expr::Field` shape as the parenthesised form. Caveat: when the call's last arg is a bare ident, the `.N` glues to the ident (field access on the variable, the older shape) rather than the call result. Bind first or wrap in parens in that case: `r=at rows i;r.1` or `(at rows i).1`.
Whitespace between `<atom>` and `.field` is tolerated; both `r.path` and `r .path` parse as field access on `r`, producing identical ASTs. (Contrast with `-`, where whitespace IS load-bearing because `-` is also a binary op and is itself a valid identifier character; `.` has no such ambiguity, so the dot binds unambiguously regardless of surrounding spaces.)
`<atom>.<field>` binds tighter than the surrounding call: in `cat "x" r.path` the `.path` attaches to `r`, not to the `cat` call result.
Destructure:
```
{x;y}=p
```
Binds `x` to `p.x` and `y` to `p.y`. All named fields must exist on the record.
Update:
```
ord with total:fin cost:sh
```
### Display order
`prnt` and `fmt "{}"` render records with fields sorted lexicographically by name, regardless of declared or insertion order. The same rule applies on every engine (tree, VM, Cranelift JIT), so `diff` of stdout across engines is stable and safe for agent self-verification. `jdmp` JSON output already canonicalises keys the same way.
### Field names at dot-access
After `.` or `.?`, the parser accepts any identifier-shaped token as a field name, including:
- **Reserved keywords** - `r.type`, `r.if`, `r.use`, `r.true`, `r.nil`. JSON keys commonly mirror language keywords and dot-access must just work.
- **camelCase** - `r.cvssMetricV31`, `r.userId`. Real-world JSON from APIs is rarely snake_case.
- **Leading uppercase** - `r.Items`, `r.UserName`. PascalCase keys from .NET / Java backends are first-class.
- **snake_case** - `r.type_id`, `r.user_name`.
- **kebab-case** - `r.x-request-id` (requires the leading segment to be an identifier).
These relaxations are scoped to post-dot position only - top-level identifiers still follow the standard naming rules.
---
## Tools (external calls)
```
tool <name>"<description>" <params>><return-type> timeout:<n>,retry:<n>
```
```
tool get-user"Retrieve user by ID" uid:t>R profile t timeout:5,retry:2
```
Tool declarations are verified statically like functions - call sites are type-checked and arity-checked. At runtime, tool calls dispatch through a provider configured via `--tools <config.json>`:
```json
{
"tools": {
"get-user": {
"url": "https://api.example.com/get-user",
"method": "POST",
"timeout_secs": 5,
"retries": 2,
"headers": { "Authorization": "Bearer token" }
}
}
}
```
ilo serialises call arguments as `{"args": [...]}` (JSON array), sends them to the endpoint, and deserialises the response body back to an ilo value. HTTP 2xx → `Ok(response)`, non-2xx → `Err("HTTP <status>: ...")`. Without `--tools`, tool calls return `Ok(_)` (stub behaviour).
**Value ↔ JSON mapping:**
| ilo type | JSON |
|----------|------|
| `n` | number |
| `t` | string |
| `b` | boolean |
| `_` | null |
| `L n` | array |
| `R ok err` | `{"ok": ...}` or `{"err": ...}` |
| record | object |
Tool return type `>t` is the escape hatch - any JSON response is coerced to a text string without parsing.
---
## Imports
Split programs across files with `use`:
```
use "path/to/file.ilo" -- flat import: all declarations (including _-private ones by convention)
use "path/to/file.ilo" [name1 name2] -- selective import: only named public declarations
use alias:"path/to/file.ilo" -- named-module import: public declarations prefixed with alias-
use re:"path/to/file.ilo" [name1 name2] -- re-export: import AND expose those names to consumers
```
**Flat import** merges everything into a shared namespace. Private (`_`-prefixed) declarations come through but are not part of the public interface.
**Selective import** (`[name1 name2]`) imports only the listed names. Requesting a `_`-prefixed name is an error (ILO-P019). Cannot be combined with the `alias:` form.
**Named-module import** (`alias:"path"`) renames all public symbols: a function `dbl` from `use math:"./math-lib"` becomes `math-dbl`. Private (`_`-prefixed) declarations are silently excluded.
**Re-export** (`re:"path" [names]`) imports the listed names and also adds them to this module's public surface so consumers can import them from this module directly. Requires a `[...]` list; `re:` without a list is an error.
```
-- math-lib.ilo
_internal-helper n:n>n; +n 0 -- private — excluded from alias imports
dbl n:n>n; *n 2
half n:n>n; /n 2
-- main.ilo
use "math-lib.ilo" -- flat: dbl, half (and _internal-helper) in scope
use m:"math-lib.ilo" -- named: m-dbl, m-half in scope; _internal-helper excluded
run n:n>n; m-dbl! half n
-- facade.ilo
use re:"math-lib.ilo" [dbl half] -- re-export: dbl and half are part of facade's public API
extra n:n>n; +n 100
-- consumer.ilo
use "facade.ilo" [dbl extra] -- dbl came from math-lib but is visible via re-export
```
### Module privacy
Declarations whose name starts with `_` (underscore, immediately adjacent, e.g. `_helper`) are module-private:
- **Excluded** from named-module imports (`use alias:"path"`) — not prefixed and not available to the importer.
- **Blocked** in selective imports (`use "path" [_name]`) — requesting a private name is ILO-P019.
- **Visible** in flat imports (`use "path"`) — they merge into the shared namespace as a convention; the importer can call them, but they are not considered part of the public API.
Declaring a private function: `_helper-name params:type > return-type; body`
### Rules
- Path is relative to the importing file's directory
- Transitive: if `a.ilo` uses `b.ilo`, `b.ilo`'s declarations are visible to `main.ilo` when it uses `a.ilo`
- Circular imports are an error (`ILO-P018`)
- Named-module form (`alias:"path"`) and selective import (`[...]`) cannot be combined
- Re-export form (`re:"path"`) requires a `[...]` list
- Scoped import with unknown or private name: `ILO-P019`
- `use` in inline code (no file context): `ILO-P017`
### Error codes
| Code | Condition |
|------|-----------|
| `ILO-P017` | File not found or `use` in inline mode |
| `ILO-P018` | Circular import detected |
| `ILO-P019` | Name in `[...]` list not declared in the imported file |
---
## Package Registry
ilo has a lightweight GitHub-based package registry. There is no central server — GitHub is the substrate.
### Installing packages
```
ilo add <owner>/<repo> -- fetch latest default branch
ilo add <owner>/<repo>@<ref> -- fetch a specific branch, tag, or SHA prefix
ilo update -- re-fetch all installed packages
ilo update <owner>/<repo> -- re-fetch one package
```
`ilo add` performs a shallow `git clone` into `~/.ilo/pkgs/<owner>/<repo>/` and writes a line to `ilo.lock` in the current directory.
### Using installed packages
After `ilo add myorg/helpers`, import the package's `index.ilo` with:
```
use "myorg/helpers" -- imports ~/.ilo/pkgs/myorg/helpers/index.ilo
use "myorg/helpers" [foo bar] -- selective import
use "myorg/helpers/utils.ilo" -- import a specific file from the package
```
A `use` path whose first component contains no `.` is treated as a package reference, not a local file path. To import a local file in a sibling directory, use an explicit leading `./`:
```
use "./sibling.ilo" -- always local
use "myorg/helpers" -- always a package
```
### Lockfile (`ilo.lock`)
`ilo add` writes/updates `ilo.lock` in the current working directory. Commit this file to source control.
```
# ilo.lock — generated by `ilo add`; commit to source control
myorg/helpers <sha40> https://github.com/myorg/helpers
```
Format: tab-separated columns `slug`, `sha`, `url`. Lines starting with `#` are comments.
### Non-goals (v1)
- Centralised registry hosting (GitHub is the substrate)
- Semantic versioning enforcement
- Private registry / auth
- Transitive dependency resolution
---
## Error Handling
`R ok err` return type. Call then match:
```
get-user uid;?{^e:^+"Lookup failed: "e;~d:use d}
```
Compensate/rollback inline:
```
charge pid amt;?{^e:release rid;^+"Payment failed: "e;~cid:continue}
```
### Auto-Unwrap `!`
`func! args` calls `func` and auto-unwraps the Result: if `~v` (Ok), returns `v`; if `^e` (Err), immediately returns `^e` from the enclosing function.
```
inner x:n>R n t;~x
outer x:n>R n t;d=inner! x;~d
```
Equivalent to `r=inner x;?r{~v:v;^e:^e}` but in 1 token instead of 12.
Rules:
- The called function must return `R` or `O` (else verifier error ILO-T025)
- The enclosing function must return `R` (or `O` for Optional callees) (else verifier error ILO-T026)
- `!` goes after the function name, before args: `get! url` not `get url!`
- Zero-arg: `fetch!()`
### Panic-Unwrap `!!`
`func!! args` is symmetric in shape with `!`, but on the failure path it aborts the program with a runtime diagnostic and exit code 1 instead of propagating. There is no enclosing-return-type constraint, so persona code can use it from `main>t`, `main>n`, or any non-Result / non-Optional context.
```
main>t;rdl!! "input.txt" -- read file, abort with diagnostic if missing
main>n;v=num!! "42";v -- parse number, abort on parse error
main>n;m=mset mmap "k" 7;mget!! m "k" -- get value or abort if key missing
```
On `^e` (Err) the program writes `panic-unwrap: <Err payload>` to stderr and exits 1. On `O nil` the program writes `panic-unwrap: expected value, got nil`. On `~v` (Ok) or non-nil Optional, the inner value is extracted, identical to `!`.
Rules:
- The called function must return `R` or `O` (else verifier error ILO-T025)
- **No constraint on the enclosing function's return type** - this is the difference from `!`
- `!!` goes after the function name, before args: `rdl!! path` not `rdl path!!`
- Zero-arg: `fetch!!()`
Use `!` when the caller wants to react to the Err (compensate, retry, log). Use `!!` when the failure is a programming or environmental error the caller has no way to recover from - typical in short scripts, glue code, and main entry points.
---
## Patterns (for LLM generators)
### Bind-first pattern
Always bind complex expressions to variables before using them in operators. Operators only accept atoms and nested operators as operands - not function calls.
```
-- DON'T: *n fac -n 1 (fac is an operand of *, not a call)
-- DO: r=fac -n 1;*n r (bind call result, then use in operator)
```
### Recursion template
```
<name> <params>><return>;<guard>;...;<recursive-calls>;combine
```
1. **Guard**: base case returns early - `<=n 1 1` (or `<=n 1{1}`)
2. **Bind**: bind recursive call results - `r=fac -n 1`
3. **Combine**: use bound results in final expression - `*n r`
### Factorial
```
fac n:n>n;<=n 1 1;r=fac -n 1;*n r
```
- `<=n 1 1` - braceless guard: if n <= 1, return 1
- `r=fac -n 1` - recursive call with prefix subtract as argument
- `*n r` - multiply n by result
### Fibonacci
```
fib n:n>n;<=n 1 n;a=fib -n 1;b=fib -n 2;+a b
```
- `<=n 1 n` - braceless guard: return n for 0 and 1
- `a=fib -n 1;b=fib -n 2` - two recursive calls, each with prefix arg
- `+a b` - add results
### Tail-call optimisation
ilo guarantees that **tail calls do not consume host-stack frames**. A function that recurses only in tail position can run to arbitrary depth — the runtime trampolines the call by rebinding parameters in place rather than pushing a frame.
The manifesto's "Constrained" rule (every feature must pay for itself in tokens) vetoed adding a `loop` keyword. Instead, tail-recursive accumulator patterns are the canonical idiom for iteration beyond what `@` foreach covers, and the TCO guarantee makes them safe at any depth.
A call is in **tail position** when its return value is the function's return value: the last statement of the body, the expression of a `ret` statement, an arm of a tail-position `?` match, or the body of a braceless guard. Calls inside `@` foreach, `@` range, `wh` loops, or as operands of further computation are NOT in tail position.
> **Recursive self-call discarded at non-tail position fires `ILO-T043`.** When a function calls itself before another statement runs, the recursive return is silently dropped — every call falls through to the later statements. The verifier emits `ILO-T043` with a hint pointing at the tail-position fix (move the recursive call to the body's last statement, wrap it in `ret`, or restructure via `?h cond then else`). The warning is narrowly scoped to self-calls (caller name == callee name); bare non-recursive user-fn calls at non-tail position may be side-effecting and do not warn. Surfaced 2026-05-21 by the interp1d persona: see `examples/recursive-tail-position.ilo` for the canonical fix shape.
```
-- Tail-recursive countdown — runs to arbitrary depth.
count-down n:n>n;=n 0 0;count-down -n 1
-- Tail-recursive accumulator — sums a list without growing the host stack.
sum-acc xs:L n acc:n>n;empty=len xs;=empty 0 acc;sum-acc tl xs +acc hd xs
```
Constraints on the tail-call peephole:
- The callee must be a direct user-defined function name (not a FnRef in scope, not a closure, not a builtin, not a tool).
- The call must have no auto-unwrap (`!` / `!!`) — those forms inspect the result before deciding whether to propagate.
These constraints leave the common shapes (recursive accumulators, state machines, mutual recursion via direct names) covered. Other shapes still recurse the host stack as before; for deep recursion through non-tail-eligible shapes, restructure into an accumulator.
Tree interpreter and bytecode VM (`--vm`) support shipped in 0.12.x; the VM emits `OP_TAILCALL` for tail-position user-fn calls and reuses the current call frame instead of pushing a new one, so depth is bounded only by available heap. Cranelift (`--jit`, AOT) gains matching `return_call` lowering in a subsequent PR; until then, deep tail-recursion under the JIT/AOT path recurses the host stack and is bounded by it.
### Multi-statement bodies
Semicolons separate statements. Last expression is the return value.
```
f x:n>n;a=*x 2;b=+a 1;*b b -- (x*2 + 1)^2
```
Bodies may also be written across multiple newline-separated lines, indented under the signature. The parser stays inside the same function body while it sees an open bracket (`[`, `(`, `{`) or a pipe operator continuation. This makes long literals and multi-line conditional pipelines readable without semicolons:
```
f x:n>n
a=*x 2
b=+a 1
*b b
g>L n
[10, 20, 30, 40,
50, 60, 70, 80]
```
Statement separation reverts to standard rules once brackets close. A blank line ends the current declaration.
Windows CRLF (`\r\n`) is normalised to `\n` before lexing, so files edited on Windows parse identically to Unix-line-ending files.
### Multi-function files
Functions in a file are separated by **newlines**. The parser strips all newlines, so the token stream is flat. After parsing each function body, the parser uses the next newline-delimited boundary to start the next declaration.
A non-last function body's **final expression must not be a bare variable reference (`Ref`) or a function call**, because the parser greedily reads following tokens as additional call arguments. Safe endings prevent this:
| Ending | Example | Safe? | Why |
|--------|---------|-------|-----|
| Binary operator | `+n 0`, `*x 1` | ✓ | fixed arity - no greedy loop |
| Index access | `xs.0`, `rec.field` | ✓ | returns `Expr::Index`, not `Ref` |
| Match block | `?v{…}` | ✓ | ends with `}` |
| ForEach block | `@x xs{…}` | ✓ | ends with `}` |
| Parenthesised expr | `(x>>f>>g)` | ✓ | ends with `)` |
| Record constructor | `point x:1 y:2` | ✓ | parses as `Expr::Record`, not `Ref` |
| Text/number literal | `"ok"`, `42` | ✓ | literal, not `Ref` |
| Bare variable (`Ref`) | `n`, `result` | ✗ | greedy loop fires |
| Bare function call | `len xs`, `f a` | ✗ | greedy loop fires |
The **last function in a file** can end with anything - greedy parsing stops at EOF.
```
-- Non-last functions: end with a binary expression
digs n:n>n;t=str n;l=len t;+l 0 -- +l 0 = l (binary, safe)
clmp n:n lo:n hi:n>n;<n lo lo;>n hi hi;+n 0 -- +n 0 = n (binary, safe; `clamp` is a builtin)
-- Last function: bare call is fine
sz xs:L n>n;len xs -- EOF - greedy loop stops naturally
```
To use a pipe chain in a non-last function, wrap it in parentheses:
```
dbl-inc x:n>n;(x>>dbl>>inc) -- parens prevent >> from consuming next function's name
inc-sq x:n>n;x>>inc>>sq -- last function - no parens needed
```
### DO / DON'T
```
-- DON'T: fac n:n>n;<=n 1 1;*n fac -n 1
-- ↑ *n sees fac as an atom operand, not a call
-- DO: fac n:n>n;<=n 1 1;r=fac -n 1;*n r
-- ↑ bind-first: call result goes into r, then *n r works
-- DON'T: +fac -n 1 fac -n 2
-- ↑ + takes two operands; fac is just an atom ref
-- DO: a=fac -n 1;b=fac -n 2;+a b
-- ↑ bind both calls, then combine
```
---
## Error Diagnostics
ilo verifies programs before execution and reports errors with stable codes, source context, and suggestions.
### Error codes
Every error has a stable `ILO-<letter><digits>` code. The letter is the
namespace - the phase that raised the diagnostic - so agents and tools
can route on prefix without parsing the message. Numeric ranges are
reserved per namespace with generous gaps, so future codes slot in
cleanly and the contract is forward-compatible.
| Range | Letter | Area | Status |
|----------------|--------|-------------------------------|----------|
| `ILO-L000-099` | L | Lexer / tokenisation | active |
| `ILO-P100-199` | P | Parser / syntax | active |
| `ILO-N200-299` | N | Names / resolution | reserved |
| `ILO-I300-399` | I | Imports | reserved |
| `ILO-T400-499` | T | Types | active |
| `ILO-V500-599` | V | Verifier (post-type checks) | reserved |
| `ILO-R600-699` | R | Runtime | active |
| `ILO-D700-799` | D | Deprecation warnings | reserved |
| `ILO-E800-899` | E | Engine-specific limitations | reserved |
| `ILO-S900-999` | S | Skill / spec system | reserved |
**Historical codes.** ilo shipped with flat numbering inside each
namespace - `ILO-L001`, `ILO-P001`, `ILO-T001`, `ILO-R001`, `ILO-W001`,
all starting at 001. Those codes remain valid forever. The hundreds-block
allocation above applies to new codes from now on, and a cross-engine
regression test asserts every emitted code lives in a documented range.
**Reserved namespaces.** `N`, `I`, `V`, `D`, `E`, `S` carry no codes
today. They are forward declarations so the first code in each category
slots into its own range without conflicting with the active namespaces.
`D` is earmarked for deprecation warnings: when a feature is scheduled
for removal it emits an `ILO-D7xx` warning at compile time without
failing the build.
Use `--explain` to see a detailed explanation:
```
ilo --explain ILO-T004
```
### Source context
Errors point at the relevant source location with a caret:
```
error[ILO-T005]: undefined function 'foo' (called with 1 args)
--> 1:9
|
1 | f x:n>n;foo x
| ^^^^^
|
= note: in function 'f'
= suggestion: did you mean 'f'?
```
Parser, verifier, and runtime errors all show source spans. The verifier uses the enclosing statement span as the best available location for expression-level errors.
### Suggestions
The verifier provides context-aware hints:
- **Did you mean?** - Levenshtein-based suggestions for undefined variables, functions, fields, and types
- **Type conversion** - suggests `str` for n→t, `num` for t→n
- **Missing arms** - lists uncovered match patterns with types
- **Arity** - shows expected parameter signature
### Error output formats
```
--ansi / -a ANSI colour (default for TTY)
--text / -t Plain text (no colour)
--json / -j JSON (default for piped output)
--no-hints / -nh Suppress idiomatic hints
--silent / -s Suppress program stdout (mainly for --bench; see below)
NO_COLOR=1 Disable colour (same as --text)
```
**`--silent` / `-s`.** Suppresses the program's own stdout (`prnt`, `prnv`, `jprn`, etc.) for the duration of execution. Designed for `ilo <file> --bench`: combined with `--json` it lets agent harnesses (e.g. persona cost rollup) consume the bench JSON envelope on stdout without it being drowned in the benchmarked function's own output. Stderr is never silenced, so genuine errors still surface. Diagnostic output (including the bench JSON envelope and the human-readable bench summary block) is always emitted on stdout regardless of `--silent` — the flag only redirects program-level prints. Unix only (no-op on Windows for the program-stdout half; bench output still reaches stdout there).
JSON error output follows a structured schema with `severity`, `code`, `message`, `labels` (with spans), `notes`, and `suggestion` fields.
Runtime errors raised from the Cranelift JIT (opt-in via `--jit`) populate `labels` with the source span of the failing operation, matching tree and VM behaviour. Span coverage threads through every JIT runtime helper (unwrap, panic-unwrap, list-get, slice, index, jpth, mget, record-field strict access, builtin dispatch, dynamic call); AOT-compiled binaries inherit the same coverage. Pre-v0.11.6 builds surfaced `{"labels":[]}` for these shapes - if you see an empty labels array on a runtime error, the binary is out of date.
AOT binaries also install an async-signal-safe handler in `ilo_aot_init` that catches fatal signals (SIGSEGV, SIGBUS, SIGFPE, SIGILL, SIGABRT) and writes a single JSON line on stderr identifying the signal before the process terminates with the conventional 128+signo exit code. The diagnostic uses `ILO-R015` (AOT runtime fault). Without the handler, a hard fault inside compiled native code would leave the process with raw signal exit (e.g. 139 for SIGSEGV) and no diagnostic — agents driving ilo couldn't distinguish a clean non-zero exit from a hard fault. A SIGSEGV from an AOT binary is always a bug in ilo (codegen or runtime helper); file an issue with the source program and the JSON line.
AOT binaries also install an async-signal-safe handler in `ilo_aot_init` that catches fatal signals (SIGSEGV, SIGBUS, SIGFPE, SIGILL, SIGABRT) and writes a single JSON line on stderr identifying the signal before the process terminates with the conventional 128+signo exit code. The diagnostic uses `ILO-R015` (AOT runtime fault). Without the handler, a hard fault inside compiled native code would leave the process with raw signal exit (e.g. 139 for SIGSEGV) and no diagnostic — agents driving ilo couldn't distinguish a clean non-zero exit from a hard fault. A SIGSEGV from an AOT binary is always a bug in ilo (codegen or runtime helper); file an issue with the source program and the JSON line.
### Top-level program output
For a program whose entry function returns a Result, the `~`/`^` wrapper is split across streams and exit codes so shell callers do not have to strip a prefix:
| Top-level return | Plain stdout | Plain stderr | Exit |
| --- | --- | --- | --- |
| `~v` (Ok) | `v` (bare) | - | 0 |
| `^e` (Err) | - | `^e` | 1 |
| any non-Result | `v` | - | 0 |
In `--json` mode the value is always wrapped (`{"schemaVersion": 1, "ok": v}` / `{"schemaVersion": 1, "error": {...}}`) and emitted to stdout; exit codes match the plain-mode table. The `schemaVersion` field was added in 0.12.1 to every CLI `--json` envelope (`run`, `graph`, `--ast`, `serv`, `tools --json`, `spec --json`) so agents can route on a single field across every command. See `JSON_OUTPUT.md` for the full audit table.
**`-j` short alias (ILO-442).** Every subcommand that accepts `--json` also accepts the `-j` short form with identical behaviour: `ilo check -j file.ilo`, `ilo run -j 'code'`, `ilo spec -j ai`, `ilo skill -j list`, `ilo tools -j --mcp m.json`, `ilo version -j`, `ilo explain -j ILO-T001`, `ilo build -j prog.ilo`, etc. Manifesto P6 (every subcommand has `--json`) plus terser invocations for agent prompts.
`Display` on `Value::Ok` / `Value::Err` still renders `~v` / `^e` in every other context (nested values, `prnt`, REPL prompts, error messages, debug output) - only the top-level program-return print path is split.
The contract applies uniformly to in-process runners (`ilo prog.ilo`, `--vm`, `--jit`) and to AOT-compiled standalone binaries from `ilo compile`. Both strip the top-level `~`/`^` wrapper on stdout, route `^e` to stderr, and use the same exit codes - output is byte-for-byte identical across every backend.
**Auto-echo suppression for `prnt` + status sentinel.** When the entry function has at least one *unconditional top-level* `prnt` call AND the tail expression is a bare wrapped string literal (`~"text"` or `^"text"`), the top-level auto-echo is suppressed. The wrapped literal is treated as a status sentinel rather than a value the caller wants captured. Without this rule, a function shaped like `m>R t t;prnt "report";~"ok"` emits `report\nok\n` on stdout and shell callers piping the output have to strip the trailing `ok`. The rule does NOT fire when (a) there is no `prnt` in the body — `m>R t t;~"ok"` still prints `ok` because the wrapped literal IS the program's output (the `cli-tasks-save-ok.ilo` pattern); (b) the `prnt` is nested inside a guard, loop, or match arm — those are conditional and the `prnt` may never run; (c) the tail is `~v` where `v` is a binding or call — that's a real return value. `^"text"` errors still go to stderr with exit 1; the suppression rule never silently swallows an Err. Pinned by `tests/regression_tilde_str_noecho.rs` and `examples/tilde-str-noecho.ilo`.
### Idiomatic hints
After successful execution, ilo scans the source for non-canonical forms and emits hints to stderr:
```
hint: `==` → `=` saves 1 char (both mean equality in ilo)
hint: `length` → `len` (canonical short form)
```
Builtin alias hints appear at most once per program (the first long-form name found). In JSON mode, hints appear as `{"hints":["..."]}` on stderr. Suppress with `--no-hints` / `-nh`.
### CLI invocation
```
ilo 'code' [args...] -- inline program; default-runs the entry function
ilo program.ilo [func] [args] -- if `func` is omitted and the file declares exactly
one function, that function runs automatically
ilo run program.ilo [func] [a] -- verb form; same dispatch as the bare positional
ilo check program.ilo [--json|-j] [--strict] -- run the verifier without executing (exit 0 = clean; --strict treats warnings as exit-code errors)
ilo test [path] [--engine vm|jit|all] -- run `-- run:` / `-- out:` / `-- err:` assertions in .ilo files (exit 0 on all-pass, 1 on any failure)
ilo build program.ilo -o out -- AOT compile to a standalone binary (alias for `compile`)
ilo run program.ilo --emit js -- transpile to JavaScript and print to stdout (PR #713, ILO-73)
ilo run program.ilo --emit python -- transpile to Python and print to stdout
ilo program.ilo --ast -- print parsed AST as JSON and exit
ilo --explain ILO-T004 -- print error explanation and exit
ilo help ai -- compact AI spec to stdout (= contents of ai.txt)
ilo serv -- long-lived JSON request/response loop
ilo httpd handler.ilo [--port N] -- HTTP server: calls handler fn per request (default port 8080)
ilo --max-ast-depth N <sub> -- cap parser nesting at N (default 256; protects `ilo serv`
and other untrusted-source paths from DoS payloads, raises ILO-P103)
ilo --max-runtime SECS <sub> -- cap wall-clock runtime at SECS (default 60; 0 disables; raises ILO-R016)
ilo --max-output-bytes BYTES <sub> -- cap stdout output at BYTES (default ~100 MB; 0 disables; raises ILO-R017)
ilo run --allow-net[=HOSTS] <file> -- restrict outbound net to comma-separated hosts (* = all, empty = none)
ilo run --allow-read[=PATHS] <file> -- restrict file reads to comma-separated path prefixes
ilo run --allow-write[=PATHS] <file> -- restrict file writes to comma-separated path prefixes
ilo run --allow-run[=CMDS] <file> -- restrict subprocess spawning to comma-separated command names
```
**Capability flags (`ILO-CAP-001`).** `ilo run --allow-net=HOSTS --allow-read=PATHS --allow-write=PATHS --allow-run=CMDS` gates IO builtins at the process level. Any `--allow-*` flag present switches the runtime from **permissive** (default — no restrictions, full backwards compatibility) to **restricted** (only listed targets are permitted). Denial returns a normal `R` Err value with code `ILO-CAP-001`; programs can pattern-match it. Capability matrix: `get`/`post`/`put`/`patch`/`del`/`fetch` → `--allow-net`; `rd`/`rd-lines`/`ls`/`lsr` → `--allow-read`; `wr`/`wr-lines`/`wr-app` → `--allow-write`; `run`/`run2` → `--allow-run`. Value syntax: omit = unrestricted; `*` = all permitted; empty (`--allow-net=`) = all blocked; comma list = only those targets. Matching: net = hostname extracted from URL, exact or `*.domain` wildcard; read/write = path-prefix with separator boundary; run = basename or full-path match. See `SANDBOX.md` for the operator guide and `examples/capability-sandbox.ilo` for a runnable demo.
**Production-safety guards (`ILO-R016`, `ILO-R017`).** `ilo run` caps wall-clock runtime at 60 s and stdout output at ~100 MB by default. A runaway loop (missing increment, recursion with no base case) aborts with `ILO-R016` once the time budget hits, instead of burning CPU forever; a `prnt` loop without termination aborts with `ILO-R017` once the byte budget hits, instead of filling the agent transcript with megabytes of garbage. Both guards write a structured diagnostic to stderr and exit 1. Defaults are well above any legitimate program (real agent tasks finish under 10 s and produce kilobytes); raise with `--max-runtime SECS` / `--max-output-bytes BYTES`, set either to `0` to disable. The guards were installed by the mandelbrot persona report (2026-05-20) which spun in an infinite loop and wrote 165 MB of stdout before the harness intervened.
**Verb-noun aliases.** `ilo run <file>` is an exact alias for the bare positional `ilo <file>` - same dispatch, same engine selection, same arg handling. `ilo build <file> -o <out>` is an alias for `ilo compile <file> -o <out>`. Both exist to match the toolchain conventions used by `cargo`, `go`, and `zero` so agents and humans can guess the command name without consulting the help text. The bare positional forms remain fully supported for backwards compatibility; nothing has been removed.
**`ilo check`.** Standalone verifier invocation: lex, parse, resolve imports, and run the type verifier without proceeding to bytecode compilation or execution. Exit code 0 means the program is well-typed and verifier-clean; exit code 1 means at least one diagnostic was emitted on stderr. The output mode follows the global flags (`--json` for NDJSON diagnostics, `--text` for plain text, `--ansi` for coloured output; auto-detected when omitted - JSON when stderr is not a TTY, ANSI otherwise). `ilo check` works on both files and inline code; on a syntactically-broken input it still reports the parse error rather than crashing, which is important for editor and agent loops that may feed in half-written programs.
**`ilo test`.** Runs the `-- run: <fn> <args>` / `-- out: <expected>` (or `-- err: <stderr>`) annotations embedded in `.ilo` source files - the same format the in-tree `tests/examples_engines.rs` integration harness already uses. A file path tests that one file; a directory walks `*.ilo` recursively. Each case runs as a subprocess (`ilo <file> --vm <args>`), output is asserted against the expected payload, and the result prints as `PASS path::fn (line N)` / `FAIL path::fn (line N) (got: X, want: Y)`. The final line reports `N passed, M failed`. Exit 0 if everything passed, 1 if any case failed or no annotations were found. The default engine is `--vm`; pass `--engine jit` or `--engine all` to widen the matrix. Per-file `-- engine-skip: vm jit` annotations skip the listed engines, matching the integration harness. Because every example under `examples/` uses this annotation format already, `ilo test examples/` doubles as a smoke test for the language itself and as a worked reference an agent can read when writing tests for its own programs.
**`ilo httpd`.** Starts an HTTP/1.1 server that calls a user-defined ilo handler function for every incoming request. The handler receives a `Request` record and must return a `Response` record (or a bare record with at least `status` and `body` fields). One OS thread is spawned per accepted connection. The handler is loaded once at startup; re-reads require a restart.
```
ilo httpd handler.ilo -- serve on :8080 (default)
ilo httpd --port 3000 handler.ilo -- serve on :3000
ilo httpd handler.ilo myhandler -- call function `myhandler` instead of `handler`
```
Handler signature:
```
-- Request fields injected by ilo httpd at runtime:
-- method:t HTTP verb (GET, POST, ...)
-- path:t request path including query string
-- headers:M t t request headers (keys lowercased)
-- body:t request body (empty string when absent)
--
-- Response fields read by ilo httpd:
-- status:n HTTP status code (200, 404, 500, ...)
-- body:t response body
-- headers:M t t optional response headers
type rsp{status:n;body:t}
handler req:_>rsp
p=req.path
msg=+"Hello! You requested: " p
rsp status:200 body:msg
```
Use `req:_` (wildcard) for the request param type — the `Request` record is created by the ilo httpd runtime and its field types cannot be declared in the handler source without a `type` alias that re-exports them. The dot-access `req.path`, `req.method`, `req.body`, `req.headers` work because ilo resolves record field access by name at runtime. `Content-Type` defaults to `text/plain; charset=utf-8` when not set in the response headers map. Distinct from `ilo serv` (which speaks the agent-protocol JSON-RPC loop); `httpd` is for user-facing HTTP traffic.
The handler file's `use` imports are resolved at startup, relative to the handler's own directory, matching `ilo run` / `ilo check` (ILO-481). A handler can split logic across sibling modules (`use "store.ilo"`) rather than inlining everything. A missing import surfaces a real diagnostic and the server refuses to start.
**`ilo check --strict`.** Treats every warning-severity diagnostic (ILO-T032 bare `fmt`, ILO-T033 bare `mset` / `+=` / `mdel`, ILO-W002 `@x (jpar! …){…}` steering to `jpar-list!`, future warning codes) as a hard exit-code failure. The diagnostic stream itself is unchanged: warnings still emit with `severity: "warning"` in the JSON output, so editor integrations that route by severity stay correct. Only the exit code is elevated. CI harnesses that gate merges on `ilo check` should use `--strict` so warnings can't slip through silently; for interactive use, the default (warnings-are-advisory) is the right behaviour.
**Default-run.** Inline programs (`ilo 'code'`) and single-function files run their entry function with the remaining CLI args; no explicit function name needed. Multi-function files auto-pick a function called `main` when no positional func arg is supplied. The same heuristic applies to the explicit engine flags - `--vm` and `--jit` both auto-pick `main` on multi-fn files, matching the default-engine behaviour. With no `main` declared, supply a function-name argument.
**AOT entry-pick.** `ilo compile file.ilo -o out` (alias `ilo build`) follows the same entry-pick rules as the in-process engines: a single user-defined function is used directly; on multi-function files the entry is `main` if defined, otherwise the explicit positional `func` arg (`ilo compile file.ilo -o out run`); otherwise the compile fails with `ILO-E801` and exits 1 without writing a binary. AOT does not fall back to "first declared function" - that historical default produced binaries that called the wrong entry symbol and SIGSEGV'd at runtime.
**Default engine.** The bytecode register VM is the default execution path. It supports every opcode (closures with Phase 2 capture, listview windows, fused len-of-filter, every modern shape), and avoids the JIT compile-and-bail cost paid by the pre-v0.11.9 Cranelift-first default whenever a program touched an opcode the JIT couldn't handle. Cranelift JIT is opt-in via `--jit`; on opt-in, the JIT runs hot numeric loops and falls back to the VM on bailout. Phase 2 captures run natively on every public backend - VM, JIT, and AOT (`ilo compile`); AOT embeds the postcard `CompiledProgram` blob into the binary's `.rodata` so dispatch helpers can re-enter the VM on user-fn callbacks the same way the in-process runners do. For long-running workloads where the JIT pays for itself, opt in explicitly; for most agent workloads the VM is the right default.
**Tree-walker is internal-only.** The tree-walking interpreter is no longer user-selectable: `--run-tree` and its `--run` alias were removed from the public CLI in 0.12.1 (they now error with the unknown-flag guard). The interpreter stays in-tree as the dispatch target for HOF / regex / fmt-variadic / IO / sleep / ct / rsrt / closure-bind-ctx shapes the VM and Cranelift haven't lifted natively yet - the VM bails to it transparently for the ops listed by `is_tree_bridge_eligible` (`rgx`, `rgxall`, `rgxall1`, `rgxall-multi`, `rgxsub`, `fmt`, `fmt2`, `rd`, `rdb`, `rdjl`, `rdin`, `rdinl`, `for-line`, `sleep`, `lsd`, `walk`, `glob`, `dirname`, `basename`, `pathjoin`, `fsize`, `mtime`, `isfile`, `isdir`, `run`, `env-all`, `jkeys`, `tz-offset`, `ct` 2-arg and 3-arg, `rsrt` 2-arg and 3-arg, `dur-parse`, `dur-fmt`, and the closure-bind ctx variants of `map`/`flt`/`fld`/`srt`). Cross-engine parity for those shapes is pinned by `tests/regression_builtin_bridge.rs` and `tests/regression_tree_bridge_invariants.rs`. 0.13.0+ is on track for a hard drop once the bridge consumers are lifted natively and the shared runtime types (`Value`, `MapKey`, `RuntimeError`, math helpers) are extracted from `src/interpreter/` to a non-engine module.
**Subcommand dispatch.** The first positional argument is interpreted as a function name when it has the shape of an ilo identifier - `[a-z][a-z0-9]*(-[a-z0-9]+)*` - so `ilo file.ilo list-orders` routes to the `list-orders` function. Args that don't match the ident shape (file paths like `/tmp/data.json`, numbers, sigils, bracketed lists, anything with a `.` or `/`) route to `main` (or the entry function) as a positional CLI arg instead. Trailing dashes (`foo-`), doubled dashes (`foo--bar`), and negative numbers (`-1`) are not idents and pass through as data.
**Unknown `--flag` guard.** Any token in the positional tail matching the clean long-flag shape `--word` or `--word-with-dashes` that isn't a recognised flag is rejected upfront with `error: unrecognised flag '--<name>'. Use 'ilo --help' for valid flags. To pass it as a literal arg, separate with '--' first.` and exit 1. This prevents `ilo main.ilo --engine tree` from silently consuming `--engine` as a positional arg (which used to surface as misleading `ILO-R012 no functions defined` or `ILO-R004 main: expected N args, got N+1`). To pass a hyphen-prefixed token through as literal data, place the `--` separator first: `ilo main.ilo -- --foo`. Anything after the first `--` is data. Tokens with `=` (`--key=val`), trailing or doubled dashes (`--foo-`, `--foo--bar`), and negative numbers (`-1`) are not clean flag shapes and pass through unchanged.
**Text-typed params.** When the entry function declares a parameter of type `t`, the CLI passes the raw arg through without numeric coercion. `ilo 'f x:t>t;x' 42` returns the string `"42"`, not the number 42.
**Exit codes.** A program returning `Value::Err` (or `^reason` from the entry function) exits with code 1 and prints the err payload on stderr. `~v` (Ok) and any non-Result return value exit 0. Verifier and parser errors exit 2.
**List args from the CLI.** Comma-separated args become `L n` or `L t` automatically: `ilo 'f xs:L n>n;sum xs' 1,2,3`.
---
## Formatter
Dense output is the default - newlines are for humans, not agents. No flag needed for dense format:
```
ilo 'code' Dense wire format (default)
ilo 'code' --dense / -d Same, explicit
ilo 'code' --expanded / -e Expanded human format (for code review)
```
### Dense format
Single line per declaration, minimal whitespace. Operators glue to first operand:
```
cls sp:n>t;>=sp 1000{"gold"};>=sp 500{"silver"};"bronze"
```
### Expanded format
Multi-line with 2-space indentation. Operators spaced from operands:
```
cls sp:n > t
>= sp 1000 {
"gold"
}
>= sp 500 {
"silver"
}
"bronze"
```
Dense format is canonical - `dense(parse(dense(parse(src)))) == dense(parse(src))`.
---
## Complete Example
```
tool get-user"Retrieve user by ID" uid:t>R profile t timeout:5,retry:2
tool send-email"Send an email" to:t subject:t body:t>R _ t timeout:10,retry:1
type profile{id:t;name:t;email:t;verified:b}
ntf uid:t msg:t>R _ t;get-user uid;?{^e:^+"Lookup failed: "e;~d:!d.verified{^"Email not verified"};send-email d.email "Notification" msg;?{^e:^+"Send failed: "e;~_:~_}}
```
### Recursive Example
Factorial and Fibonacci as standalone functions:
```
fac n:n>n;<=n 1 1;r=fac -n 1;*n r
```
```
fib n:n>n;<=n 1 n;a=fib -n 1;b=fib -n 2;+a b
```
## Stability
See STABILITY.md at repo root for the per-surface stability matrix. Three tiers: stable (schemaVersion:1 envelope, ILO-error-codes, serv-protocol-phases, file-version-pragma, manifesto-principles, reserved-name-policy), provisional (builtin-signatures, cli-flag-names, error-message-prose, examples-corpus, ilo-test-surface), experimental (0.13-in-flight-features, aot-artifact-format, cranelift-jit-internals, extensions-dir, cargo-feature-flags). Stable surfaces are safe to pin across releases. Provisional surfaces carry a deprecation-window guarantee. Experimental surfaces may disappear without notice. `ilo spec --json ai` surfaces this matrix in the `stability` field of the JSON envelope, and per-item stability annotations on every builtin in the `builtins` array.