diff --git a/ai.txt b/ai.txt index 9448b36f..404dcd1c 100644 --- a/ai.txt +++ b/ai.txt @@ -1,17 +1,12 @@ INTRO: 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 `^` only at file start, so `^` elsewhere keeps its `return err` meaning. 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 ` 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: : ...>; 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: explicit braces wrap the whole body (same semantics). 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: `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) `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): ` for payload variants, `tag: ` 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). [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` before the parameter list. Bounds are optional per variable; omitting `:bound` defaults to `any`. gmn x:a y:a>a -- min of two comparable values gadd x:a y:a>a -- addition, numeric values only grep s:a n:n>t -- repeat text gid x:a>a -- identity, any type **Bound set** (small and fixed): `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: `(: ...>;)`. 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) 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. [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: 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. +TYPES: `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): ` for payload variants, `tag: ` 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). [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` before the parameter list. Bounds are optional per variable; omitting `:bound` defaults to `any`. gmn x:a y:a>a -- min of two comparable values gadd x:a y:a>a -- addition, numeric values only grep s:a n:n>t -- repeat text gid x:a>a -- identity, any type **Bound set** (small and fixed): `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: `(: ...>;)`. 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) 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. [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: 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. NAMING: Short names everywhere. 1–3 chars. `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. **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 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`, …) 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: `AND a b`, `OR a b`, `NOT a`=`&a b`, `|a b`, `!a`=`ILO-L001` `=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` `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` `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` `tup.0` / `pair.0` (tuple access)=bind from `zip`-pair, then `at pair 0` (no tuple type)=`ILO-T004` 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 `- - a b c d` for `` 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 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 `) 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 ` 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] `+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`=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] `-x`=negate=`n` `!x`=logical NOT=any (truthy) [Special infix] `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 /*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 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 precedence] Standard mathematical precedence (higher binds tighter): 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: `\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 `{` / `}`, but only inside strings that actually contain at least one `{ident}` slot. Strings with no interpolation slot keep `{{` / `}}` verbatim so existing programs (e.g. JSON templates) are not silently rewritten. 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. `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` `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` (bytes/3.4 stub; within ~5% for English prose). Pure text-in / number-out; tree-bridge eligible. ILO-47 tracks replacing the stub with a real BPE tokeniser. *Experimental.*=`n` `run cmd argv`=spawn `cmd` with argv list — see [Process spawn](#process-spawn) for the no-shell-no-glob security model=`R (M t t) t` `run2 cmd argv`=like `run` but returns a typed `RunResult` record (`r.stdout`, `r.stderr`, `r.exit` as `n`) instead of a loose map; Err only on spawn failure=`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` `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), `{:= 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) ...`=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)` `sleep ms`=pause current engine for `ms` milliseconds; returns nil=`_` `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` > **`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 `, `next `, `this ` — 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`: `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. `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: `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:"` (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:"` for the same case. **Inherits parent env + cwd.** Neither primitive provides env or cwd override. Set the parent env / cwd before invoking ilo if you need a different shape. **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. [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. 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. [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`. 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). -- 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. -FUNCTIONS: : ...>; 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 tot p:n q:n r:n>n;s=*p q;t=*s r;+s t -TYPES: `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. [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, treated as `unknown` during verification. Used for higher-order function signatures: identity x:a>a;x apply f:F a a x:a>a;f x Type variables provide weak generics - the verifier accepts any type for `a` without consistency checking across call sites. [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: `(: ...>;)`. Same shape as a top-level function declaration, wrapped in parens, no name. **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` 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. -NAMING: Short names everywhere. 1–3 chars. `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. **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 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 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`, …) 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: `AND a b`, `OR a b`, `NOT a`=`&a b`, `|a b`, `!a`=`ILO-L001` `=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` `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` `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` `tup.0` / `pair.0` (tuple access)=bind from `zip`-pair, then `at pair 0` (no tuple type)=`ILO-T004` 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 `- - a b c d` for `` 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 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 `) 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 ` 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. -BUILTINS: Called like functions, compiled to dedicated opcodes. `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` `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` `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` `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` `run cmd argv`=spawn `cmd` with argv list — see [Process spawn](#process-spawn) for the no-shell-no-glob security model=`R (M t t) t` `run2 cmd argv`=like `run` but returns a typed `RunResult` record (`r.stdout`, `r.stderr`, `r.exit` as `n`) instead of a loose map; Err only on spawn failure=`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` `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)=`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), `{:= 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) ...`=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)` `sleep ms`=pause current engine for `ms` milliseconds; returns nil=`_` `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` > **`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. > **`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 `, `next `, `this ` — 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`: `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. `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: `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:"` (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:"` for the same case. **Inherits parent env + cwd.** Neither primitive provides env or cwd override. Set the parent env / cwd before invoking ilo if you need a different shape. **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). **v1 is dynamic, not static.** In this MVP the `World` token is a runtime value — a function can receive `w:W` without the verifier enforcing that a `net=false` world is not passed to a net builtin. Static enforcement (verifier rejects mismatched worlds at call sites) is deferred to a follow-up. Carry-forward pattern: always thread `world` from `main` to every I/O function. fetch w:W url:t>R t t;get url -- no w.net check yet (v1 dynamic) main>t; w=world r=fetch w "https://api.example.com/data" ... See `examples/capability-world.ilo` for a full working example. [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. 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. [Crypto primitives] `sha256`, `hmac-sha256`, `b64`, `b64-dec`, `hex`, `ct-eq` form the crypto-primitives cluster — the path agents need for webhook signature verification, JWT signing, and any time a secret is compared to a known value. All six 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`. `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. `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). -- 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" `b64-dec` returns `Result` so malformed input surfaces typed at the boundary; the encoders and `ct-eq` are total. -BUILTINS: Called like functions, compiled to dedicated opcodes. `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` `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` `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` `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` `run cmd argv`=spawn `cmd` with argv list — see [Process spawn](#process-spawn) for the no-shell-no-glob security model=`R (M t t) t` `run2 cmd argv`=like `run` but returns a typed `RunResult` record (`r.stdout`, `r.stderr`, `r.exit` as `n`) instead of a loose map; Err only on spawn failure=`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` `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), `{:= 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) ...`=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)` `sleep ms`=pause current engine for `ms` milliseconds; returns nil=`_` `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` > **`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. > **`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 `, `next `, `this ` — 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`: `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. `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: `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:"` (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:"` for the same case. **Inherits parent env + cwd.** Neither primitive provides env or cwd override. Set the parent env / cwd before invoking ilo if you need a different shape. **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. 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. [Crypto primitives] `sha256`, `hmac-sha256`, `b64`, `b64-dec`, `hex`, `ct-eq` form the crypto-primitives cluster — the path agents need for webhook signature verification, JWT signing, and any time a secret is compared to a known value. All six 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`. `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. `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). -- 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" `b64-dec` returns `Result` so malformed input surfaces typed at the boundary; the encoders and `ct-eq` are total. +BUILTINS: Called like functions, compiled to dedicated opcodes. `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` `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` (bytes/3.4 stub; within ~5% for English prose). Pure text-in / number-out; tree-bridge eligible. ILO-47 tracks replacing the stub with a real BPE tokeniser. *Experimental.*=`n` `run cmd argv`=spawn `cmd` with argv list — see [Process spawn](#process-spawn) for the no-shell-no-glob security model=`R (M t t) t` `run2 cmd argv`=like `run` but returns a typed `RunResult` record (`r.stdout`, `r.stderr`, `r.exit` as `n`) instead of a loose map; Err only on spawn failure=`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), `{:= 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) ...`=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)` `sleep ms`=pause current engine for `ms` milliseconds; returns nil=`_` `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` > **`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 `, `next `, `this ` — 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`: `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. `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: `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:"` (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:"` for the same case. **Inherits parent env + cwd.** Neither primitive provides env or cwd override. Set the parent env / cwd before invoking ilo if you need a different shape. **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. 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. [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`. 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). -- 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} 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. `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: `"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. **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. 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=;?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 ` to make both text, or `default-on-err (num ) ` 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 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 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} diff --git a/src/diagnostic/registry.rs b/src/diagnostic/registry.rs index 92af9710..616e6480 100644 --- a/src/diagnostic/registry.rs +++ b/src/diagnostic/registry.rs @@ -1874,7 +1874,7 @@ A function with explicit generic type parameters (``, mn x:a y:a>a r=x;>(x) y{r=y};r -mn 1 "two" -- ILO-T044: 'a' bound to n then t +mn 1 "two" -- ILO-T045: 'a' bound to n then t ``` Fix: pass two values of the same type. @@ -1884,7 +1884,7 @@ Fix: pass two values of the same type. ``` add-one x:a>a;+x 1 -add-one "hello" -- ILO-T044: text does not satisfy numeric +add-one "hello" -- ILO-T045: text does not satisfy numeric ``` Fix: pass a numeric argument. diff --git a/src/interpreter/json.rs b/src/interpreter/json.rs index c570ecb0..0fe14cff 100644 --- a/src/interpreter/json.rs +++ b/src/interpreter/json.rs @@ -76,7 +76,12 @@ impl Value { Value::LazyStdinLines(_) => { Err("stdin-lines iterator cannot be serialized".to_string()) } - Value::World { net, read, write, run } => { + Value::World { + net, + read, + write, + run, + } => { let mut map = serde_json::Map::with_capacity(4); map.insert("net".to_string(), serde_json::Value::Bool(*net)); map.insert("read".to_string(), serde_json::Value::Bool(*read)); diff --git a/src/interpreter/mod.rs b/src/interpreter/mod.rs index da4830c2..2779cd91 100644 --- a/src/interpreter/mod.rs +++ b/src/interpreter/mod.rs @@ -401,8 +401,16 @@ impl std::fmt::Display for Value { } Value::Ok(v) => write!(f, "~{}", v), Value::Err(v) => write!(f, "^{}", v), - Value::World { net, read, write, run } => { - write!(f, "World {{net: {net}, read: {read}, write: {write}, run: {run}}}") + Value::World { + net, + read, + write, + run, + } => { + write!( + f, + "World {{net: {net}, read: {read}, write: {write}, run: {run}}}" + ) } Value::FnRef(name) => write!(f, "", name), Value::Closure { fn_name, captures } => { @@ -7234,15 +7242,31 @@ fn call_function(env: &mut Env, name: &str, args: Vec) -> Result { if builtin == Some(Builtin::WorldCap) && args.is_empty() { let (net, read, write, run) = match env.caps.as_ref() { crate::caps::Caps::Permissive => (true, true, true, true), - crate::caps::Caps::Restricted { net, read, write, run } => { + crate::caps::Caps::Restricted { + net, + read, + write, + run, + .. + } => { let cap_allowed = |p: &crate::caps::Policy| { matches!(p, crate::caps::Policy::All) || matches!(p, crate::caps::Policy::List(v) if !v.is_empty()) }; - (cap_allowed(net), cap_allowed(read), cap_allowed(write), cap_allowed(run)) + ( + cap_allowed(net), + cap_allowed(read), + cap_allowed(write), + cap_allowed(run), + ) } }; - return Ok(Value::World { net, read, write, run }); + return Ok(Value::World { + net, + read, + write, + run, + }); } // world-no-net > World — construct a World with net=false. @@ -7256,6 +7280,7 @@ fn call_function(env: &mut Env, name: &str, args: Vec) -> Result { read, write, run, + .. } => { let cap_allowed = |p: &crate::caps::Policy| { matches!(p, crate::caps::Policy::All) @@ -8562,7 +8587,12 @@ fn value_to_json(val: &Value) -> serde_json::Value { serde_json::Value::Object(map) } Value::LazyStdinLines(_) => serde_json::Value::String("".to_string()), - Value::World { net, read, write, run } => { + Value::World { + net, + read, + write, + run, + } => { let mut map = serde_json::Map::with_capacity(4); map.insert("net".to_string(), serde_json::Value::Bool(*net)); map.insert("read".to_string(), serde_json::Value::Bool(*read)); @@ -9476,17 +9506,26 @@ fn eval_expr(env: &mut Env, expr: &Expr) -> Result { )), }, // World field access: .net .read .write .run → Bool - Value::World { net, read, write, run } => { + Value::World { + net, + read, + write, + run, + } => { let v = match field.as_str() { "net" => Value::Bool(net), "read" => Value::Bool(read), "write" => Value::Bool(write), "run" => Value::Bool(run), - other if *safe => Value::Nil, - other => return Err(RuntimeError::new( - "ILO-R005", - format!("no field '{other}' on World (known: net, read, write, run)"), - )), + _other if *safe => Value::Nil, + other => { + return Err(RuntimeError::new( + "ILO-R005", + format!( + "no field '{other}' on World (known: net, read, write, run)" + ), + )); + } }; Ok(v) } diff --git a/src/parser/mod.rs b/src/parser/mod.rs index db546e71..df87e068 100644 --- a/src/parser/mod.rs +++ b/src/parser/mod.rs @@ -1791,7 +1791,8 @@ statement boundary; bind the chain to a local first. For example, split \ Some(tok) => Err(self.error_hint( "ILO-P007", format!("expected type, got {}", tok.user_facing_name()), - "valid types: n, t, b, L n, R n t, F n>n, W (World), or a record type name".to_string(), + "valid types: n, t, b, L n, R n t, F n>n, W (World), or a record type name" + .to_string(), )), None => Err(self.error("ILO-P008", "expected type, got EOF".into())), } @@ -4158,7 +4159,12 @@ or write `({fmt_name} \"...\" ...)` so its args are grouped." // `env-all!` / etc. Never consume args — return immediately as // a 0-arg call. Without this guard the greedy args loop below // would steal the first token of the next statement. - if name == "rdin" || name == "rdinl" || name == "env-all" || name == "world" || name == "world-no-net" { + if name == "rdin" + || name == "rdinl" + || name == "env-all" + || name == "world" + || name == "world-no-net" + { return Ok(Expr::Call { function: name, args: vec![], diff --git a/src/verify.rs b/src/verify.rs index b2e12d78..1b8118e2 100644 --- a/src/verify.rs +++ b/src/verify.rs @@ -29,7 +29,9 @@ pub enum Ty { /// - `None` — dynamic (constructed via `world`, value is runtime-determined) /// - `Some(false)` — statically known to deny net (constructed via `world-no-net`) /// - `Some(true)` — statically known to allow net (future use) - World { net_known: Option }, + World { + net_known: Option, + }, Unknown, } @@ -3939,7 +3941,12 @@ fn builtin_check_args( // world-no-net > World — construct a World with net=false. // Statically known to deny network access; the verifier emits // ILO-T044 if this value flows into a scope that calls a net builtin. - (Ty::World { net_known: Some(false) }, errors) + ( + Ty::World { + net_known: Some(false), + }, + errors, + ) } "run" => { // run cmd:t args:L t > R (M t t) t @@ -5451,12 +5458,27 @@ impl VerifyContext { // dynamic worlds (world builtin, function parameters) are skipped. if matches!( callee.as_str(), - "get" | "pst" | "put" | "pat" | "del" | "hed" | "opt" - | "getx" | "pstx" | "get-many" | "get-to" | "pst-to" + "get" + | "pst" + | "put" + | "pat" + | "del" + | "hed" + | "opt" + | "getx" + | "pstx" + | "get-many" + | "get-to" + | "pst-to" ) { let net_denied_var = scope.iter().rev().find_map(|frame| { frame.iter().find_map(|(name, ty)| { - if matches!(ty, Ty::World { net_known: Some(false) }) { + if matches!( + ty, + Ty::World { + net_known: Some(false) + } + ) { Some(name.clone()) } else { None diff --git a/src/vm/jit_cranelift.rs b/src/vm/jit_cranelift.rs index 87f77715..dadfb5f2 100644 --- a/src/vm/jit_cranelift.rs +++ b/src/vm/jit_cranelift.rs @@ -7691,6 +7691,58 @@ mod tests { assert_eq!(r, Some(Value::Bool(true))); } + // ── ILO-387: Cranelift JIT regression tests for bounded generics ──────── + // Generics are erased at compile time; the JIT sees monomorphic bytecode. + // These tests prove the JIT path executes bounded-generic functions correctly + // for each bound kind: comparable, numeric, and unbounded (any). + + #[test] + fn cranelift_bounded_generic_comparable_min_numbers() { + // gmn: lesser of two numbers. + let r = jit_run_numeric( + "gmn x:a y:a>a\n r=x\n >(x) y{r=y}\n r", + "gmn", + &[7.0, 3.0], + ); + assert_eq!(r, Some(3.0)); + } + + #[test] + fn cranelift_bounded_generic_comparable_max_numbers() { + // gmx: greater of two numbers. + let r = jit_run_numeric( + "gmx x:a y:a>a\n r=x\n <(x) y{r=y}\n r", + "gmx", + &[3.0, 7.0], + ); + assert_eq!(r, Some(7.0)); + } + + #[test] + fn cranelift_bounded_generic_numeric_add() { + // gadd: generic addition. + let r = jit_run_numeric("gadd x:a y:a>a;+x y", "gadd", &[10.0, 20.0]); + assert_eq!(r, Some(30.0)); + } + + #[test] + fn cranelift_bounded_generic_any_identity_number() { + // gid: unbounded identity with numeric arg. + let r = jit_run_numeric("gid x:a>a;x", "gid", &[42.0]); + assert_eq!(r, Some(42.0)); + } + + #[test] + fn cranelift_bounded_generic_any_identity_text() { + // gid: unbounded identity with text arg. + let r = jit_run( + "gid x:a>a;x", + "gid", + &[Value::Text(Arc::new("hello".to_string()))], + ); + assert_eq!(r, Some(Value::Text(Arc::new("hello".to_string())))); + } + // ── inline_chunk: CMPK_LT_N / CMPK_LE_N / CMPK_EQ_N / CMPK_NE_N arms ── #[test] diff --git a/src/vm/mod.rs b/src/vm/mod.rs index 9023289f..28a62be8 100644 --- a/src/vm/mod.rs +++ b/src/vm/mod.rs @@ -7971,14 +7971,24 @@ impl NanVal { // can drain it one line at a time without buffering. NanVal::heap_stdin_lines(handle.clone()) } - Value::World { net, read, write, run } => { + Value::World { + net, + read, + write, + run, + } => { // World tokens are opaque at the VM level — represented as a // tagged record so the VM can pass them through without special // opcodes. Decode in `to_value` matches this layout. use crate::vm::TypeInfo; let type_info = Rc::new(TypeInfo { name: "World".to_string(), - fields: vec!["net".to_string(), "read".to_string(), "write".to_string(), "run".to_string()], + fields: vec![ + "net".to_string(), + "read".to_string(), + "write".to_string(), + "run".to_string(), + ], num_fields: 0, }); let flat: Box<[NanVal]> = Box::new([ diff --git a/tests/regression_world_builtin.rs b/tests/regression_world_builtin.rs index 6571f178..fad85237 100644 --- a/tests/regression_world_builtin.rs +++ b/tests/regression_world_builtin.rs @@ -16,7 +16,11 @@ fn run_src(src: &str) -> (String, bool) { let out = ilo().arg(src).output().expect("ilo binary not found"); let stdout = String::from_utf8_lossy(&out.stdout).trim().to_string(); let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string(); - let combined = if stderr.is_empty() { stdout } else { format!("{stdout}\n{stderr}") }; + let combined = if stderr.is_empty() { + stdout + } else { + format!("{stdout}\n{stderr}") + }; (combined, out.status.success()) } @@ -35,7 +39,11 @@ fn world_builtin_returns_world_type() { fn world_field_net() { let (out, ok) = run_src("main>b;w=world;w.net"); assert!(ok, "w.net should succeed: {out}"); - assert_eq!(out.trim_end_matches(|c: char| !c.is_alphanumeric()).trim(), "true", "net={out}"); + assert_eq!( + out.trim_end_matches(|c: char| !c.is_alphanumeric()).trim(), + "true", + "net={out}" + ); } #[test]