rut

rut is a small, statically typed, embeddable scripting language with Rust-flavored syntax, implemented in Rust. It is designed to be the scripting layer of host applications — typically UI apps — replacing JavaScript engines with a language whose type system is not erased: types exist at runtime, drive bytecode specialization, and make the host boundary fully checked.

Syntax feels like TypeScript (simple enum, the class shape, anonymous functions), with a Rust-flavored trait surface (trait + nominal satisfaction through impl I for T blocks) and Kotlin-style structured concurrency (async/await over poll-based futures). The runtime is a bytecode VM with no JIT — deterministic, fuel-metered, and small enough to embed everywhere a wasm binary fits.

use ink::{ Logger };
use pouch::{ Vec };

fn sieve(limit: i32) -> Vec<i32> {
    let mut marks = Vec<u8>.filled(0, limit + 1);
    let primes: Vec<i32> = Vec.new();
    for (let i = 2; i <= limit; i += 1) {
        if (marks[i] == 0) {
            primes.push(i);
            let mut m = i * i;
            while (m <= limit) {
                marks[m] = 1;
                m += i;
            }
        }
    }
    return primes;
}

pub fn main() {
    let log = Logger.new("sieve");
    let primes = sieve(100);
    log.info(f"{primes.len()} primes up to 100, last={primes[primes.len() - 1]}");
}

Where to go next

The book is also served live at https://rut.hpp2334.com, and the wasm playground — where every snippet on this site runs in the browser — lives at https://playground.rut.hpp2334.com.

The repo

crates/     the implementation: lexer, parser, compiler, VM, std, CLI, wasm
rut/        the in-tree rut packages (core, pouch, ink, json, http, …)
examples/   seven runnable end-to-end projects
demo/       the wasm playground
docs/       this book (built with mdbook)

Build everything from source:

cargo build --release -p rut-cli   # the `rut` binary: run / fmt / pack / dump

License

MIT OR Apache-2.0.

Installation

rut is a self-hosting-free, from-source toolchain: one Rust build gives you the rut binary (run / format / pack / dump) plus the language’s in-tree packages, which the engine mounts automatically when you run a standalone file.

Prerequisites

• Rust (nightly) — the repo pins an exact nightly in rust-toolchain.toml; rustup installs it on the first build. Any recent rustup works.

• git — for the checkout.

• Node.js 20+ — only if you want to build or drive the wasm playground (the rest of the book does not need it).

Build the toolchain

From a checkout of the repository:

cargo build --release -p rut-cli

This produces the rut binary at target/release/rut. Put it on your PATH (or call it by path — the pages here use the bare name):

cargo build --release -p rut-cli
export PATH="$PWD/target/release:$PATH"
rut
# usage: rut — run <file.rut | dir | mod.rutbundle> [--fuel N] | fmt <file.rut | dir> [--check] | pack <dir> [-o out.rutbundle] | dump <file.rut>

The binary embeds the whole engine: lexer, parser, compiler, typed bytecode, and the VM. It also carries the vendored packages from the repo’s rut/ directory (core, pouch, ink, json, …) — a standalone hello.rut that says use ink::{ Logger }; just works, no manifest required.

Smoke-test it

cat > hello.rut <<'EOF'
use ink::{ Logger };

pub fn main() {
    let log = Logger.new("hello");
    log.info(f"hello, rut!");
}
EOF
rut run hello.rut

hello, rut!

If that printed, your toolchain is complete. Continue to your first rut program.

Optional: the wasm playground

The playground runs the same engine compiled to WebAssembly. Building it needs one extra target:

rustup target add wasm32-unknown-unknown
cargo build -p rut-wasm --target wasm32-unknown-unknown --release

or, from demo/, the one-command lane that also copies the artifact into place:

cd demo && npm install && npm run build:wasm

Optional: build this book

The documentation is an mdbook site:

cargo install mdbook --locked
mdbook serve docs     # live-reload preview at http://localhost:3000
mdbook build docs     # static site in docs/book/

Your first rut program

rut feels like TypeScript on the surface and Rust underneath the hood. This page walks one file through the whole toolchain — running, formatting, inspecting, and budgeting — so every later page can assume the workflow.

Write and run

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("hello");
    let name = "rut";
    log.info(f"hello, {name}!");
}

Save it as hello.rut and run it:

rut run hello.rut

hello, rut!

Three things to notice:

• One file is one module. There is no include form; cross-module code is reached through use paths (see the modules tutorial).
• use ink::{ Logger }; pulls Logger out of the ink package. When you rut run a standalone file, the vendored packages mount automatically — no manifest needed.
• f"hello, {name}!" is a format literal: {expr} interpolates any expression, rendered through the value’s display contract.

pub fn main() is the entry the CLI calls.

Values, briefly

Extend the file — rut infers, and every type is known at compile time:

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("hello");
    let n = 10;            // i32 — the integer default
    let scale = 1.5;       // f32 — the float default
    let big: u64 = 10;     // u64 via annotation — fits the default
    let flags = [1, 2, 3]; // [i32] — a fixed heap cell
    let mut sum = 0;       // `mut` — this one is written to
    for (let x of flags) {
        sum += x * n;
    }
    log.info(f"sum={sum} scale={scale}");
}

sum=60 scale=1.5

The full tour — suffixes, casts, strings, bytes, structs — is the values and variables tutorial, and the exact rules live in literals and inference.

Format

The formatter is the style — there is no configuration:

rut fmt hello.rut            # rewrite in place
rut fmt hello.rut --check    # verify only (note: --check goes AFTER the path)
rut fmt .                    # walk a directory tree, every *.rut file

--check prints unformatted: <file> and exits 1 when a file needs changes, which makes it a clean CI gate. A file that does not parse is refused loudly rather than half-formatted.

Inspect

dump compiles a single module and prints its structures — useful when a snippet behaves differently than you expect:

rut dump hello.rut

dump runs the lone module through the frontend without mounting the packages, so it is the tool for surface questions (“what does this lower to?”) rather than whole-program runs. The playground’s AST and IR panes show the same two views live — see the playground.

Budget it

Every rut run is fuel-metered. Cap it with --fuel N (default 10,000,000):

rut run hello.rut --fuel 1000

A program that exhausts its fuel halts with a diagnostic naming the budget — the same contract the VM enforces for embedded hosts, along with heap ceilings and depth limits (resource limits).

Where next

• The tutorial teaches the language hands-on, one concept per chapter.
• The examples are seven complete projects you can run today.
• Core concepts explains why the language is shaped the way it is.

The playground

The playground is the zero-install way to run rut: the whole engine — lexer, parser, compiler, VM — compiled to WebAssembly and served as a static page. It is deployed at https://playground.rut.hpp2334.com.

The layout

• Case list — prepared programs, ordered the way the repo’s own gate runs them: algorithms first (sieve, quicksort, matrix multiply), then language-surface tours (classes, closures & generics, structs, literals, checked arithmetic, str views, bytes, opaque, when, maps & sets, type aliases), then memory shapes (node cycle, tree, weak cache).
• Editor — the case’s source, live-editable. The cases are read from the same .rut files the repository’s native test gate compiles and runs, so what you edit is the real corpus, not a copy.
• Output / AST / IR panes — every run shows the program’s real output plus the two compile views: the parsed AST and the typed IR the compiler lowers to. rut dump <file> prints the same structures from the CLI.
• Budget control — each run executes under an explicit fuel + heap budget (default 10,000,000 fuel / 4 MiB heap). A budget that bites is a feature, not a bug: one prepared case parks on the out-of-fuel trap on purpose, and the Resume control adds fuel and continues the same frame — that is structured-concurrency-grade resumption, not a restart.

No silent fallback

The page probes the wasm artifact at boot. If the engine or the syntax-highlighting module is missing or invalid, you get a full-page error naming the exact build command — the panes never mount in a degraded mode. On the deployed site this never happens; when you run a local build (below), the preflight exists so a stale artifact cannot masquerade as a working playground.

Running it locally

cd demo
npm install
npm run build:wasm   # builds rut.wasm + rut-lsp.wasm, copies to public/
npm run dev          # http://localhost:8080 with live reload

Other lanes:

npm run build        # static build into dist/
npm run smoke        # headless gate: every case really runs
npm run dev:channel  # dev server + a throwaway public https URL for demos

The corpus itself is documented in the playground corpus, with the bigger end-to-end projects under Examples.

Values and variables

Every value in rut has a type, and every type is known at compile time. This chapter covers the primitive types, how literals infer their types, how bindings work, and the one rule that organizes everything else: primitives copy, every other value is a shared cell.

For the full grammar of literals and inference rules, see the reference on literals and inference.

The primitive types

There is no null, no undefined, and no character type. A str iterates as one-codepoint strs, and codepoints read as u32 (s.code(), s.code_at(i)) — see string slicing and views.

Variables: let and let mut

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("vars");
    let a = 10;          // an immutable binding
    let mut b = 10;      // a mutable binding
    b = 20;              // OK — b may be reassigned
    // a = 30;           // ERROR: a is not `mut`
    log.info(f"a={a} b={b}");
}

a=10 b=20

mut is permission to write through that name: reassigning the binding, assigning to a field (p.x = 3), or assigning to an element (xs[0] = 7). Sharing is not gated by mut — two bindings can name the same value, and what mut controls is only who may write.

Every type has a zero value: 0 for numbers, false for bool, the empty string, nil for nullables. Omit a field in a struct literal and it takes the field’s initializer if there is one, else the type’s zero value (see structs, enums, and classes).

Numbers

An unsuffixed integer literal defaults to i32; an unsuffixed float defaults to f32. The default is also a ceiling: a literal adapts to the expected type only while it fits the default.

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("numbers");
    let a = 10;                        // i32
    let b = 10u8;                      // u8 via suffix
    let c: u64 = 10;                   // u64 via annotation — 10 fits
    let big = 18446744073709551615u64; // past the i32 default: suffix required
    let d = 1.5;                       // f32
    let d64: f64 = 1.5;                // f64 via annotation
    let hex = 0xFF_u32;                // 0x / 0b / 0o bases, _ separators
    log.info(f"a={a} d={d} d64={d64} hex={hex} big={big}");
}

a=10 d=1.5 d64=1.5 hex=255 big=18446744073709551615

Conversions are explicit casts: expr as T. Casts truncate like C — they never trap.

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("casts");
    let cast = 300 as u8;   // 44 — keeps the low 8 bits
    log.info(f"cast={cast}");
}

cast=44

Arithmetic has two sharp edges:

• Mixed widths do not mix. Both operands must have the same width — convert one side first. let mut total = 0.0; makes an f32, and adding an f64 to it is a type error; annotate let mut total: f64 = 0.0; when you mean double precision.
• Overflow, division by zero, and out-of-bounds indexing trap. For the explicit non-trapping ladder (wrapping_add, saturating_mul, checked_add), see the standard library.

Text: plain, raw, and format strings

Three literal forms. A plain string is always inert — no interpolation ever happens implicitly.

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("text");
    let name = "rut";
    let s = "hi\tname";              // plain: escapes processed
    let raw = r"C:\temp\log.txt";    // raw: every byte is literal
    let t = f"hi {name}!";           // format: placeholders evaluated
    log.info(f"{s} | {raw} | {t}");
}

hi	name | C:\temp\log.txt | hi rut!

Plain and format strings share the same escapes (\t \n \r \\ \" and \u{...}). In an f-string, { expr } splices any expression — identifiers, calls, arithmetic — except nested string literals (bind one to a variable first). {{ and }} are literal braces:

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("text");
    log.info(f"open{{close}} braces");   // prints: open{close} braces
}

open{close} braces

What an f-string can render: integers (decimal), floats (shortest round-trip decimal: 3.5, 0.1), bool (true/false), str (contents), and enum members (their name: Color.Green renders Green). Composite values — structs, classes, arrays, vecs — are a compile error inside an f-string; write a to_string()-style method and call it, or use a debug dump for development.

Sequences and buffers

The fixed array [T] is built from a literal or a repeat:

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("arrays");
    let arr = [1, 2, 3];         // [i32] — fixed length
    let zero: [u8] = [0u8; 34];  // 34 slots of 0
    log.info(f"len={arr.len()} first={arr[0]} zero.len={zero.len()}");
}

len=3 first=1 zero.len=34

The growable sequence is Vec<T> (from the pouch package — use pouch::{ Vec };): Vec.new(), Vec.from([..]), Vec<i32>.filled(0, 1024), push, pop, len. Indexing and for..of work the same on both. See the standard library for the full surface.

bytes is the binary primitive. s.encode() turns text into octets, b.decode() reads it back (lossy UTF-8), bytes.zeroed(n) and bytes.from(a) build buffers directly:

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("bytes");
    let b = "rut runs".encode();
    let ok = b.decode() == "rut runs";   // true — content comparison
    log.info(f"len={b.len()} roundtrip={ok}");
}

len=8 roundtrip=true

Sharing: the one rule

Primitives and fn values copy on assignment, argument passing, and return. Every other value is a shared cell: let q = p is an O(1) handle move, and a write through any alias is visible through all of them.

use ink::{ Logger };

struct Point { x: i32; y: i32 }

pub fn main() {
    let log = Logger.new("sharing");
    let mut p = Point { x: 1, y: 2 };
    let q = p;          // q and p name ONE cell
    p.x = 4;            // q.x is 4 now
    log.info(f"q.x={q.x} same cell: {q == p}");
}

q.x=4 same cell: true

Equality follows the same split:

The one copy escape hatch is bytes.clone() — a fresh buffer with the same octets. There is no generic copy for any other type; if you need a divergent value, build a new one.

Absence is nil on a nullable ?T — see errors and optionality.

Tuples

Records (A, B) are first-class values with numeric fields:

use ink::{ Logger };

fn divmod(a: i32, b: i32) -> (i32, i32) {
    return (a / b, a % b);
}

pub fn main() {
    let log = Logger.new("tuples");
    let (q, r) = divmod(17, 5);   // destructuring
    let t = (1, true);
    log.info(f"q={q} r={r} t.0={t.0}");
}

q=3 r=2 t.0=1

The pair is also rut’s standard error channel — the next chapters use it constantly.

Put it together

Save this as literals.rut and run rut run literals.rut:

use pouch::{ Vec };
use ink::{ Logger };

struct Point { x: f32; y: f32 }

fn literals(name: str) {
    let log = Logger.new("literals");
    let a = 10;                      // i32 (default)
    let b = 10u8;                    // u8 via suffix
    let c: u64 = 10;                 // u64 via annotation — fits the default
    let big = 18446744073709551615u64; // past the `i32` default: suffix REQUIRED
    let cast = 300 as u8;            // 44 — `as` truncates
    let d = 1.5;                     // f32 (default)
    let e = 1.5f32;                  // f32 via suffix
    let d64: f64 = 1.5;              // f64 via annotation
    let s = "hi\tname";              // plain string: escapes processed
    let raw = r"C:\temp\log.txt";    // raw literal: NO escape processing
    let t = f"hi {name}!";           // format literal
    let ch = "h";                    // a 1-codepoint str
    let mut arr = [1, 2, 3];         // [i32] — fixed array
    let mut zero: Vec<f32> = Vec<f32>.filled(0.0, 1024);  // growable, flat
    let grow = Vec<i32>.from([1, 2, 3]);  // array -> growable
    arr[0] = 7;                      // element write needs `mut`
    zero[0] = 9.0f32;
    let bin = bytes(64);             // 64 zeroed octets
    let p = Point { x: 1, y: 2 };    // struct literal: no `new`

    log.info(f"a={a} e={e} d64={d64} ch={ch} p.x={p.x} zero[0]={zero[0]} len={grow.len()} bin={bin.len()}");
}

pub fn main() {
    literals("rut");
}

a=10 e=1.5 d64=1.5 ch=h p.x=1 zero[0]=9 len=3 bin=64

Next: control flow and when.

Control flow and when

rut has the classic structured statements — if/else, while, for — and exactly one match construct: when, an exhaustive pattern expression. There is no switch, no case, no fallthrough. The full rules live in the reference on control flow.

if and else

Braces are always required, whatever the body length:

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("flow");
    for (let hits of [0, 5, 12]) {
        let mut first = false;
        let mut warm = false;
        let mut hot = false;
        if (hits == 0) {
            first = true;
        } else if (hits < 10) {
            warm = true;
        } else {
            hot = true;
        }
        log.info(f"hits={hits} first={first} warm={warm} hot={hot}");
    }
}

hits=0 first=true warm=false hot=false
hits=5 first=false warm=true hot=false
hits=12 first=false warm=false hot=true

The condition must be a bool — there is no truthiness coercion, and no parenthesized-assignment footgun.

Loops

while repeats until its condition is false:

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("sieve");
    let i = 2;
    let limit = 12;
    let mut marks = [0; 16];
    let mut m = i * i;
    while (m <= limit) {
        marks[m] = 1;
        m += i;
    }
    log.info(f"marks[4]={marks[4]} marks[5]={marks[5]} stopped at m={m}");
}

marks[4]=1 marks[5]=0 stopped at m=14

for..of iterates anything with elements: fixed arrays, Vecs, str (yielding one-codepoint strs), and bytes (yielding u8s):

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("loops");
    let mut n = 0;
    for (let w of ["rut", "runs", "rut"]) {
        // w is a str
    }
    for (let c of "héllo") {
        n += 1;             // 5 iterations — codepoints, not the 6 bytes
    }
    log.info(f"n={n}");
}

n=5

The loop variable is always spelled let and is fresh each iteration.

Indexed for is the C shape. The induction variable is loop-owned: the update clause (and the body) may assign it without mut.

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("loops");
    let xs = [3, 1, 4];
    let n = xs.len();
    let mut total = 0;
    for (let i = 0; i < n; i += 1) {
        total += xs[i];
    }
    log.info(f"total={total}");
}

total=8

break and continue work in every loop form; there are no labels and no do..while.

return

return expr; exits the function. If the function returns nothing, the arrow is omitted and return; (or falling off the end) returns:

use pouch::{ Vec };
use ink::{ Logger };

fn swap(mut xs: Vec<i32>, a: i32, b: i32) {
    let t = xs[a];
    xs[a] = xs[b];
    xs[b] = t;
    // no return — the function's type is nil
}

pub fn main() {
    let log = Logger.new("swap");
    let xs = Vec<i32>.from([1, 2, 3]);
    swap(xs, 0, 2);
    log.info(f"first={xs[0]} last={xs[2]}");
}

first=3 last=1

when — the one match

when (value) { pattern -> body, ... } is an expression: the first matching arm produces the value. No fallthrough — exactly one arm runs.

use ink::{ Logger };

fn classify(n: i32) -> str {
    return when (n) {
        0       -> "zero",
        1, 2, 3 -> "small",     // comma-separated alternatives
        else    -> "big",       // the wildcard
    };
}

pub fn main() {
    let log = Logger.new("when");
    for (let n of [0, 2, 9]) {
        log.info(f"{n}: {classify(n)}");
    }
}

0: zero
2: small
9: big

The arm body before the , is an expression; arms can also be blocks:

use ink::{ Logger };

enum Light { Green, Yellow, Red }

fn go()    { Logger.new("light").info("go"); }
fn brake() { Logger.new("light").info("brake"); }
fn stop()  { Logger.new("light").info("stop"); }

pub fn main() {
    let l = Light.Yellow;
    when (l) {
        Light.Green  -> { go(); },
        Light.Yellow -> { brake(); },
        Light.Red    -> { stop(); },
    }
}

brake

Used as a statement, a when must produce nothing — the block arms above are statement arms.

Patterns

v1 patterns are: enum members (Light.Red), literals (integers, floats, bool, str), comma-separated alternatives, and else. There are no ranges, no destructuring, and no guards — an if inside the arm body does that job.

Exhaustiveness is enforced

• Enum scrutinee: either cover every member or add else. A partial when over an enum is a compile error — when you add a member later, the compiler finds every when you must extend.
• Any other scrutinee: else is mandatory (integers and strings cannot be enumerated).

use ink::{ Logger };

enum Light { Green, Yellow, Red }

fn go()    { Logger.new("light").info("go"); }
fn brake() { Logger.new("light").info("brake"); }
fn stop()  { Logger.new("light").info("stop"); }

fn drive(l: Light) {
    when (l) {
        Light.Green  -> { go(); },
        Light.Yellow -> { brake(); },
        Light.Red    -> { stop(); },   // all members: no else needed
    }
}

fn describe(n: i32) -> str {
    return when (n) {
        0    -> "zero",
        else -> "not zero",            // non-enum scrutinee: else REQUIRED
    };
}

pub fn main() {
    drive(Light.Red);
    let log = Logger.new("light");
    log.info(describe(0));
    log.info(describe(7));
}

stop
zero
not zero

when over a bool reads nicely as a two-arm check:

use ink::{ Logger };

struct Point { x: i32; y: i32 }

pub fn main() {
    let log = Logger.new("nullable");
    let p: ?Point = Point { x: 1, y: 2 };
    when (p != nil) {
        true -> { log.info(f"point {p.x} {p.y}"); },
        else -> { log.info("point: nil"); },
    }
}

point 1 2

Duplicate patterns — and arms made unreachable by an earlier one — are compile errors.

One type across the arms

All arm expressions must agree: that shared type is the when’s type. A when that builds a value usually reads best wrapped in a function — the function’s return type then pins every arm:

use ink::{ Logger };

enum Light { Green, Yellow, Red }

fn light_for(i: i32) -> Light {
    return when (i) {
        0    -> Light.Green,
        1    -> Light.Yellow,
        else -> Light.Red,
    };
}

pub fn main() {
    let log = Logger.new("light");
    log.info(f"{light_for(0)} {light_for(1)} {light_for(5)}");
}

Green Yellow Red

Put it together

use ink::{ Logger };

enum Light { Green, Yellow, Red }

fn action(l: Light) -> str {
    return when (l) {
        Light.Green  -> "go",
        Light.Yellow -> "brake",
        Light.Red    -> "stop",
    };
}

fn light_for(i: i32) -> Light {
    return when (i) {
        0    -> Light.Green,
        1    -> Light.Yellow,
        else -> Light.Red,
    };
}

fn classify(n: i32) -> str {
    return when (n) {
        0       -> "zero",
        1, 2, 3 -> "small",
        else    -> "big",
    };
}

pub fn main() {
    let log = Logger.new("lights");

    for (let n of [0, 2, 9]) {
        log.info(f"{n}: {classify(n)}");
    }

    let mut i = 0;
    while (i < 3) {
        log.info(action(light_for(i)));
        i += 1;
    }
}

0: zero
2: small
9: big
go
brake
stop

Next: functions, closures, and generics.

Functions, closures, and generics

Functions are declared with fn, values can be functions, and generic functions monomorphize at compile time — each instantiation gets its own specialized code. The details live in the reference on functions, closures, and generics.

Declaring functions

Parameter and return types are always written. A function whose return type is omitted returns nothing:

use pouch::{ Vec };
use calc::{ Math };
use ink::{ Logger };

struct Point { x: f32; y: f32 }

fn swap(mut xs: Vec<i32>, a: i32, b: i32) {
    let t = xs[a];
    xs[a] = xs[b];
    xs[b] = t;
}

fn length(pt: Point) -> f64 {
    return Math.sqrt((pt.x * pt.x + pt.y * pt.y) as f64);
}

pub fn main() {
    let log = Logger.new("fns");
    let xs = Vec<i32>.from([1, 2, 3]);
    swap(xs, 0, 2);
    log.info(f"first={xs[0]} length={length(Point { x: 3, y: 4 })}");
}

first=3 length=5

A mut parameter (fn step(mut p: Point)) is the callee’s permission to write through p — and because non-primitive values share, that means the caller’s value. A plain parameter promises not to write through it.

Recursion works as expected — functions are visible in their own bodies, and mutual recursion within a module needs no forward declaration.

Anonymous functions

The closure spelling is an anonymous fn with a block body. There is no arrow shorthand — every closure states its parameter and return types, which is what lets it inhabit a first-class fn type:

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("closures");
    let add = fn (a: i32, b: i32) -> i32 { return a + b; };

    let area_of = fn (r: f32) -> f32 {
        let sq = r * r;
        return sq * 3.14159265f32;
    };

    add(1, 2);          // call it like any function
    log.info(f"add={add(1, 2)} area={area_of(1)}");
}

add=3 area=3.1415927

Function types are written fn(P..) -> R and appear anywhere a type does:

use ink::{ Logger };

fn apply(f: fn(i32) -> i32, v: i32) -> i32 {
    return f(v);
}

pub fn main() {
    let log = Logger.new("fns");
    let double = fn (x: i32) -> i32 { return x * 2; };
    log.info(f"apply={apply(double, 21)}");
}

apply=42

Closures capture the enclosing bindings — a closure body sees and can use the locals around it, including after the enclosing function would have returned, because captured cells stay alive as long as the closure does. Since non-primitives share, a capture of a Vec or a struct is a handle to the same cell: writes through the closure are visible to everyone else holding it.

Generics

A generic function declares type parameters in angle brackets. Each concrete instantiation is compiled separately (monomorphized), so generics cost nothing at runtime:

use ink::{ Logger };

fn first<T>(xs: [T], fallback: T) -> T {
    if (xs.len() == 0) {
        return fallback;
    }
    return xs[0];
}

pub fn main() {
    let log = Logger.new("generics");
    let head = first([10, 20], -1);      // first<i32> — inferred
    let name = first(["a", "b"], "?");   // first<str> — a separate instance
    log.info(f"head={head} name={name}");
}

head=10 name=a

T is inferred from the arguments; you rarely spell first<i32>(..) explicitly. Two rules to know:

• A bare T has no methods — you cannot call anything on a value whose type is just T. Pass concrete values in, or take a trait-typed parameter instead (next chapter).
• In v1 a generic class in a parameter position does not unify — fn sum(xs: Vec<i32>) is fine, but a function generic over T taking Vec<T> is not yet the shape to reach for. Concrete instantiations cover most code.

requires bounds

An inline requires bound gates which instantiations compile:

use ink::{ Logger };

trait Labeled {
    fn label(self) -> str;
}

struct Tag { id: i32 }

impl Labeled for Tag {
    fn label(self) -> str { return f"tag-{self.id}"; }
}

fn name<T requires Labeled>(x: T) -> str {
    let w: Labeled = x;     // the bound proves this widening
    return w.label();
}

pub fn main() {
    let log = Logger.new("bounds");
    log.info(name(Tag { id: 7 }));
}

tag-7

The bound is admission-only: it checks at each call site that the concrete type satisfies the named trait (or union of traits), and it proves a T-typed value may be used as that trait type — it does not put methods on T itself. Union bounds admit any member:

fn kind<T requires Ridge | Trench>(x: T) -> str { .. }

This is exactly how typed JSON entry points are spelled — decodeJson<T requires JsonDeserialize>(s: str) — see errors and optionality. Bounds and unions are covered fully in the reference on type aliases and union bounds.

Free functions are the default idiom

rut’s records carry no methods (bodies are fields only; methods live in impl blocks — see structs, enums, and classes), so the everyday shape is small data plus free functions over it:

use ink::{ Logger };

struct Point { x: f32; y: f32 }

fn nudged(pt: Point) -> Point {
    return Point { x: pt.x + 1, y: pt.y };
}

pub fn main() {
    let log = Logger.new("free-fns");
    let p = nudged(Point { x: 2, y: 5 });
    log.info(f"p.x={p.x} p.y={p.y}");
}

p.x=3 p.y=5

Reach for methods when something is genuinely the receiver’s behavior, and for trait impls — everything else is a plain function.

Put it together

use pouch::{ Vec };
use ink::{ Logger };

fn first<T>(xs: [T], fallback: T) -> T {
    if (xs.len() == 0) {
        return fallback;
    }
    return xs[0];
}

fn sum(xs: Vec<i32>) -> i32 {
    let mut total = 0;
    for (let x of xs) {
        total += x;
    }
    return total;
}

pub fn main() {
    let log = Logger.new("closures");
    let add = fn (a: i32, b: i32) -> i32 { return a + b; };
    let area_of = fn (r: f32) -> f32 {
        let sq = r * r;
        return sq * 3.14159265f32;
    };
    log.info(f"add={add(1, 2)} area={area_of(1)} sum={sum(Vec<i32>.from([1, 2, 3]))}");

    let head = first([10, 20], -1);       // first<i32> — monomorphized
    let name = first(["a", "b"], "?");    // first<str> — separate instance
    log.info(f"head={head} name={name}");
}

add=3 area=3.1415927 sum=6
head=10 name=a

Next: structs, enums, and classes.

Structs, enums, and classes

rut has three user-defined type forms, each with one job:

• enum — a small set of named constants.
• struct — an open data record: every field public, literal construction everywhere.
• class — a sealed record: private fields, construction through class methods only.

In all three, the type body is fields only — every method lives in an impl block. A fn written inside a type body is a parse error. The reference pages are structs, enums, and classes and constructors.

Enums

An enum is a distinct named type over integer constants. No payloads, no methods, no computed members — where another language would use a union of literal strings, rut uses an enum:

use ink::{ Logger };

enum Light { Green, Yellow, Red }

enum Direction { Up = 1, Down, Left, Right }   // 1, 2, 3, 4

pub fn main() {
    let log = Logger.new("enums");
    log.info(f"{Light.Green} {Direction.Left} {Direction.Right}");
}

Green Left Right

Members are the enum’s values and are spelled qualified: Light.Green. Explicit initializers set where the numbering starts; the rest continue from there.

when over an enum must be exhaustive — every member, or an else arm (see control flow and when). Enums render as their member name in format strings.

Structs — open records

Declare with struct, construct with a literal — anywhere in a function body, nested inside other literals. There is no new:

use ink::{ Logger };

struct Point {
    x: f32;
    y: f32;
}

struct Rect {
    min: Point;
    max: Point;
}

struct Style {
    color: u32 = 0xff00ff;      // field initializer: literals may omit it
    width: f32 = 1;
}

pub fn main() {
    let log = Logger.new("structs");
    let p = Point { x: 1, y: 2 };                    // every field, by name
    let s = Style {};                                // defaults fill the rest
    let r = Rect { min: Point { x: 0, y: 0 }, max: p };
    log.info(f"r.max.x={r.max.x} width={s.width}");
}

r.max.x=1 width=1

All fields are public, always — member visibility in a struct is a compile error. Privacy is what classes are for.

Structs share. A struct value is a handle to a heap cell: assignment, arguments, and returns all pass the handle, and a write through any alias is visible through all of them. Writing needs a mut binding or mut parameter:

use ink::{ Logger };

struct Point { x: f32; y: f32 }

pub fn main() {
    let log = Logger.new("sharing");
    let mut p = Point { x: 1, y: 2 };
    let q = p;              // q and p name ONE cell
    p.x = 4;                // q.x is 4 now
    log.info(f"q.x={q.x} same cell: {q == p}");
}

q.x=4 same cell: true

== on struct values is cell identity — q == p is true (one cell), p == Point { x: 4, y: 2 } is false (a different cell). To compare field by field, write a function.

Recursive shapes are legal — a record may name itself through a nullable field, because ?Node is one word:

use ink::{ Logger };

struct Node {
    value: i32;
    left: ?Node;
    right: ?Node;
}

fn count(n: ?Node) -> i32 {
    let mut c = 1;
    if (n.left != nil) { c += count(n.left); }
    if (n.right != nil) { c += count(n.right); }
    return c;
}

pub fn main() {
    let log = Logger.new("nodes");
    let n = Node {
        value: 1,
        left: Node { value: 2, left: nil, right: nil },
        right: nil,
    };
    log.info(f"count={count(n)}");
}

count=2

Classes — sealed records

A class adds three things to a struct: module-private fields, construction gated through class methods, and the option of cleanup hooks. There is no constructor keyword, no new operator, and no outside literal — the only way to build a class value from outside is to call a class method that chooses to.

use ink::{ Logger };

class Counter {
    n: i32 = 0;             // module-private — the class's business
}

impl Counter {
    pub fn new() -> Self {                 // the construction surface
        return Self { };                   // the class-private literal
    }

    pub fn press(mut self) {
        self.n = self.n.wrapping_add(1);
    }

    pub fn count(self) -> i32 { return self.n; }
}

pub fn main() {
    let log = Logger.new("counter");
    let c = Counter.new();
    c.press();
    c.press();
    log.info(f"count={c.count()}");      // 2
}

count=2

The pieces:

• A class method is just a function without self. Rect.new(w, h), Version.parse(s), Rect.from_square(s) — any no-self method returning Self is a constructor. new is a convention, not syntax.
• The Self { .. } literal is class-private — legal anywhere in the class’s own impl block, never outside. This is the seal.
• Instance methods spell self explicitly as the first parameter; mut self marks methods that write. There is no this, no static methods, no get/set syntax — a computed property is a method (c.count()).
• Construction is validation. A constructor is an ordinary function — it can check arguments and refuse:

use ink::{ Logger };

class Rect {
    w: f32;
    h: f32;
}

impl Rect {
    pub fn new(w: f32, h: f32) -> Self {
        if (w <= 0 || h <= 0) {
            panic("Rect: negative extents");
        }
        return Self { w: w, h: h };
    }

    pub fn from_square(s: f32) -> Self {
        return Rect.new(s, s);
    }

    pub fn area(self) -> f32 { return self.w * self.h; }
}

pub fn main() {
    let log = Logger.new("rect");
    let r = Rect.new(3, 4);
    let sq = Rect.from_square(2);
    log.info(f"area={r.area()} square={sq.area()}");
}

area=12 square=4

A try-constructor answers the nullable — nil is a failed validation, not a crash:

impl Version {
    pub fn parse(s: str) -> ?Version {
        // ... split "1.2" — on failure:
        return nil;
    }
}

No inheritance. There is no extends, no super, no overriding. Code sharing is composition (hold a helper in a field) or free functions; polymorphism is traits — the next chapter.

Visibility recap

• Struct members: public, always.
• Class members: unannotated is module-private; pub exposes to importers (also pub(mod), pub(super), pub(self)).
• The types themselves follow the same rule: pub class Vec<T> is importable, a bare class Helper stays in its module. See modules and packages.

Struct or class?

Default to a struct: data in, data out, shared like every other value. Reach for a class when the type has rules that construction must enforce, holds private state that outsiders must not read, or owns a resource that needs explicit cleanup.

Put it together

use ink::{ Logger };

class Counter {
    n: i32 = 0;
}

impl Counter {
    pub fn new() -> Self {
        return Self { };
    }

    pub fn press(mut self) {
        self.n = self.n.wrapping_add(1);
    }

    pub fn count(self) -> i32 { return self.n; }
}

class Rect {
    w: f32;
    h: f32;
}

impl Rect {
    pub fn new(w: f32, h: f32) -> Self {
        if (w <= 0 || h <= 0) {
            panic("Rect: negative extents");
        }
        return Self { w: w, h: h };
    }

    pub fn from_square(s: f32) -> Self {
        return Rect.new(s, s);
    }

    pub fn area(self) -> f32 { return self.w * self.h; }
}

pub fn main() {
    let log = Logger.new("classes");
    let c = Counter.new();
    c.press();
    c.press();
    let r = Rect.new(3, 4);
    let sq = Rect.from_square(2.0f32);
    log.info(f"count={c.count()} area={r.area()} square={sq.area()}");
}

count=2 area=12 square=4

Next: traits and impl blocks.

Traits and impl blocks

A trait declares a set of methods; a type joins the trait by writing an impl block. Satisfaction is nominal — the impl block is the only admission. A type whose members all happen to match a trait’s shapes is still not an instance of it until someone writes the block. The full dispatch story is in the reference on traits and traits and dispatch.

Declaring a trait

Traits declare method signatures — no bodies, no default implementations, no fields:

trait Shape {
    fn area(self) -> f64;
    fn name(self) -> str;
}

Methods spell their receiver self explicitly, like every rut method. Anything that looks like a property is a method: declare fn count(self) -> i32;, not a field.

Implementing a trait

impl Trait for Type { .. } registers the pair. Every method must match the trait’s signature exactly; extra methods don’t belong here (put those in an inherent block). Trait impl methods carry no pub — they are as visible as the trait.

use ink::{ Logger };

trait Shape {
    fn area(self) -> f64;
    fn name(self) -> str;
}

struct Circle { r: f64 }

impl Shape for Circle {
    fn area(self) -> f64 { return 3.14159 * self.r * self.r; }
    fn name(self) -> str { return "circle"; }
}

pub fn main() {
    let log = Logger.new("traits");
    let c = Circle { r: 1.0 };
    log.info(f"{c.name()}={c.area()}");
}

circle=3.14159

Rules worth knowing:

• One impl per (trait, type) pair, program-wide. A duplicate is a link error.
• Placement: an impl may live in a module of the trait’s package or the type’s package — at least one side must be yours. You cannot implement two foreign types to each other.
• An empty impl block is legal and acts as a marker: impl Serializable for Point {} says “this type is in” when the trait has no required methods.
• Primitives can implement traits too (in the trait’s own package or module) — the standard library uses this to give integer widths a common internal interface.

Inherent impls

impl Type { .. } — no trait — is where a type’s own methods live: class methods like new, instance methods, helpers. It compiles only in the module that declares the type.

use ink::{ Logger };

struct Circle { r: f64 }

impl Circle {
    fn new(r: f64) -> Self {
        return Self { r: r };
    }
}

pub fn main() {
    let log = Logger.new("traits");
    let c = Circle.new(1.0);
    log.info(f"r={c.r}");
}

r=1

Using trait values

Widening is implicit at any position that expects the trait: an annotated binding, a field, an argument, a return.

use ink::{ Logger };

trait Shape {
    fn area(self) -> f64;
    fn name(self) -> str;
}

struct Circle { r: f64 }

impl Shape for Circle {
    fn area(self) -> f64 { return 3.14159 * self.r * self.r; }
    fn name(self) -> str { return "circle"; }
}

pub fn main() {
    let log = Logger.new("traits");
    let c: Shape = Circle { r: 1.0 };   // Circle widens to Shape
    log.info(f"{c.name()}={c.area()}");
}

circle=3.14159

Trait-typed parameters accept any implementor — write the function once, call it with each concrete type:

use ink::{ Logger };

trait Shape {
    fn area(self) -> f64;
    fn name(self) -> str;
}

struct Circle { r: f64 }
struct Square { side: f64 }

impl Shape for Circle {
    fn area(self) -> f64 { return 3.14159 * self.r * self.r; }
    fn name(self) -> str { return "circle"; }
}

impl Shape for Square {
    fn area(self) -> f64 { return self.side * self.side; }
    fn name(self) -> str { return "square"; }
}

fn describe(s: Shape) -> str {
    return f"{s.name()}={s.area()}";
}

pub fn main() {
    let log = Logger.new("traits");
    log.info(describe(Circle { r: 1.0 }));
    log.info(describe(Square { side: 3.0 }));
}

circle=3.14159
square=9

Heterogeneous containers hold mixed implementors behind the trait name. Inside a single-typed context calls bind directly; iterating a collection of Shape dispatches through the value’s vtable — the compiler picks, and mis-guessing costs one hop, never wrong behavior:

use pouch::{ Vec };
use ink::{ Logger };

trait Shape {
    fn area(self) -> f64;
    fn name(self) -> str;
}

struct Circle { r: f64 }
struct Square { side: f64 }

impl Shape for Circle {
    fn area(self) -> f64 { return 3.14159 * self.r * self.r; }
    fn name(self) -> str { return "circle"; }
}

impl Shape for Square {
    fn area(self) -> f64 { return self.side * self.side; }
    fn name(self) -> str { return "square"; }
}

pub fn main() {
    let log = Logger.new("traits");
    let mut shapes: Vec<Shape> = Vec.new();
    shapes.push(Circle { r: 1.0 });
    shapes.push(Square { side: 3.0 });
    let mut total: f64 = 0.0;
    for (let s of shapes) {
        total += s.area();       // dispatches per element
    }
    log.info(f"total={total} n={shapes.len()}");
}

total=12.14159 n=2

Type tests: is

expr is Type answers with a bool and never traps:

• Concrete RHS — p is Circle: an exact-type test.
• Trait RHS — p is Shape: a capability probe (“does this value’s type have an impl of Shape?”).

use ink::{ Logger };

trait Shape {
    fn area(self) -> f64;
    fn name(self) -> str;
}

struct Circle { r: f64 }
struct Square { side: f64 }

impl Shape for Circle {
    fn area(self) -> f64 { return 3.14159 * self.r * self.r; }
    fn name(self) -> str { return "circle"; }
}

impl Shape for Square {
    fn area(self) -> f64 { return self.side * self.side; }
    fn name(self) -> str { return "square"; }
}

pub fn main() {
    let log = Logger.new("traits");
    let sq = Square { side: 2.0 };
    log.info(f"shape: {sq is Shape} circle: {sq is Circle}");
}

shape: true circle: false

is answers the question; it changes nothing — there is no narrowing and no downcast through a trait. A trait-typed value is used through its trait’s methods; if you need the erased-storage version — a value whose type is forgotten until recovered — that is opaque, covered in errors and optionality and the reference on opaque.

Bounds connect traits to generics

fn name<T requires Labeled>(x: T) admits exactly the instantiations whose concrete type has an impl of Labeled — see functions, closures, and generics. The bound is what makes widening legal inside the body: let w: Labeled = x;.

Making your type iterable

A type becomes a for..of target by implementing the builtin Iterator<E> contract with its single resumption member:

use pouch::{ Vec };
use ink::{ Logger };

struct CountUp { n: i32 }

impl Iterator<i32> for CountUp {
    fn __iterate(self, emit: fn(i32) -> bool) {
        for (let i = 1; i <= self.n; i += 1) {
            if (!emit(i)) { return; }   // false = stop
        }
    }
}

pub fn main() {
    let log = Logger.new("iter");
    let ups = CountUp { n: 4 };
    let got: Vec<i32> = Vec.new();   // shared: survives the loop's captures
    for (let v of ups) {
        got.push(v);
    }
    log.info(f"n={got.len()} first={got[0]} last={got[got.len()-1]}");
}

n=4 first=1 last=4

for (let v of it) desugars to it.__iterate(emit) with a synthetic closure. One consequence to know: the loop body’s captures are taken at the desugar, so reassigning an enclosing scalar inside the loop mutates a copy, not the original. Accumulate through something shared instead — vec.push(v) — or have the loop body act on values it can see directly.

The builtin sequences ([T], Vec<T>, str, bytes) iterate without the trait — their loops are fused, never a per-element call.

Put it together

use pouch::{ Vec };
use ink::{ Logger };

trait Shape {
    fn area(self) -> f64;
    fn name(self) -> str;
}

struct Circle { r: f64 }
struct Square { side: f64 }

impl Shape for Circle {
    fn area(self) -> f64 { return 3.14159 * self.r * self.r; }
    fn name(self) -> str { return "circle"; }
}

impl Shape for Square {
    fn area(self) -> f64 { return self.side * self.side; }
    fn name(self) -> str { return "square"; }
}

fn describe(s: Shape) -> str {
    return f"{s.name()}={s.area()}";
}

pub fn main() {
    let log = Logger.new("traits");

    let c: Shape = Circle { r: 1.0 };
    log.info(describe(c));

    let sq = Square { side: 2.0 };
    log.info(f"is shape: {sq is Shape}");

    let mut shapes: Vec<Shape> = Vec.new();
    shapes.push(Circle { r: 1.0 });
    shapes.push(Square { side: 3.0 });
    let mut total: f64 = 0.0;
    for (let s of shapes) {
        total += s.area();
    }
    log.info(f"total={total} n={shapes.len()}");
}

circle=3.14159
is shape: true
total=12.14159 n=2

Next: errors and optionality.

Errors and optionality

rut has no exceptions you catch, no Result enum, and no null. Two mechanisms cover everything:

• Absence is nil on a nullable ?T.
• Failure is a value in the second slot of a pair — the (T, err) answer channel.
• Bugs — broken contracts — trap loudly and immediately (panic, assert, a nil deref, an out-of-bounds index).

The design background lives in everything is a value.

?T and nil: absence

?T is a nil-able cell. A plain T always holds a value; ?T is that value or nil:

use ink::{ Logger };

struct Node {
    value: i32;
    left: ?Node;      // one word — recursive shapes are legal
    right: ?Node;
}

pub fn main() {
    let log = Logger.new("nodes");
    let n = Node { value: 1, left: nil, right: nil };
    log.info(f"left is nil: {n.left == nil}");
}

left is nil: true

Lookups answer ?T: a hit is the value, a miss is nil. Deref is automatic at every use — p.x, p[i], for (let x of p), arithmetic — and dereferencing a nil traps NilDeref, so guard first:

use nmapset::{ HashMap };
use ink::{ Logger };

pub fn main() {
    let log = Logger.new("optional");
    let mut scores: HashMap<str, i32> = HashMap.new();
    scores.put("rut", 41);
    let mut n = 0;
    let hit = scores.get("rut");      // ?i32
    if (hit != nil) {
        n = hit + 1;                  // a hit auto-unwraps for `+`
    }
    log.info(f"n={n}");
}

n=42

p == nil compares against the null. There is no flow-typing: after the guard, hand the value to a typed binding when you want a plain T:

let err = map_response(resp, "no such repo or ref", "data.jsdelivr.com");
if (err != nil) {
    let why: str = err;           // the plain str behind the nullable
    eprint(why);
    return 1;
}

nil in an expected-?T position just works: let p: ?Node = nil;, or a left: nil field in a literal.

The (T, err) answer channel

Functions that can fail return a pair. The convention is uniform:

• empty err + a value — success;
• empty err + nil — a legitimate “not found”;
• non-empty err — failure.

The simplest err is a str message (empty string means success):

fn hex_dec(s: str) -> (bytes, str) {
    if (s.len() % 2 != 0) {
        return (bytes.zeroed(0), "hex: odd-length input");
    }
    // ... decode ...
    return (out.freeze(), "");
}

Nullable halves make both slots explicit — this is the standard library’s own shape, (?T, ?E):

// json's entry points
fn decodeJson<T requires JsonDeserialize>(s: str) -> (?T, ?DecodeJsonError);
fn encodeJson<T requires JsonSerialize>(v: T) -> (?str, ?EncodeJsonError);

The caller destructures and checks the err half first:

use json::{ decodeJson };
use ink::{ Logger };

pub fn main() {
    let log = Logger.new("json");
    let (n, e) = decodeJson<i64>("42");
    if (e == nil) {
        log.info(f"n={n}");
    } else {
        let why = e;
        log.info(f"decode failed at {why.at}");
    }
}

n=42

Integer arithmetic’s checked ladder uses the same idea in miniature: x.checked_add(y) answers (T, bool) where .1 is false exactly when the result escaped the width — see values and variables.

Building an error type

For errors a caller might want to branch on, pair a payloadless enum (the kind) with a fixed-field struct (the details). That is the shape json uses:

pub enum DecodeErrorKind { Unexpected, Truncated, InvalidUtf8, WrongType, Depth, Trailing }

pub struct DecodeJsonError {
    kind: DecodeErrorKind;
    at: i64;        // codepoint offset in the input
    got: str;       // the offending text
    expected: str;  // what the schema asked for here
}

The caller picks: branch on kind, or just render the fields:

use json::{ decodeJson };
use ink::{ Logger };

pub fn main() {
    let log = Logger.new("json");
    let (bad, be) = decodeJson<i64>("[1,2,3]");
    if (be != nil) {
        let why = be;
        // rejected at 0: got '[', wanted an i64
        log.info(f"rejected at {why.at}: got '{why.got}', wanted {why.expected}");
    }
}

rejected at 0: got '[', wanted an i64

Enums have no payloads — the struct carries the data. This split keeps every error a plain value: copy it, store it in a log, put a location next to it, test it.

panic and assert: for bugs, not for flow

panic("Rect: negative extents");        // abort with a message
assert(total == expected, "checksum");  // abort when the condition is false

Use these when continuing would be a lie: a broken invariant, an impossible state, a caller error that is a programming mistake. Data problems — a bad byte in a file, a missing key, a network error — are values and belong in the answer channel, so callers can recover.

A trap’s message and a stack trace (opt-in via capture_stacktrace()) land in the host’s diagnostics — see diagnostics, traces, and symbolication.

Erasure when you truly need it

When a value must cross a boundary that cannot name its type — host handles, heterogeneous boxes — opaque(v) seals it and opaque.downcast<T>(o) -> ?T recovers it (nil on a wrong type, never a trap):

use ink::{ Logger };

struct Point { x: i32; y: i32 }

pub fn main() {
    let log = Logger.new("opaque");
    let box1 = opaque(Point { x: 1, y: 2 });
    let p = opaque.downcast<Point>(box1);   // ?Point
    when (p != nil) {
        true -> { log.info(f"point {p.x} {p.y}"); },
        else -> { log.info("point: nil"); },
    }
}

point 1 2

x is T probes the box without recovering it. This is rut’s only any-shaped value, and it can do nothing until recovered — see the reference on opaque.

Put it together

use json::{ decodeJson, encodeJson };
use ink::{ Logger };

pub fn main() {
    let log = Logger.new("json");

    // a successful decode: (value, nil)
    let (n, e) = decodeJson<i64>("42");
    if (e == nil) {
        log.info(f"n={n}");
    } else {
        let why = e;
        log.info(f"decode failed at {why.at}: {why.expected}");
    }

    // encode answers the same shape: (?str, ?EncodeJsonError)
    let (s, ee) = encodeJson<[i64]>([1, 2, 3]);
    if (ee == nil) {
        let text = s;
        log.info(f"s={text}");
    } else {
        log.info("encode failed");
    }

    // a bad decode: the (nil, err) half answers the failure
    let (bad, be) = decodeJson<i64>("[1,2,3]");
    if (be == nil) {
        log.info("unexpected success");
    } else {
        let why = be;
        log.info(f"rejected at {why.at}: got '{why.got}', wanted {why.expected}");
    }
}

n=42
s=[1,2,3]
rejected at 0: got '[', wanted an i64

Next: modules and packages.

Modules and packages

A rut file is a module: one namespace, one visibility scope. A directory with a rut.toml is a package — the unit you depend on and share. This chapter walks up those two levels. The reference pages are modules and visibility, project structure and rut.toml, and dependency kinds.

What lives at module scope

Module scope contains declarations only: use, let, fn, struct, class, enum, trait, impl. Every statement lives inside a function — and loading a module executes nothing. There is no load-time side-effect ordering to reason about; the host loads your module and calls its entry point (conventionally pub fn main).

Module-level let initializers must be load-time literals — 42, "app", true. Arithmetic, record literals, and calls to user functions are not accepted in this build (there is no mutable module state; programs build their state in main).

use pouch::{ Vec };
use ink::{ Logger };

struct Point { x: f32; y: f32 }

let version = 1;                       // fine: a literal
let app_name = "app";                  // any literal works

fn main_body() { /* statements live here */ }

pub fn main() {
    let log = Logger.new("app");
    let origin = Point { x: 0, y: 0 }; // record literals live in function bodies
    log.info(f"{app_name} v{version} origin.x={origin.x}");
}

app v1 origin.x=0

Visibility

Every declaration has a visibility, and unannotated means module-private — the safe default. Nothing leaks unless it says pub:

The same forms apply to types, module lets, and class members. Structs are the exception: a struct is an open record — all members public, always, and its impl methods take no visibility annotation (they are as public as the type).

use — naming other modules

use imports names with Rust-like paths:

use ink::{ Logger };
use pouch::{ Vec };
use json::{ decodeJsonBytes, JsonDeserialize };

Builtin names — the primitives, str/bytes members, panic, assert, Vec-free array grammar, opaque — are ambient: no use needed. Package names from your manifest are; an unused name in a use is a lint, not an error.

Within one module, everything is visible — including declarations later in the file. Order never matters.

Packages: rut.toml

A package is a directory with a manifest. The small but complete case — one library package and one app:

greet/
├── pkg/
│   ├── rut.toml
│   └── greet.rut
└── app/
    ├── rut.toml
    └── main.rut

# greet/pkg/rut.toml
name = "greet"
entry.lib = "./greet.rut"

[deps]
pouch = { path = "../../rut/pouch" }   # the toolchain tree's pouch package

// greet/pkg/greet.rut
use pouch::{ Vec };

pub struct Greeting {
    to: str;
    lines: Vec<str>;
}

impl Greeting {
    pub fn new(to: str) -> Self {
        return Self { to: to, lines: Vec.new() };
    }

    pub fn add(mut self, line: str) {
        self.lines.push(line);
    }

    pub fn render(self) -> str {
        let mut out = f"dear {self.to},";
        for (let line of self.lines) {
            out = f"{out} {line}";
        }
        return out;
    }
}

fn shout(msg: str) -> str {   // module-private: no `pub`, never importable
    return f"{msg}!";
}

The app names its dependencies in [deps], by path — each package pulls its own dependencies along (ink brings the host surface rt; you never spell it):

# greet/app/rut.toml
name = "app"
entry.lib = "./main.rut"

[deps]
greet = { path = "../pkg" }
ink = { path = "../../rut/ink" }       # the logger package

// greet/app/main.rut
use greet::{ Greeting };
use ink::{ Logger };

pub fn main() {
    let log = Logger.new("app");
    let mut g = Greeting.new("rut");
    g.add("hello");
    g.add("from a package");
    log.info(g.render());
}

Run the app from its directory:

rut run .

dear rut, hello from a package

Resolution walks [deps] recursively (a dep’s own [deps] mount with it), with a cycle guard and first-mount-wins. Single loose files get a convenience: the rut CLI mounts the toolchain’s tree packages when your file says use ink:: or use pouch:: — see the rut CLI.

One package, several files

A package’s body can be split across files. The manifest splices them, base first, in listed order — into one module: one namespace, one visibility scope. A name private to one file is visible to every other file of the same package:

name = "app"
entry.lib = "./biz.rut"
entry.libs = ["./domain.rut", "./world.rut", "./app.rut"]

This is assembly, not an include form — cross-package references still go through use paths.

Dependency kinds

Beyond [deps], a manifest can declare two other relations:

• [peer-deps] — a package this one integrates with but never pulls: the consumer supplies it, or (with optional = true) the integration mounts only if the peer is already in the program’s closure. The standard library’s json package uses this to attach its Vec/map serialization impls only for programs that carry the container packages.
• [dev-deps] — mounted only when building/testing the package itself, never for a consumer.

[peer-deps]
pouch = { path = "../pouch", optional = true, lib = "./group-pouch.rut" }

[dev-deps]
pouch = { path = "../pouch" }

entry fn — the host-facing surface

pub publishes a name to other rut modules. entry publishes a function to the embedding host, with its signature checked against the boundary’s crossing rules at compile time:

entry fn hex_enc(data: bytes) -> str { .. }

An embedded application drives these entries; pub fn main is the conventional entry the rut run CLI calls. See the host boundary.

Tooling

rut run <file.rut | dir | mod.rutbundle> [--fuel N]  # compile + run
rut fmt <file.rut | dir> [--check]                   # format in place
rut pack <dir> [-o out.rutbundle]                    # a self-contained bundle
rut dump <file.rut>                                  # dump module info

Put it together

The greet project above is complete as shown — two directories, two manifests, two sources. Copy the trees into files and rut run . from greet/app to see:

dear rut, hello from a package

Next: async: tasks, workers, and channels.

Async: tasks, workers, and channels

rut’s concurrency is pull-based. An async fn compiles into a future — a cold value that runs nothing until something drives it. There are no promises that start on creation, no microtask queue, no implicit scheduling: the host owns time, and code progresses only when a driving loop pumps it. The model is described in the async model, with the full surface in async and await and tasks.

async fn and await

An async fn declares its context — cx: RunContext — as the first parameter. Calling it runs nothing: it returns a cold future. await is the one in-body suspension point, and it consumes the future:

async fn countdown(cx: RunContext, log: Logger, n: u32) {
    let mut i = n;
    while (i > 0) {
        log.info(f"t-{i}");
        await sleep(500);       // park here; the loop resumes the frame
        i -= 1;
    }
    log.info("lift-off");
}

The cx is engine-minted at call sites the way self is — you never pass it when calling an async fn:

launch_future(countdown(log, 3));   // no cx — the engine supplies it

Two consume paths, and exactly one per future:

• await fut — drive it from this async fn’s body. Legal only inside an async fn, and only for engine-woven futures (async-fn results and sleep).
• launch_future(fut) — hand it to the driving loop and keep a receipt. Returns a LaunchedFutureHandle<T>, which is not a future: it cannot be awaited or re-launched. Its abort() flags cancellation; the frame notices at its next checkpoint and runs its cleanup.

sleep(ms) is the one built-in pender — a Future<nil> that parks its frame until the VM’s clock reaches the deadline.

Both launch_future and sleep come from the async_host package:

use async_host::{ launch_future, sleep };

Who drives?

You never write a driving loop — the embedder does. The rut run CLI is an embedder: after main returns it pumps the loop — drain ready frames, advance the virtual clock to the next timer deadline, repeat — until nothing is pending. So a program launches work from main and the output simply appears:

rut run countdown.rut

t-3
t-2
t-1
lift-off

Calling an async function and awaiting it in the same body is the straight-line case; launching is for concurrency — independent work that overlaps through the loop’s interleaving.

Talking to the network: the http package

The standard http package is async-only where work actually waits. Everything else — the client, the verbs, the builder — is sync construction sugar:

use http::{ HttpClient };

let client = HttpClient.new();
let resp = await client.get(url).build().send(cx);

The shape, step by step:

• client.get(url) (or request(), post, put, patch, del) hands back a RequestBuilder; .method(..), .url(..), .header(k, v) (repeatable), .body(bytes) chain on it.
• .build() freezes a re-sendable Request.
• .send(cx) is the async point. It resolves at headers — the wire body is still unread.
• From the Response, take one of two readbacks:
  • await resp.body(cx) — drain the remaining body in one future;
  • resp.byte_stream() then await stream.next(cx) — one chunk per future, nil at end-of-stream, for bounded-memory downloads.

Errors come back as data, not traps: status 0 is reserved for transport failure (resp.transport_error() carries the reason), any real status — 4xx and 5xx included — is a normal response (resp.ok() is the 2xx test), and a mid-read wire death surfaces as nil from next() with the reason in stream.error().

A complete worker from the repository’s GitHub-viewer example — send, then drain:

async fn do_list(cx: RunContext, client: HttpClient, owner: str, repo: str, rf: str) -> i32 {
    let url = f"https://data.jsdelivr.com/v1/packages/gh/{owner}/{repo}@{rf}";
    let resp = await client.get(url).build().send(cx);
    if (resp.status() == 0) {
        let why: str = resp.transport_error();
        eprint(f"rgh: network error: {why}");
        return 1;
    }
    if (!resp.ok()) {
        eprint(f"rgh: CDN {resp.status()}");
        return 1;
    }
    let (tree, e) = decodeJsonBytes<Root>(await resp.body(cx));
    if (e != nil) {
        let why: DecodeJsonError = e;
        eprint(f"rgh: bad tree JSON at {why.at}");
        return 1;
    }
    // ... print the tree ...
    return 0;
}

The stream lane walks chunks — send, then loop:

let resp = await client.get(url).build().send(cx);
let stream = resp.byte_stream();
while (true) {
    let c = await stream.next(cx);
    if (c == nil) {
        let rerr = stream.error();
        if (rerr != nil) { return 1; }   // failed mid-read
        break;                            // clean end of stream
    }
    let chunk: bytes = c;
    total += chunk.len();
}

await select, join, and structured scopes

Racing futures (await select { fut1 -> .., fut2 x -> .. }) and joining a launched future’s value (await handle) are spelled in the grammar but not in this build — the compiler gates them. Cancellation is here: handle.abort() flags the frame, and the probe at its next checkpoint unwinds it deterministically, running cleanup in reverse declaration order. See tasks for the roadmap.

Workers and channels

For true parallelism, a host can spawn workers — separate VMs on separate threads with separate heaps. There is no shared memory: all data crosses typed channels, and what may cross is a checked rule — primitives and str copy; a cell (vec, record, class instance) transfers when exclusively held, else deep-copies; endpoints (Sender/Receiver) transfer; closures do not cross. A trap in a worker kills only that worker. The API is a host facility (spawn_worker, Channel<T>), so its shape depends on your embedder — see workers and channels.

Put it together

use async_host::{ launch_future, sleep };
use ink::{ Logger };

async fn countdown(cx: RunContext, log: Logger, n: u32) {
    let mut i = n;
    while (i > 0) {
        log.info(f"t-{i}");
        await sleep(500);
        i -= 1;
    }
    log.info("lift-off");
}

pub fn main() {
    let log = Logger.new("countdown");
    launch_future(countdown(log, 3));
}

t-3
t-2
t-1
lift-off

Next: the standard library.

The standard library

The standard library splits in two. core is the only true standard — a prelude of builtin names that are ambient: in scope in every compilation unit, no use needed. Everything else is a set of swappable packages shipped in the toolchain tree — a program that wants one says so (a use line; the CLI mounts the tree packages for loose files automatically, and a package program lists them in its manifest). Any of them can be replaced wholesale; the engine knows none of their names.

The reference page is core and the swappable packages.

What’s always there (core)

Reporting and bugs

panic("Rect: negative extents");       // abort with a message
assert(total == expected, "checksum"); // abort when false (message optional)

Integer safety ladder

Every integer width carries compiler-lowered methods. Plain +/-/* trap on overflow; these never do:

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("ladder");
    let mut v: u8 = 250;
    v = v.wrapping_add(10);            // 4 — two's-complement wrap
    let over = 200u8.checked_add(100); // (44, false) — .1 false = escaped
    let sat = 200u8.saturating_add(100); // 255 — clamp at the bounds
    log.info(f"v={v} over=({over.0}, {over.1}) sat={sat}");
}

v=4 over=(44, false) sat=255

checked_* answers (T, bool); .0 holds the wrapped bits either way. Pick per call site: a checksum wraps, a length checks.

str members

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("str");
    let s = "héllo rut";
    log.info(f"len={s.len()} first={s.code()}");
    log.info(f"at1={s.code_at(1)} octets={s.encode().len()}");
    log.info(f"view={s.slice(6, 9)}");
    let head: str = "héllo";
    log.info(f"starts={s.starts_with(0, head)}");
    let joined = string_join(["rut", "runs"]);
    log.info(f"joined={joined}");
    let h = str.from_code(72);
    log.info(f"from_code={h}");
}

len=9 first=104
at1=233 octets=10
view=rut
starts=true
joined=rutruns
from_code=H

s.slice deserves a second look: no octets move; the view records a window over the parent, prints, compares by content, iterates, and can re-slice. Codepoint access is spelled with integers — str.from_code(n) builds the 1-codepoint str for a u32. There is no split primitive; tokenizing rides s.scan(from, set) over a caller-owned [u8] class table. See string slicing and views.

bytes members

use ink::{ Logger };

pub fn main() {
    let log = Logger.new("bytes");
    let b = "rut runs".encode();
    log.info(f"len={b.len()} decode={b.decode()}");
    let copy = b.clone();     // the ONLY copy escape hatch
    let z = bytes.zeroed(4);
    let from = bytes.from([1, 2, 3]);
    log.info(f"same={copy == b} zeroed={z.len()} from={from.len()}");
}

len=8 decode=rut runs
same=true zeroed=4 from=3

Erasure and cleanup

opaque(v) seals any value for recovery with opaque.downcast<T>(o) -> ?T — see errors and optionality. on_drop(p, cleanup) runs a callback when a cell’s refcount reaches zero, and Weak(v) holds a non-keeping reference (upgrade() -> ?T, nil once the referent died) — the memory stories live in the Rc heap and destructors and weak references.

StrBuf — the raw growable builder

Prefer the package face below; the engine cell under it is StrBuf(cap) with push/push_code/len/finish.

One gated name

NAN is core’s single constant, deliberately name-explicit: use core::{ NAN };. The float constants live in calc.

pouch — the growable sequence

use pouch::{ Vec };
use ink::{ Logger };

pub fn main() {
    let log = Logger.new("pouch");
    let mut xs: Vec<i32> = Vec.new();         // or Vec.with_capacity(64)
    xs.push(10);                              // amortized O(1)
    let v = Vec<f32>.filled(0.0, 1024);       // n slots of one value
    let w = Vec<i32>.from([1, 2, 3]);         // from a fixed array (copies)
    let x = xs[0];                            // indexing
    xs[0] = 42;                               // needs a `mut` binding
    let last = xs.pop();                      // removes + returns; traps if empty
    let n = xs.len();
    let mut total = 0;
    for (let e of w) {                        // iteration
        total += e;
    }
    log.info(f"x={x} last={last} len-after-pop={n} filled={v.len()} total={total}");
}

x=10 last=42 len-after-pop=0 filled=1024 total=6

Vec<u8> is the mutable byte builder: push bytes, then freeze() into the immutable bytes. xs.as_array() copies the live elements into a fixed [T]. A slice(from, to) window is compiler-lowered — an O(1) view that writes through to the parent vector.

nmapset — keyed collections

use nmapset::{ HashMap, HashSet };
use ink::{ Logger };

pub fn main() {
    let log = Logger.new("nmapset");
    let mut counts: HashMap<str, i32> = HashMap.new();
    let fresh = counts.put("rut", 1);          // answers true when the key was NEWLY added
    let mut n = 0;
    let hit = counts.get("rut");   // ?i32 — nil means absent
    if (hit != nil) { n = hit + 1; }
    let there = counts.has("rut");             // membership
    let gone = counts.remove("runs");         // answers whether it was there
    let size = counts.len();

    let mut seen: HashSet<str> = HashSet.new();
    let first = seen.put("x");     // true — newly added
    let again = seen.put("x");     // false
    log.info(f"fresh={fresh} n={n} has={there} removed={gone} len={size}");
    log.info(f"first={first} again={again}");
}

fresh=true n=2 has=true removed=false len=1
first=true again=false

Keys come from a fixed set — integers, bool, str, bytes (no floats: they have no stable equality contract) — hashed by the host; a user-defined key escapes by encoding canonically to bytes. A hit returns the stored cell, not a copy. There is no iteration surface: maps and sets answer questions, they don’t walk.

strbuild — the string builder

use strbuild::{ StringBuilder };
use ink::{ Logger };

pub fn main() {
    let log = Logger.new("strbuild");
    let n = 3;
    let mut b = StringBuilder.new();     // or StringBuilder.with_cap(1024)
    b.append("count: ");
    b.append_code(33);                   // one codepoint
    b.append(f" up to {n}");             // appends are amortized O(1)
    let s = b.build();                   // the ONE materialization; builder keeps its buffer
    log.info(s);
}

count: ! up to 3

Every out = f"{out}{chunk}" loop copies the whole prefix each time; the builder appends into one growable cell and copies once, at build().

calc — float math

use calc::{ Math };
use ink::{ Logger };

pub fn main() {
    let log = Logger.new("calc");
    let x: f64 = -2.0;
    let a: f64 = 3.0;
    let b: f64 = 7.0;
    let d = Math.sqrt(2.0);        // f64 host fns: sin, pow, atan2, fma, ...
    let f = Math.sqrt_f(2.0f32);   // f32 twins under a `_f` suffix
    let mx = Math.max(a, b);
    let sg = Math.signum(x);
    log.info(f"sqrt={d} sqrt_f={f} pi={Math.PI}");
    log.info(f"abs={Math.abs(x)} min={Math.min(a, b)} max={mx} signum={sg}");
}

sqrt=1.4142135623730951 sqrt_f=1.4142135 pi=3.141592653589793
abs=2 min=3 max=7 signum=-1

rut has no overloading, so the width lives in the name. The integer ladder is not here — those are core’s, always available.

json — encode and decode

use json::{ decodeJson, encodeJson };
use ink::{ Logger };

pub fn main() {
    let log = Logger.new("json");
    let (n, e) = decodeJson<i64>("42");            // (?T, ?E) — see errors
    let (s, ee) = encodeJson<[i64]>([1, 2, 3]);    // (?str, ?EncodeJsonError)
    if (e == nil && ee == nil) {
        let text = s;
        log.info(f"n={n} s={text}");
    }
}

n=42 s=[1,2,3]

Decode is direct and schema-driven: your type’s impl JsonDeserialize reads exactly the fields it expects, no intermediate tree. Your types opt in with two small impls; the container impls (Vec<T>, the map/set family) mount automatically when those packages are in your program. Error values are a kind enum plus a struct with .at/.got/.expected — see errors and optionality.

ink — logging

There is no console, no print — all output goes through a logger:

use ink::{ Logger };

pub fn main() {
    let n = 3;
    let log = Logger.new("app");
    log.info(f"started with {n} items");
    log.debug("..."); log.warn("..."); log.error("...");
}

started with 3 items
...
...
...

Logger is a plain rut class over a host-provided handle; the embedder chooses the sink (the rut CLI prints to stdout). The same pattern — declare a host surface in a .d.rut, wrap it in a rut class — is how any embedder package reaches rut code; see embedding and native modules.

http

The async HTTP client lives with the concurrency chapter — builder construction, send(cx) resolving at headers, body drains and byte streams — in async: tasks, workers, and channels.

Put it together

use pouch::{ Vec };
use strbuild::{ StringBuilder };
use calc::{ Math };
use ink::{ Logger };

pub fn main() {
    let log = Logger.new("std");

    // Vec: build, pop, read
    let mut v: Vec<i32> = Vec.new();
    v.push(10);
    v.push(20);
    v.push(30);
    let last = v.pop();
    log.info(f"len={v.len()} last={last} first={v[0]}");

    // fixed arrays + string_join from core
    let parts: Vec<str> = Vec.from(["rut", "runs"]);
    log.info(f"joined={string_join(parts.as_array())}");

    // StringBuilder: amortized appends, one materialization
    let mut b = StringBuilder.new();
    b.append("count: ");
    b.append_code(33);
    b.append(f" up to {v.len()}");
    let s = b.build();
    log.info(s);

    // calc's Math namespace (f64) and its f32 twins (_f)
    let d = Math.sqrt(2.0);
    let f = Math.sqrt_f(2.0);
    log.info(f"sqrt2 f64~{d} f32~{f} pi={Math.PI}");

    // assert: the builtin bug-catcher
    assert(v.len() == 2, "vec should hold two");
    log.info("asserted");
}

len=2 last=30 first=10
joined=rutruns
count: ! up to 2
sqrt2 f64~1.4142135623730951 f32~1.4142135 pi=3.141592653589793
asserted

That completes the tutorial. From here, the core concepts explain why the language is shaped the way it is, and the reference pins down every rule.

Design goals

rut is a small, statically typed, embeddable scripting language with Rust-flavored syntax, implemented in Rust. It is designed to be the scripting layer of host applications — UI apps in particular — in the role a JavaScript engine usually plays: a safe, hot-reloadable language that drives the host’s object graph.

The difference is structural, not cosmetic. In an embedded JS engine the host’s types are erased (Element, Store are empty interfaces; the real types exist only in .d.ts files and get “recovered” by convention), cancellation is emulated on top of promises, and every value crossing the bridge is re-parsed and re-coerced by hand. rut is built so those three problems cannot arise: types are kept at runtime, coroutines are natively poll-based, and host values have deterministic lifetimes.

The pillars

Fully static, reified types. There is no dynamic typing, no any, no gradual typing. Every value’s exact type is known to the compiler and carried at runtime — type tests, checked erasure, and host-boundary checks all read the same runtime truth. See reified types and layouts.

Types make code faster. The bytecode is typed, generics monomorphize, and primitive buffers stay flat: a fixed array of f32 is a packed f32 buffer, not an array of boxed numbers. There is no JIT and none is needed — the code shape a JS JIT exists to speculate on (polymorphic property loads) does not exist in rut.

Everything is a value — with two honest regimes. Primitives move by value; every composite (str, bytes, records, arrays, trait objects, erasure boxes) is a reference-counted cell whose handle copies in O(1). Sharing is the default and visible; there is no hidden copying. See everything is a value.

Poll-based coroutines. async/await compiles to cold state machines with Rust-style poll semantics: a future that nobody drives costs nothing, and cancellation drops the state machine at its suspension point. No promises, no microtask queue. See the async model.

Reference counting; no collector. Objects die the moment their last reference goes away, so destructors are deterministic — host resources (threads, sockets, textures) release at a knowable point, not “sometime at GC”. Strong cycles leak by design; weak references are the first-class answer. See memory.

No JIT. All optimization happens ahead of time: fold, inline, monomorphize, emit typed bytecode. What you run is what you compiled — predictable startup, predictable per-op cost, no tiering.

Embeddable by contract. The host registers native functions whose Rust signatures are the declared surface; every crossing is type-checked against reified types, and the host owns the event loop, the fuel budget, and the clock. See the host boundary and the bytecode VM.

Why not JavaScript

The case against shipping a JS engine — not just this or that implementation — is fourfold, and each item has a structural answer:

1. History debt compounds. Two nullish values, coercing ==, typeof null, implicit semicolons: each is a permanent liability the ecosystem re-implements forever. rut starts from a closed, small grammar — absence is nil on a nullable type, errors are values, and legacy JS keywords are reserved words whose error message tells you what to write instead. Nothing legacy can accrete.

2. Conformance means implementing the world. A compliant engine needs BigInt, Intl, Date’s quirks, microtask ordering — thousands of person-hours before user code runs. rut’s built-in contract is deliberately tiny: primitives, sequences, channels, string building. Everything else is library — maps and sets, JSON, logging, and the host’s own domain are ordinary packages, several of them written in rut and swappable.

3. Too slow without a JIT. Interpreter-only JS runs one to two orders of magnitude slower, because a JS engine’s speed is its JIT. rut’s no-JIT stance is viable only because the language is statically typed: calls bind statically whenever the call site names one concrete type, and dynamic dispatch is a checked vtable hop that happens only where the program actually erases types.

4. Too much memory. JS values are boxes — per-object headers, tagged pointers, boxed array elements, collector overhead. rut’s answer is layout: untagged 8-byte slots, record payloads as slot arrays, flat primitive buffers, and reference counting with no collector pass on the hot path.

What “no dynamic typing” leaves you

Erasure is never silent — it is spelled and checked:

• Trait-typed values (d: Drawable) for polymorphism. Dispatch is dynamic only where a value may be one of several concrete types, and a trait-typed value still carries its exact class at runtime.
• The opaque box (opaque(v), opaque.downcast<T>(o)) for storage. Erasure mints a checked box; recovery checks the runtime type and yields nil on a mismatch — never a silent wrong-type read.

JSON-shaped data, heterogeneous collections, and any-shaped host APIs all route through these two doors, which is what keeps “every value has a runtime type” true without giving up dynamism where it earns its keep.

The execution model

source ──► lexer/parser ──► typecheck ──► IR ──► typed bytecode ──► VM
                                   (fold, inline, monomorphize)

• One thread per VM. A Vm instance runs on one thread with one heap and no atomics; workers are separate VMs communicating by typed message passing.
• The host owns time. The VM exposes stepping verbs — drain the ready queue, expire timers, poll with a deadline — plus op budgets and interrupt callbacks. A UI host drives script between frames and stays responsive; a test host virtualizes the clock and gets fully deterministic schedules.
• Traps stop at the boundary. A panic in script (overflow, nil deref, a failed assert) unwinds as a Trap value to the host call — rut code never catches one. Bugs become host-visible errors with a script backtrace, not corrupted state.

What this buys you

If you are writing scripts: assignments never deep-copy; cleanup runs when the last reference dies; a miss is nil, a failure is a returned err string, and a crash is a loud trap with a real stack trace. If you are embedding: you declare your API once in a rut declaration file, bind it with typed Rust closures, and the compiler plus the load-time verifier reject every mismatched shape before any script runs — there is no bridge boilerplate to maintain.

The rest of this section walks each pillar in depth; the tutorial shows the day-to-day syntax, and the reference pins down exact rules.

Everything is a value

rut’s type system has one spine: every name binds a value, and there are exactly two ways a value can exist. Primitives and fn values are immediate — moved by copying their bits. Every other type is a cell — a heap object whose handle is what gets copied. That single split explains assignment, parameter passing, equality, and what bytes.clone() is for.

The two regimes

There is no third regime. No type is “sometimes copied, sometimes shared”: a struct value never silently deep-copies, a str never silently aliases. The regime is a property of the type, known at compile time, and the compiler emits the right move for it.

Sharing is the law for cells

let b = a on any cell type is one handle move: the new binding retains the cell, the old binding releases it. Passing a million-element array to a function retains once. A loop binding iterates the stored elements, not copies of them.

use ink::{ Logger };

struct Point { x: f32; y: f32 }

pub fn main() {
    let log = Logger.new("values");
    let mut p = Point { x: 1, y: 2 };
    let q = p;          // q and p name ONE cell
    p.x = 4;            // q.x is 4 now — sharing is the law
    log.info(f"q.x = {q.x}");   // read through the other alias
}

q.x = 4

Mutation through an alias is visible through all of them, in both directions. What gates writing is the mut-binding rule — a binding must be declared mut to be written through — never the sharing itself. Sharing is always safe: a handle keeps its referent alive, so nothing dangles, and there is no borrow checker because there are no loans.

If you want a value that aliases nothing, you build one: a literal, a constructor, a copy of the fields you need. The language has exactly one copy escape hatch — bytes.clone(), a one-shot deep copy of a binary buffer, for interop hand-offs. There is no generic clone: a divergent value of any other type is unreachable by construction, which is what makes aliasing something you can reason about locally.

?T — the nullable

Absence is nil on a nullable type, spelled as a prefix on the type: ?T is “a T or nil”. ? applies to the type term that follows, so [?T] is an array of nullables while ?[T] is a nullable array, and ??T chains (and unwraps transitively at use).

The coercions are one line: T → ?T boxes; ?T → T derefs. The box is a fresh one-slot cell that aliases the value’s cell — boxing a record shares it, boxing a primitive copies its bits. The deref is implicit at every value position: field access, method calls, indexing, iteration, arithmetic all read through the box.

use ink::{ Logger };

struct User { id: i64; name: str }

fn lookup(id: i64) -> ?User {
    if (id == 7) { return User { id: 7, name: "ada" }; }
    return nil;             // a miss is nil, nothing else
}

pub fn main() {
    let log = Logger.new("values");
    let u = lookup(7);                // ?User
    log.info(f"u.name = {u.name}");   // auto-deref when non-nil
    let missing = lookup(8);
    log.info(f"miss is nil: {missing == nil}");   // guard where absence is expected
}

u.name = ada
miss is nil: true

A nil reaching a value use traps (NilDeref) — never a silent read. Guard with u == nil where absence is expected; the trap is the bug-catcher, not the semantics. A miss is nil and nothing else: a lookup that finds nothing returns ?V, and callers compare against nil.

== is honest about the regime

• Primitives compare by value.
• str compares by content (codepoints); bytes by octets.
• Everything else compares by identity — two bindings are equal exactly when they name the same cell.

Identity is the only equality full sharing can defend: two separately built [1, 2] arrays are two cells, so [1,2] == [1,2] is false. Content comparison is a loop over fields, written where content is the contract. The one place identity quietly behaves like value equality: enum variants are immortal singletons, so Flavor.Sour == Flavor.Sour is true.

The answer channel: a pair

There is no exception type and no Result monad. Failures are data in the second element of a record — (value, err) — with one documented convention:

• an empty err plus a value is success;
• an empty err plus nil means “not found”;
• a non-empty err means “failed”.

use ink::{ Logger };

fn parse_hex(s: str) -> (bytes, str) {
    if (s.len() % 2 != 0) {
        return (bytes.zeroed(0), "hex: odd-length input");
    }
    let n = s.len() / 2;
    let mut buf: [u8] = [0u8; n];
    for (let i = 0; i < n; i += 1) {
        let hi = hex_digit(s.code_at(i * 2));
        let lo = hex_digit(s.code_at(i * 2 + 1));
        if (hi < 0 || lo < 0) {
            return (bytes.zeroed(0), "hex: not a digit");
        }
        buf[i] = ((hi * 16) + lo) as u8;
    }
    return (bytes.from(buf), "");       // (data, "") on success
}

fn hex_digit(c: u32) -> i64 {
    if (c >= 48 && c <= 57) { return (c - 48) as i64; }   // '0'..'9'
    if (c >= 97 && c <= 102) { return (c - 87) as i64; }  // 'a'..'f'
    return -1;
}

pub fn main() {
    let log = Logger.new("values");
    let (raw, err) = parse_hex("4869");
    if (err != "") { log.info(f"err: {err}"); return; }   // propagate
    log.info(f"ok: {raw.decode()} ({raw.len()} bytes)");
    let (raw, err) = parse_hex("486");
    if (err != "") { log.info(f"err: {err}"); }           // the failure channel
}

ok: Hi (2 bytes)
err: hex: odd-length input

The pair destructure in return position is free — the compiler fuses the mint away — so this shape costs nothing on hot paths. At the host boundary the same pair crosses field by field, which makes entry fn -> (?T, err) the standard answer a Rust embedder reads.

Consequences you feel day to day

• Reassignment is cheap. Moving containers around — returning them, storing them, restructuring them — is handle traffic, not payload traffic. Algorithms that churn records and arrays pay aliasing, not copying.
• Loop variables are fresh per iteration but share elements. A for (let x of xs) loop hands you the stored element; writes through it mutate the sequence. Each iteration is a fresh binding.
• Containers of primitives stay flat. A fixed [i32] is a packed i32 buffer; growable sequences of primitives store raw payloads with a one-byte nil tag — no per-element heap box.
• Erasure is a box. opaque(v) mints an erasure box; recovery is opaque.downcast<T>(o), checked against the runtime type. See reified types and the reference on opaque.

The memory machinery under all of this — refcounts, deterministic destructors, weak references — is the next chapter’s subject: memory. The exact rules live in the reference on by-reference and nullable.

Reified types and layouts

Types in rut are not a compile-time fiction. Every value’s exact type is available at runtime — generics included: a Cache<i32> and a Cache<str> are different types to the VM, with distinct identities and distinct method sets. This chapter explains where that reified reality lives, what it is used for, and how values are actually laid out.

The mental model

Think of the VM as keeping a type table: one descriptor per instantiated type — its kind, its field list, its trait impls, and for composites the method tables its instances point at. Every heap cell’s header names an entry in that table. A value never “forgets” its type, because its type is one field read away.

Types themselves are not first-class script values — you cannot put a type in a variable or write a function over types. What you get is the language-facing surfaces of reification:

• is type tests — x is Circle (exact) and x is Drawable (capability: does this value’s type have a registered impl?).
• Checked erasure — opaque.downcast<T>(o) reads the box’s runtime type and recovers the payload, or nil on a mismatch.
• Host-boundary checks — native functions declare parameter types once; every call is checked against them.
• Debugging and traces — error messages, backtraces, and formatter output name real runtime types.

Why reification is load-bearing

The reason rut can check everything cheaply is that the runtime type is always reachable:

1. The host boundary needs no coercion code. A native fn declares (Opaque, str, str) -> nil once; the VM checks each argument’s runtime type at the crossing. There is no bridge-side “re-parse-and-pray” layer, because a wrong-shaped call fails loudly at the boundary.
2. Erasure is checked, not blind. opaque(v) stamps the box; opaque.downcast<T> consults the stamp. A box answers type tests by the box — o is T misses for every payload type — so the only way back to the payload is the checked recovery. Erasure without reification would be any; with reification it is a sealed box.
3. Distinct instantiations. Vec<f32> and Vec<f64> are different types everywhere — in the type table, in method resolution, at the host boundary. Nothing about a generic’s type argument is erased.
4. Serialization and tooling. Reflection walks the same descriptors, which is how userland JSON encoding is complete without annotations or macros on your types.

Slots: the untagged hot path

Inside the VM, registers and record fields are untagged 8-byte slots. The bytecode is typed — every register’s static type is recorded in the function’s signature and re-verified at load — so hot paths carry no type tags at all:

#![allow(unused)]
fn main() {
#[derive(Clone, Copy)]
pub union Slot {
    pub i: i64,            // ints, bool: the canonical scalar width
    pub f: f64,            // floats: f32 widened
    pub r: *mut CellVal,   // every non-primitive: a cell handle
}
}

A primitive is its bits; a composite is a handle to a cell. The tagged world — a value that carries its type with it — exists only at the host boundary, where Rust code that cannot trust static types receives checked, typed values.

Record layout: one slot per field

Both struct and class values live in a cell: a header (refcount + type id), a pointer to the type’s vtable when the type has methods, and the payload — a slot array, one untagged slot per field, in declaration order.

• Primitive fields are widened into their slot; composite fields are cell handles.
• Visibility, generic parameters, and impl blocks elsewhere add nothing — the payload depends only on the field list.
• Field access is by index; there are no hidden members and no inheritance, so there is no base-class prefix and nothing to walk.
• Fixed arrays of primitives ([f32]) keep their elements flat and packed at machine width — the one place values live inline. Growable sequences are rut-library classes over such arrays.

Consequences:

• size_of/align_of do not exist, deliberately. Layout is an implementation detail, not an API — rut has no C-ABI struct surface for hosts to mirror. Hosts see records only through the checked boundary (see the host boundary).
• A record’s memory cost is its field count times 8 bytes plus the cell header, which is exactly what the heap budget charges.
• Widening a value to a trait type allocates nothing: the trait-typed value is the same cell, reinterpreted through its vtable.

Vtables: one per type, attached at construction

A cell’s vtable is filled when the value is constructed and never changes. It names the exact type and holds one entry per trait method the type implements, keyed by a global (trait instantiation, method) id — Slice<Point> and Slice<str> have separate slot sets, because they are separate trait instantiations.

A call through a trait object is two loads and an indirect jump:

d.draw(g)          ; d: Drawable, draw has global slot 3
  obj  <- d.cell
  code <- obj.vtable.slots[3]
  call code(d, g)

An inherent method call — c.area() on a concrete c — compiles to a direct call with no table involved. The dispatch rules that choose between the two are the subject of the next chapter, traits and dispatch.

Type tests, lowered

Every type test is a small, pure read:

• Concrete test (d is Circle): load the value’s runtime type id, compare. When the receiver’s static type already answers, the compiler folds it to a constant.
• Trait probe (x is Drawable): load the type id, scan the descriptor’s registered impl list. Pure in its inputs, so repeated probes deduplicate and invariant ones hoist.
• Downcast (opaque.downcast<T>(o)): the same type-id compare, followed by the guarded payload extract.

There is no type_of(x) returning a manipulable value and no runtime layout introspection — the descriptors serve the VM, the checks, and tooling, not userland metaprogramming. Reflection over data (walking fields to serialize) is a library facility built on the same tables; see the reference on reflection.

What this buys you

• Type errors are runtime facts, not conventions: a host call, a downcast, or a trait probe is checked against the same table the VM dispatches through.
• One runtime truth per value — the vtable that answers dispatch is the same one that answers is.
• The tag-free hot path keeps the interpreter’s arithmetic and field traffic at raw slot speed while reification costs only what the program’s dynamic features actually use.

Traits and dispatch

A trait in rut is a named contract: a list of method signatures that a type can implement — by name, in an impl block. Satisfaction is nominal: the impl block is the admission, and nothing else. A type whose members happen to match a trait’s shapes is not an implementor; some module must say impl I for T.

The shape of a trait

use ink::{ Logger };

trait Shape {
    fn area(self) -> f64;
    fn scale(v: f64);
}

struct Point { x: f32; y: f32 }

impl Shape for Point {
    fn area(self) -> f64 { return self.x as f64; }
    fn scale(v: f64) { }    // the impl must list every trait method
}

pub fn main() {
    let log = Logger.new("traits");
    let p = Point { x: 3, y: 4 };
    log.info(f"area = {p.area()}");     // a concrete receiver: static
}

area = 3

• Methods only, no bodies. A trait declares signatures — no fields, no properties, and no default implementations, ever. One member kind means one dispatch candidate per call; a default body would be a second candidate with a resolution law of its own.
• Two impl forms. impl T { .. } defines the type’s inherent methods and may live only in the module that declares T. impl I for T { .. } defines a trait implementation; its methods are exactly the trait’s, with no pub (they are as visible as the trait).
• One impl per pair, program-wide. Two modules implementing the same trait for the same type is a link error that names both. The impl registry — merged when modules link — is the single source of truth for “who implements what”.
• Placement is pair-local. A trait impl may live in the trait’s package or the type’s package — at least one side of every (trait, type) pair must be yours. Implementing two foreign types’ pairing is rejected outright; there is no orphan rule beyond that.
• Any nominal type can be a target — classes, structs, and even primitives (impl MyTrait for i32 registers like any other impl). Traits may be generic (Wrap<T>, Iterator<E>); each instantiation has its own identity and its own method slots, and an impl may be parameterized by the target’s own type parameters — impl Encode<T> for Store<T> registers a template that serves every instantiation, unless a concrete impl shadows it.

Type bodies are fields only — a fn inside a struct or class body is a parse error. Every method, inherent or trait, lives in an impl block.

Trait-typed values

A trait name in type position is the bare name — there is no object-type keyword:

use ink::{ Logger };
use pouch::{ Vec };

trait Shape {
    fn area(self) -> f64;
}

struct Circle { r: f64 }
struct UnitSquare { side: f64 }

impl Shape for Circle {
    fn area(self) -> f64 { return 3.14159265358979 * self.r * self.r; }
}

impl Shape for UnitSquare {
    fn area(self) -> f64 { return self.side * self.side; }
}

struct Canvas { log: Logger }

impl Canvas {
    fn render(self, a: f64) { self.log.info(f"blitted a shape of area {a}"); }
}

fn blit(g: Canvas, s: Shape) { g.render(s.area()); }   // a parameter over any Shape

pub fn main() {
    let log = Logger.new("shapes");
    let g = Canvas { log: log };
    let mut mixed: Vec<Shape> = Vec.new();   // heterogeneous storage
    mixed.push(Circle { r: 1.0 });
    mixed.push(UnitSquare { side: 2.0 });
    for (let s of mixed) { blit(g, s); }
}

blitted a shape of area 3.14159265358979
blitted a shape of area 4

A trait-typed value is a reference to a real cell that still carries its exact class. Widening a concrete value to a trait it implements is implicit on assignment and argument passing, allocates nothing, and is gated by exactly one question: does the registry hold an impl I for T? There is no top type to widen to, and intersection types (A & B) are ruled out by design — when you need both contracts, declare a trait that spells both.

Dispatch: the two-rule law

Every method call compiles under one of exactly two rules, fixed at compile time as a property of the call site:

1. Static — the call site names exactly one concrete type. The call binds directly to that type’s method, no table involved:
   • a concrete receiver (c.area() on c: Circle);
   • a trait-typed local whose single concrete origin the compiler tracked (let d: Shape = Point { .. }; d.area());
   • a trait-typed parameter — the function specializes per concrete argument at monomorphization, so a trait parameter is effectively an implicit generic bound;
   • inside monomorphized generics.
2. Vtable — the receiver is trait-typed with multiple possible concrete origins:
   • elements of a heterogeneous container (Vec<Shape>);
   • trait-typed field and element loads (the cell may hold any implementor);
   • branch-merged bindings (if arms carrying different concretes into one trait-typed variable).

The origin analysis is conservative: any merge, indirection, or cross-function flow counts as multiple. Mis-analysis cannot produce wrong code — an uncertain origin costs one vtable hop, never a wrong static bind. And the same descriptor that answers vtable calls answers is probes: one runtime truth per value.

Type tests

expr is Type yields a bool and is total — it never traps. Two probes, one keyword:

• Concrete RHS: is the value’s exact type T? (No inheritance — a single id compare.)
• Trait RHS: does the value’s exact type have a registered impl? A capability probe, usable on any value (k is Hashable).

is has no flow-sensitive effects: a true probe does not narrow x. When the static type already answers, the probe folds at compile time. Trait-typed values cannot be downcast to a concrete type at all — if you need Circle-specific behavior behind a Drawable, put that behavior in the trait. The one recovery path for erased values is the explicit opaque box (see the reference on opaque).

Visibility: the use-both gate

Calling a trait method requires both names in scope: the type (by declaration or use) and the trait (use). Inherent methods need only the type. A call that matches a registered impl whose trait no use brings in is an error — “use I to call its methods on T” — so an added trait method can never silently change what someone else’s call site means.

The iteration protocol

A type is iterable when it implements the builtin Iterator<E> trait:

use ink::{ Logger };

class CountUp {
    n: i32;
}

impl Iterator<i32> for CountUp {
    fn __iterate(self, emit: fn(i32) -> bool) {
        for (let i = 1; i <= self.n; i += 1) {
            if (!emit(i)) { return; }
        }
    }
}

pub fn main() {
    let log = Logger.new("iter");
    for (let v of CountUp { n: 3 }) {
        log.info(f"tick {v}");
    }
    log.info("done");
}

tick 1
tick 2
tick 3
done

for (let v of it) { body } desugars to it.__iterate(emit) with a synthetic closure: the body runs, then emit returns true; break returns false. The loop variable is the closure’s parameter — a fresh binding per iteration by construction. The builtin sequences ([T], str, bytes, and the standard growable Vec) keep fused index loops instead; they never pay a per-element call.

Engine contracts are traits too

The async machinery is spelled as builtin traits — Future<T> and RunContext — which the engine names but does not close: a hand-written type can impl Future<nil> for MyFuture through the same registry as any other impl and be driven by the same loop. See the async model and the worked example in 04 — Custom async.

Equality is not a trait

== is builtin and cannot be opted into or out of: primitives compare by value, str/bytes by content, everything else by cell identity. Field-wise comparison is a loop you write, or the map packages’ own key rules. See everything is a value.

What this buys you

• Nominal satisfaction keeps the registry exact: capability probes, widening, and vtable fills all read one table, so casts stay cheap and runtime identities stay meaningful.
• The two-rule law makes dispatch predictable: you can tell, per call site, whether you are paying a hop.
• Placement rules keep coherence decidable across packages without a global uniqueness proof — one of the pair is always local.

The async model

rut’s concurrency is pull-based, built on one noun: Future<T>. Calling an async fn runs nothing — it produces a cold future. The future runs when something drives it: an await inside another async fn, or a launch into the VM’s queue. There are no promises, no microtask queue, and no implicit scheduling: the host owns time, and nothing runs unless the driving loop runs it.

Pull, not push

The surface

use async_host::{ launch_future, sleep };
use ink::{ Logger };

async fn countdown(cx: RunContext, log: Logger, n: u32) -> nil {
    for (let i = n; i > 0; i -= 1) {
        log.info(f"{i}");
        await sleep(1000);             // the only suspension spelling
    }
}

pub fn main() -> nil {
    let log = Logger.new("countdown");
    launch_future(countdown(log, 3));  // the other consume: launch
}

3
2
1

The rules:

• The first parameter is the context. async fn f(cx: RunContext, ..) — the engine mints it at call sites and per drive, the way it mints self. It carries the frame edge: checkpoint() reads the resume state, cancelled() reads the task’s abort flag.
• Calling does not run. async fn f(..) -> T describes a value that widens to Future<T>; it runs when awaited or launched.
• One consume law. A future is consumed by await or by launch_future — exactly one. The launch returns its own receipt type, which is not a future and cannot be launched or awaited again.
• await targets engine-woven futures (async-fn results and sleep). Hand-written futures are launcher-drivable — the driving loop finds their Future::yield in the vtable — which is how the standard sleep itself is built over the open trait surface.

What the compiler emits

An async fn compiles to one hidden frame — an ordinary heap cell — with a woven Future::yield that the driving loop calls once per resumption:

frame:  [0]=state      the checkpoint enum's member — the pc
        [1]=cancelled  the task's abort flag
        [2]=awaiter    the frame awaiting THIS one
        [3]=pending    the future THIS one parks on
        [4..]=locals   every binding, mirrored into the frame

entry:      dispatch on state
per await:  probe the parked future's state
              done    -> resume with its value
              pending -> link awaiter/pending edges, park, return
resume arm: cancelled-probe -> drop path | restore locals -> continue

The state field is the program counter: resume dispatch is a jump table over the checkpoint enum. Because locals are mirrored into the frame cell, parking releases only staging registers and no liveness analysis decides which locals survive a suspension. The whole weave rides existing bytecode — no new opcodes, no new runtime machinery.

Cancellation is drop

handle.abort() flags the frame’s cancellation and re-enqueues it. The probe at its next checkpoint branches to the drop path: locals release in reverse binding order, on_drop callbacks fire by refcount, and any pending sleep dies with the frame. Cancellation never interrupts mid-expression — the checkpoint probe is the only place a cancellation becomes observable, so a cancelled function dies at a known-clean boundary. This is the same machinery that frees any heap object (see memory); coroutine frames get no special case.

The driving loop

The VM owns the queues; the embedder owns the loop:

#![allow(unused)]
fn main() {
vm.call::<_, ()>("main", ())?;              // script boots, launches futures
loop {
    vm.run_ready()?;                        // one drive per ready frame
    if let Some(d) = vm.next_deadline() {   // expire due timers into ready
        sleep_until(d);                     // the wall-clock stand-in
    }
    if vm.pending_tasks() == 0 { break; }   // idle
}
}

• sleep(ms) arms a deadline on the VM’s virtual clock (vm.now_ms() / vm.set_now()). A test host advances the clock by hand and gets fully deterministic schedules — a UI host just maps it to wall time.
• Each queue entry owns one reference; a completed drive re-enqueues the awaiting frame through a one-directional edge pair, so wake wiring never forms a cycle.
• Fuel accounting rides the ordinary per-op budget: a drive that runs out parks the frame at its checkpoint and resumes there later.

Host futures: pub host async fn

Native code joins the same model. A declaration file spells the row:

pub host async fn http_send(c: opaque, method: str, url: str,
                            headers: str, body: bytes) -> opaque;
pub host async fn http_stream_next(s: opaque) -> ?bytes;

and the embedder binds it with one closure that starts the work and returns the future’s state cell:

#![allow(unused)]
fn main() {
rut_vm::register_async!(hosts, "http_host::http_stream_next",
    (Opaque<HttpStream>,) -> Option<Vec<u8>>,
    move |s: Opaque<HttpStream>| -> Completer<Option<Vec<u8>>> {
        let c = Completer::new();
        let w = c.clone();
        std::thread::spawn(move || {
            w.complete(read_chunk(s));     // settle from any thread
        });
        c
    });
}

Completer<T> is a small shared cell: complete(v)/fail(msg) are callable from any thread (atomics plus a mutex — the VM stays single-threaded), fail’s message becomes the trap at the await, and an optional abort closure runs when the script cancels a pending future (late results are then simply discarded). The macro registers the whole row family the weave drives — start, probe, take, cancel — and the load-time check verifies the expansion against the declaration, so a decl and its bodies cannot drift apart. IO written with plain async/await Rust maps onto this naturally: the work leaves the VM, and completion is one enqueue back into the ready queue.

Structured concurrency, honestly

The language today keeps the vocabulary deliberately small: launch, abort, and await. Racing (await select { .. }) and joining a launched future (await handle) parse but are compile-gated — the diagnostics name them as future work, and structured scopes (a block that cancels its children on exit) are the same story. What exists now is already enough to structure real programs — the launch/abort receipt gives you explicit ownership of background work, and drop-based cancellation gives it a clean off switch — but nothing in the model silently cancels siblings on your behalf. See the reference on async and await, tasks, and the host futures bridge; the GitHub viewer CLI example shows a full program living inside this loop.

Memory: the Rc heap, weak refs, and cycles

rut’s memory management is reference counting with deterministic destructors and no collector. An object is destroyed the moment its last strong reference goes away — at a knowable statement, not “at some future GC”. The cost is honesty about cycles: a strong cycle never reaches zero, so it lives until the VM is torn down. rut makes that a stated rule and ships Weak<T> as the first-class answer, instead of hiding it behind a collector.

Everything is a cell

Every non-primitive value — strings, byte buffers, arrays, records, enums, trait objects, erasure boxes, nullable boxes, coroutine frames — is a heap cell. Each cell starts with a header: a refcount, a type id, and a few flags. The counts are plain integers: a VM runs on one thread with one heap, workers are separate VMs, and nothing is ever shared between them, so there are no atomics anywhere in the heap.

Because assignments and passes copy handles, not payloads, the refcount traffic is exactly the aliasing the program performs:

use ink::{ Logger };

struct Node { next: ?Node }

pub fn main() {
    let log = Logger.new("cells");
    let a: ?Node = Node { next: nil };
    let b = a;              // one retain
    log.info(f"a == b: {a == b}");   // one cell — it dies when the LAST of a, b goes away
}

a == b: true

The compiler knows every register’s static type, so it emits ref-aware moves only where references flow; scalar code pays nothing. Function boundaries do the paired inc/dec; a flat primitive buffer’s element traffic is plain slot moves.

Deterministic destruction

When a count reaches zero, destruction runs inline, in a fixed order:

1. on_drop cleanups are pinned. on_drop<T>(p: ?T, cleanup: fn(?T)) attaches a cleanup to a nullable binding — and a ?T binding is the cell reference, so this is “run this when the object dies”. One callback per binding; a second attach is a compile error; the pinned callbacks drain at the next call boundary.
2. Fields release in declaration order, recursively — a dying record’s strings, arrays, and boxes release their own references, so nothing is pinned until VM shutdown just because its owner died.
3. Host opaques run their Rust Drop at the same point. A host handle registered by the embedder releases its socket, texture, or thread when the last script reference disappears — never “someday at GC” (see the host boundary).

use ink::{ Logger };

class Connection {
    url: str;
    log: Logger;
}

impl Connection {
    fn open(url: str, log: Logger) -> Connection {
        return Connection { url: url, log: log };
    }
    fn close(self) { self.log.info(f"closed {self.url}"); }
}

pub fn main() {
    let log = Logger.new("rc");
    let conn: ?Connection = Connection.open("tcp://edge", log);
    on_drop(conn, fn(c: ?Connection) { c.close(); });
    log.info("main is done — the count hits zero at the boundary");
}

main is done — the count hits zero at the boundary
closed tcp://edge

Compare this with finalizer-based designs: there is no finalizer that “may run later or never”, no flush phase, and no resource whose release time you cannot point at in your own code.

Two edge rules worth knowing:

• Refcount overflow pins. If a counter would exceed its maximum, the object is deliberately immortalized (and logged) rather than wrapping — the same rule Swift uses.
• Weak boxes null first. When a cell with weak watchers dies, every Weak box to it is nulled before any user code runs — a cleanup that calls upgrade() sees nil, deterministically.

Weak references

Weak(v) mints a Weak<T> over v’s cell that never keeps anything alive; w.upgrade() answers ?T — the retained referent, or nil once it died. Construction is a call of the type name, admission is checked (reference types only — Weak<i32> diagnoses), and weak(nil) traps.

use ink::{ Logger };

class Model {
    name: str;
}

class View {
    model: ?Model;
    observer: ?Weak<Model>;      // a back-pointer that closes no cycle
}

pub fn main() {
    let log = Logger.new("rc");
    let mut m = Model { name: "doc" };
    let v = View { model: nil, observer: Weak(m) };   // observe without owning
    log.info(f"holding {m.name}; the view holds only a weak edge");
    m = Model { name: "next" };   // the old cell's last strong reference dies here
    log.info(f"upgrade() answers nil: {v.observer.upgrade() == nil}");
}

holding doc; the view holds only a weak edge
upgrade() answers nil: true

The two shapes that cause accidental cycles — back-pointers (child → parent) and caches (a table that should not extend lifetimes) — are exactly what Weak is for. A path through a Weak does not close a strong cycle.

The cycle policy

A strong cycle is a leak — deterministically. Its members live until the VM is dropped; no collector ever runs, no pass interrupts execution, and destructor ordering never surprises you. Guidance is lint-level, not runtime:

• resource-holding types (things with on_drop cleanups or host handles) must not participate in strong cycles;
• parent/child and observer shapes take Weak back-pointers;
• pure-data cycles are harmless — they cost only memory.

You are not left alone with the rule: debug builds assert refcount discipline (retain/release pairing, no underflow, no double free), and at teardown the VM emits a leak report — surviving objects grouped by type with allocation sites — which is the primary tool for hunting accidental cycles. Behavior is fully deterministic, so a leak reproduces exactly.

The self-managed heap

Host code may use std freely, but every byte backing a rut value is allocated through the VM’s own heap manager. The discipline is the point, not the allocator:

• Cells come from fixed-size arena chunks with freelists; a dead slot is reused by the next mint.
• Variable-size payloads (string octets, array element runs) live in size-classed blocks that never move; in-place geometric growth keeps append loops linear, and freelists recycle the common sizes.
• Immortal singletons — interned string literals, enum variants — live in a slab freed only at VM drop, carrying the “no refcount” sentinel.
• Nothing compacts. The heap never moves cells, which is precisely what lets the boundary hand Rust zero-copy views into buffers (see the host boundary).

Why self-manage instead of using the host’s allocator?

1. Budgets. An embedder can say “this script gets N bytes” and get a clean, resumable out-of-memory trap instead of an OS abort. vm.heap_usage() is exact because every allocation is accounted.
2. Teardown. Vm::drop frees the whole heap in slab units after the leak report; nothing per-object leaks past the VM — important for wasm pages and plugin hosts that spawn and kill scripts.
3. Leak reporting walks the VM’s own headers, which requires the VM’s own headers everywhere.

The budget check runs before any write — a failed allocation leaves the heap byte-identical — and traps resumably: raise the limit and continue, or drop references and retry. See the reference on resource limits for the full knob set, and the bytecode VM for how budgets interleave with execution.

What this buys you

• Deterministic resource release — the property the whole design is organized around. If your script opened something, the closing statement is knowable.
• No pauses. There is no collection pass; destruction happens inline at release-to-zero, so nothing ever interrupts a frame.
• A small, honest mental model. Sharing is by reference, copies are built explicitly (see everything is a value), lifetimes are refcounts, and the one thing refcounts cannot do — cycles — is a documented rule with a first-class tool.

The host boundary

rut exists to be embedded. The host — a Rust program — owns a VM, declares its API once in rut source, binds the implementations with typed Rust closures, and drives everything. The design rule for the whole boundary: the type system does the checking, not your bridge code. There is no argument re-parsing, no as number, no “trust-me” coercion — a value crossing either direction is checked against a reified runtime type, and a mismatch is a loud error naming both sides.

The embedding model

#![allow(unused)]
fn main() {
let mut session = Session::new();
mount_std_core(&mut session);
session.register_module("app:gfx", lower_decl_module(GFX_DECL, "gfx.d.rut")?);

let mut hosts = HostRegistry::new();
hosts.register::<_, (i32, i32), Opaque<Canvas>, _>(
    "app:gfx::newCanvas",
    |_vm, w: i32, h: i32| Ok(Canvas::new(w, h)),
);

// the join: every declared row must have a binding, and vice versa —
// verified BEFORE any script runs
hosts.verify_against(&session.expected_host_fns())?;

let mut vm = Vm::new(program, &limits, hooks, hosts)?;
vm.call::<_, ()>("main", ())?;      // an entry point
vm.run_ready()?;                    // drive async work to idle
}

The declaration file (a host package) spells the surface in rut:

pub host fn newCanvas(w: i32, h: i32) -> opaque;
pub host fn circle(h: opaque, x: f32, y: f32, r: f32) -> nil;

and the load-time join rejects three wiring bugs as panics — an embedder mistake, never a script diagnostic: a declared row with no binding, a binding with no declaration, and signature drift. “Mount what you bind”: an embedder that mounts a package declares its rows and must bind them.

The crossing set

What may cross is a compile-time property of the surface, not a runtime negotiation:

• Parameters: the primitives, str, bytes, and opaque.
• Returns: the same set plus the answer optionals ?str, ?bytes, ?opaque — Option<String>, Option<Vec<u8>>, and the opaque handles mint the nullable box, with None as the flat nil.
• Tuples cross field by field, which makes the error convention — (value, err) — a first-class entry answer. The two channels stay distinct by law: a returned err is data the host reads and acts on; a panic is drift and arrives on the trap channel, never filling an err field.

Everything else — user structs and classes, Vecs, trait-typed values, closures — stays inside the VM. A declaration that violates the set is a compile error at the declaration, not a failed call at 2 a.m. There is no any: a polymorphic crossing seals its value in an erasure box (opaque(v) at the call, opaque.downcast<T> after), checked, never silent — see reified types.

The currency is typed Rust

On the Rust side the boundary speaks ordinary Rust types. Each type declares the rut type it binds against and converts checked:

• Borrow, don’t copy. &str and &[u8] parameters read the VM’s buffers zero-copy. The borrow is call-scoped — the type system makes smuggling it past the return a compile error.
• Copy on purpose. Owned String/Vec<u8> parameters are the explicit “I keep this data” choice.
• Opaque<T> is the typed view of a host handle: an 8-byte store handle the host holds and passes back; the payload stays host-owned (Box<dyn Any> plus an optional finalize hook).

Borrow guards make the zero-copy views safe while script runs: a borrowed object is flagged, and script-side mutation through a re-entrant call traps with borrowed by host instead of racing. Guards clear on return. This is sound forever because the heap never moves objects (see memory).

Wrapping host state: the class-in-rut pattern

There is no “host class”. Native state crosses as an opaque handle and a rut class wraps it — ordinary source the compiler can see and optimize around:

class Canvas {
    h: opaque;
    fn circle(mut self, x: f32, y: f32, r: f32) -> nil {
        canvas_circle(self.h, x, y, r);
    }
    fn hits(self) -> i32 { return canvas_hits(self.h); }
}

Every method is exactly one host call — the same crossing a magic host class would have paid — but the wrapper can also carry impl blocks, validation, and convenience the native side never needed to know about. The payoff for keeping the boundary this small: host resources die deterministically. When the wrapper’s last reference goes, the handle’s refcount hits zero and the payload’s Rust Drop runs at that point — sockets and textures close on script schedule, not at some future collection.

Host functions are rows, dispatched by slot

Each declared row gets a stable slot id at compile time; calls compile to slot dispatch, so names are binding-time labels only — renaming a Rust-side binding target fails the join instead of silently rebinding. The surface grammar is small:

host fn name(params) -> T;        // concrete signature; no generics —
                                  // a generic has no shape to check
host struct Name { fields };      // flat record of crossing fields

builtin declarations (the engine’s own fns, classes, and traits — str methods, Weak, Future) are engine surface: the embedder cannot spell them, and users implement their traits with ordinary impl blocks. Async rows (pub host async fn) are declared like any row and expand into a small row family the driving loop uses — the embedder binds them with one closure per future; see the async model.

Re-entrancy, traps, budgets

• A native fn receives a context that may call back into rut (vm.call) — nested calls run under the same budget on a fresh frame stack.
• Native code runs outside the op budget: the host is trusted to be fast, or to hand back a future instead of blocking. A trap raised inside a native fn propagates to the host as an Err(Trap) with the native frame visible in the backtrace.
• Traps are catchable only at the boundary — script never catches one. That is what keeps panics loud and state uncorrupted.

What was deliberately left out

No C ABI. There is no register_struct, no size_of, no pointer mirroring of record layouts: records are slot arrays internal to the VM, and a host sees them only through the checked crossing. The few bytes you give up to the checked boundary buy the property that makes embedding pleasant — every mismatch is a named, typed, load-time diagnostic instead of a runtime mystery.

The full details live in the reference: embedding and native modules, the value boundary and borrows, host fns and declaration files, and the withdrawn C-struct experiment recorded at repr(C) interop.

The bytecode VM

Everything a rut program becomes is a typed bytecode executed by a register VM. There is no JIT, no interpreter tiering, no runtime speculation: the compiler does all optimization ahead of time, and what runs is exactly what was compiled. This chapter is the tour of that artifact — the instruction set, the module binary, the load-time verification, and the interpreter’s execution and budgeting model.

One struct, one thread, one heap

#![allow(unused)]
fn main() {
pub struct Vm {
    types:  TypeTable,     // runtime type descriptors + vtables
    heap:   Heap,          // the refcounted, self-managed heap
    mods:   Vec<Module>,   // linked binaries
    frames: Vec<Frame>,    // the call stack
    ready:  Deque<Slot>,   // woken async frames
    timers: BTreeMap<u64, Vec<Slot>>,  // the virtual clock's wheel
    lim:    Limits,        // fuel, heap budget, interrupt interval
    host:   HostHooks,     // registered native bodies, clock, loader
}
}

A VM is single-threaded by construction (!Send); workers are separate VM instances communicating by messages. The host holds one and drives it with methods: call an entry point, run_ready to drain woken frames, next_deadline for the timer wheel, drive for a single resumption. See the host boundary for the embed loop and the async model for the queues’ role in scheduling.

Typed bytecode

The instruction set is register-based: operands are u16 indices into a per-frame slot file, and every register has a static type recorded in the function’s signature. That single decision is what lets the hot path stay tag-free (see reified types) and what makes refcounting precise: the compiler emits plain moves for scalars and retain/release moves for references, with no runtime tag checks.

Ops are small and fixed-size, with variadic operand lists (call arguments, branch tables) living in per-function pools. A representative sample:

mov / movref   rD, rS        ; move; the ref form retains new, releases old
i32add, f64mul, ...          ; typed arithmetic — the opcode selects the
                             ; kind, the width rides the op
icmp, fcmp     rD, a, b      ; compares -> bool
call / callm   f, args       ; direct call / direct method call
calli          slot, recv    ; trait vtable call (dynamic dispatch)
callnat        nat, args     ; internal natives (string concat, ...)
newcell / getf / setf        ; mint a record, read/write a field
arrget / arrset              ; indexing — bounds checked, trap on miss
tidof          rD, rO        ; read a value's runtime type id
brtable        rIdx, arms    ; enum matching, resume dispatch

The type system also decides what is not an op:

• Nothing static. What the type table can answer at compile time becomes a constant — no “get type id” instruction, no length load for a fixed-size array.
• Nothing polymorphic and nothing named. A trait-typed receiver has exactly one op (the vtable call); string concatenation is a native call, not an opcode.
• Concrete memory, control flow, and two readbacks. Ops touch memory only through compile-time-known layouts, plus the two reads reification needs: “what is it” (tidof) and the guarded payload extract behind a downcast.

The module binary

Compilation produces a versioned, self-contained binary per module: types, constants, functions (with their typed register signatures), imports, and a symbol table for backtraces. Its properties matter more than its layout:

• Deterministic. The same sources plus the same dependency versions produce byte-identical binaries, so artifacts are cacheable by content hash and shippable instead of sources.
• Self-describing but strippable. Names and source spans are retained for traces by default; a release build can strip them, and a sidecar map file (keyed by content hash) can restore symbolication later. See the reference on diagnostics.
• Link-time identity. Type ids are module-local at rest and rebased into the VM’s global table at link, where impl registries merge and duplicates are rejected. Cross-module trait calls specialize per concrete argument here too — the static-dispatch rule of traits and dispatch holds across module boundaries.
• Little-endian everywhere, by law — every serialized word, so artifacts are platform-independent by construction rather than by luck.

Verification at load

Loading re-checks each function before anything executes: register operands against the signature, operand pools and jump targets in range, type operands present in the type table, native slots declared, and async state tables closed. A failed verification is a load error naming the module and function — corrupted binaries never execute. This is also where crossing rules are enforced for host-facing signatures, so a non-crossing shape is rejected before any script runs.

Module-level initialization is folded at compile time: literals, enum members, constant expressions, and interned string literals become constants in the binary. A user function call in a module initializer is a compile error — there is no load-time execution at all. Loading a module runs nothing.

The interpreter loop and traps

Execution is a decode-dispatch loop over frames. A frame is the function’s code, a program counter, its typed register file, and (for async frames) the resume state. Calls push frames; returns pop them; direct calls are an index plus jump, and trait calls are two loads plus an indirect jump through the vtable.

Failure is a trap, not an exception and not a Rust panic: integer overflow on the plain operators, a nil deref, an out-of-bounds index, a failed assert or panic(..), or an exhausted budget. A trap captures the raw frame chain (rendered lazily — symbolication happens only if someone prints it), runs destructors on the way out, and unwinds as an Err(Trap) to the host call. Rut code cannot catch one; the boundary is the catch point (see the host boundary).

Budgets and interrupts

Two knobs make it safe to run third-party code, both set at construction and mutable while running:

#![allow(unused)]
fn main() {
Limits { fuel: Option<u64>,            // one unit per op, counts down
         heap_limit_bytes: Option<u64>,// checked at every allocation
         interrupt_every: u32 }        // default: check every 1024 ops
}

• Exhaustion is resumable: the trap parks the frame exactly where it was — the frame is the loop state — so the host can add fuel, raise the heap limit, or flip the interrupt flag and resume. A UI host yields mid-frame; a wasm page grants finite fuel; a test sets finite fuel plus a virtual clock and gets a deterministic hang proof.
• The heap check runs before any write, so an out-of-memory failure leaves the heap byte-identical (see memory).
• Native functions run outside the fuel budget — a hanging native is a host bug by contract — and the interrupt hook is the host’s lever at native return points.

Why no JIT is viable

A JS engine’s speed is its JIT, and the JIT exists to speculate about polymorphic property loads. rut has no polymorphic loads: field access is by known index, calls bind statically whenever the site names one concrete type, generics are monomorphized, and the remaining dynamic dispatch is an honest checked vtable hop. The optimizer’s currency is type stability — what the checker proves is everything the optimizer gets — and its passes (constant folding, inlining, monomorphization, register-level cleanup) all run ahead of time. The result is a runtime with no warmup curve, no deoptimization asymmetries, and per-op costs you can reason about from the bytecode alone.

The full tables and laws live in the reference: typed bytecode, the module binary and verification, VM core, and resource limits and fuel.

Examples index

The repo ships two kinds of example material. The examples/ directory holds six runnable Cargo projects (five console programs and one browser page) plus one parse-only corpus example. Alongside them, demo/src/examples/ holds the playground classics — short, self-contained programs the web playground runs in the browser, the same programs the repo’s gates compile and run in CI. Each project has its own page in this chapter; the classics share The playground corpus.

All Cargo commands run from the repository root. The runnable crates share one session pattern — compile the module, verify the binary, bind host fns, then drive it through typed vm.call sites — so the pages cross-link often: 00 — Todolist establishes the pattern and 06 — GitHub viewer CLI stretches it the farthest.

The three dependency kinds

Every package carries a rut.toml manifest (see Project structure and rut.toml), and a manifest relates a package to other packages through three tables, all visible in the examples:

• [deps] — ordinary dependencies, transitively mounted. The common case: 03-plugin’s plugin/rut.toml declares server = { path = "../server" }, and 05 — Todolist web’s biz package declares ui (which itself pulls the collection packages).
• [peer-deps] — required by default: the consumer supplies the peer and the peer is never pulled transitively. Marking a peer optional = true flips it to a presence relation: its integration file (impl-only code the peer makes compilable) mounts only when the peer is anywhere in the program’s closure. The in-tree example is the std json package’s serde-model impls — impl JsonSerialize for Vec<T> is written in json but must not force every json consumer to mount the collection packages, so those live as optional peers and as [dev-deps] for json’s own tests. 02 — Digest consumes json light; 06 — GitHub viewer CLI calls assemble_peers and mounts the impl groups for real because the collections are in its closure.
• [dev-deps] — mounted only while building the package itself, never in a consumer’s world. json develops against the real collection packages through the both-kinds pairing while its consumers mount it without them.

The full rules — the loud missing-required-peer error, the silence of absent optional peers, dedup-by-origin at the splice, and what bundle format the packer emits — are on Dependency kinds.

Reading order

New to the language: read 00 — Todolist and 01 — Sort for the embedding shape, then The playground corpus for the language surface in small doses. For the web story, 05 — Todolist web is the centerpiece and 06 — GitHub viewer CLI is the networking counterpart. 03 — Plugin is the one to study for packaging and module loading, and 04 — Custom async for what the future trait looks like from user code.

00 — Todolist

The first runnable host example, and the template for the rest of the chapter: a Rust program embeds rut, compiles a rut library (there is no main in it), and drives the library through its entry fn surface. The split is two files — todolist.rut owns the data and the logic as a TodoList class with full CRUD; src/main.rs owns the session: compile, verify, then a scripted conversation of vm.calls. The one-sentence design rule: the host owns the session, rut owns the data.

Run it

cargo run -p todolist        # from the repo root
cargo test -p todolist       # the same session asserted as a test

The run prints an abridged transcript like this:

added: #1, #2, #3
set_done(#2, true)
title_of(#2) = Opt(Some(Str("implement the VM")))
title_of(42) = Opt(None)
remove(#1) = Res(Ok(Bool(true)))
remove(#1) again = Res(Err(Str("no todo #1")))
TodoList[2]
  #2 [x] implement the VM
  #3 [ ] ship the demo
second list #1: 0 todos
fuel used: 680 of Some(1000000)

Code tour

The data: a class with a fields-only body

examples/00-todolist/todolist.rut — the type body is fields only; methods live in an inherent impl block (Structs, Classes and constructors). Unannotated members are module-private. The block below is the class verbatim — new, add, and remove — closed with a main so it runs on its own; the example file itself has no main — it is a library the host drives through its entry fn surface:

use ink::{ Logger };
use pouch::{ Vec };

struct Todo {
    id: i32;
    title: str;
    done: bool = false;      // field initializer — `done` may be omitted
}

pub class TodoList {
    items: Vec<Todo>;         // unannotated members = module-private
    next_id: i32;
}

impl TodoList {
    pub fn new() -> Self {
        return Self { items: Vec.new(), next_id: 1 };
    }

    // ---- CREATE ----

    pub fn add(mut self, title: str) -> i32 {
        let id = self.next_id;
        self.items.push(Todo { id: id, title: title });
        self.next_id += 1;
        return id;
    }

    // ---- DELETE ----

    pub fn remove(mut self, id: i32) -> bool {
        let kept: Vec<Todo> = Vec.new();
        let mut removed = false;
        for (let t of self.items) {
            when (t.id == id) {
                true -> { removed = true; },   // drop the row
                else -> { kept.push(t); },     // keep everything else
            }
        }
        if (removed) {
            self.items = kept;
        }
        return removed;
    }
}

pub fn main() {
    let log = Logger.new("todos");
    let mut list = TodoList.new();
    list.add("implement the VM");
    list.add("ship the demo");
    let first = list.remove(1);
    let second = list.remove(1);
    log.info(f"remove(#1) = {first}, again = {second}, left: {list.items.len()}");
}

remove(#1) = true, again = false, left: 1

Note mut self: writing through a class handle requires a mut binding head, the same law 01 — Sort exercises on plain vecs — add and remove both declare it. remove filters through a when: the matching row is dropped, everything else is kept, and the list is rewritten only if something was actually removed. The read side (not shown) is ordinary code — len, title_of (which returns "" for a miss; the example pairs it with has_title because there is no ?. sugar), and a render built from f-strings.

The handle: one opaque box around the world

Instances of TodoList can never cross into Rust — the crossing set admits primitives, str, bytes, and opaque only, and entry fn signatures are checked against that rule at compile time (see the host boundary). So the library boxes its whole container once and the host holds the handle:

struct Lists {
    lists: Vec<TodoList>;    // handle = index; handles stay stable while held
}

fn at(c: opaque, h: u32) -> TodoList {
    let lists = opaque.downcast<?Lists>(c);
    return lists.lists[h as i32];
}

entry fn createContainer() -> opaque {
    let ls: ?Lists = Lists { lists: Vec.new() };
    return opaque(ls);
}

entry fn create(c: opaque) -> u32 {
    let k = opaque.downcast<?Lists>(c);
    k.lists.push(TodoList.new());
    return (k.lists.len() - 1) as u32;
}

Two things to take away. First, entry fn marks the host-callable surface — distinct from pub, which is use-visibility for other rut modules and carries no crossing limits (Modules and visibility). Second, erasure is the opaque(v) type-call and recovery is opaque.downcast<T>(o) -> ?T — a wrong box answers nil, never a trap (opaque — erasure and downcast). The internal helper at is an ordinary fn and may speak in full types.

The embedder: typed calls, budgets, and honest errors

examples/00-todolist/src/main.rs mounts core and the pouch package (for Vec), compiles in one call, verifies the binary, and then talks to the module through typed closures:

#![allow(unused)]
fn main() {
let c: rut_vm::OpaqueRef = vm.call("createContainer", ()).unwrap();
let list: u32 = vm.call("create", (c.clone(),)).unwrap();

let mut add = |title: &str| -> i32 {
    vm.call::<_, i32>("add", (c.clone(), list, title)).unwrap()
};
let vmf = add("implement the VM");
let demo = add("ship the demo");
}

The session runs under explicit budgets — fuel and a heap limit — so a runaway module fails loudly instead of hanging the host (Resource limits and fuel):

#![allow(unused)]
fn main() {
let limits = rut_vm::interp::Limits {
    fuel: Some(1_000_000),
    heap_limit_bytes: Some(4 * 1024 * 1024),
    interrupt_every: 1024,
};
}

And the transcript’s remove(#1) again = Res(Err(...)) line is the VM’s typed view of a bool answer — the second remove returns false, and the debug print shows the value shape the crossing produces (Value boundary and borrows).

Takeaways

• entry fn is the host-callable surface; its signatures are checked against the crossing rule at compile time, so a bad plan is a diagnostic, never a call-time surprise.
• State lives rut-side in one opaque container the host holds and re-passes; plain values cross, instances never do.
• Erasure is opaque(v); recovery is opaque.downcast<T> -> ?T.
• Budgets (fuel + heap) are the embedder’s call, and every embedder mistake comes back as a named trap.
• The same file works as a library: entries are compilation roots, so a module with no main still emits every entry.

Next: 01 — Sort scales the pattern to five algorithms and shows what recursion costs in fuel. The crossing rules behind this page are in the host boundary.

01 — Sort

The second runnable host example, in the shape of 00 — Todolist: five sorting algorithms in rut — insertion, bubble, and selection (loop-shaped), plus quicksort and merge sort (recursion, in-place vs. out-of-place) — driven from Rust through one entry fn dispatcher. Where 00 is about the boundary, this one is about the language: recursion, when on strings, the mut-binding law, wrapping arithmetic, and visible fuel budgets.

Run it

cargo run -p sort          # from the repo root
cargo test -p sort         # every algorithm, edge cases, cross-agreement

The run sorts a hand-picked input, then fills the bank with a deterministic pseudo-random vector and runs the full sweep, printing fuel per algorithm:

pushed: [5, 2, 9, 2]
after insertion: [2, 2, 5, 9]
fill(16, seed=42), each algorithm:
  insertion true  fuel   2335  [208, 320, 353, ..., 854, 893]
  bubble    true  fuel   3895  [208, 320, 353, ..., 854, 893]
  selection true  fuel   3353  [208, 320, 353, ..., 854, 893]
  quick     true  fuel   2241  [208, 320, 353, ..., 854, 893]
  merge     true  fuel   4358  [208, 320, 353, ..., 854, 893]
sort(bogus) = Res(Err(Str("unknown algorithm: bogus")))
fuel used: 21142 of Some(5000000)

The fuel column is the demo’s quiet joke: quick < insertion < selection < bubble, exactly as the textbooks promise — and the VM counts it for you.

Code tour

One opaque bank; the data never leaves rut

Vec<i32> cannot cross the host boundary, so create() boxes a Bank in an opaque and the host holds the handle — the 00 — Todolist pattern again. Results come back three ways, all crossing-shaped. serialize below is verbatim, plus a main that boxes a small bank the way create() does, so the block runs on its own:

use ink::{ Logger };
use pouch::{ Vec };

struct Bank {
    data: ?Vec<i32>;
}

entry fn serialize(c: opaque) -> str {
    let b = opaque.downcast<?Bank>(c);
    let xs = b.data;
    let mut out = "[";
    for (let i = 0; i < xs.len(); i += 1) {
        if (i > 0) {
            out = f"{out}, ";
        }
        out = f"{out}{xs[i]}";
    }
    return f"{out}]";
}

pub fn main() {
    let log = Logger.new("sort");
    let bank: ?Bank = Bank { data: Vec<i32>.from([5, 2, 9, 2]) };
    let c = opaque(bank);
    log.info(f"serialized: {serialize(c)}");
}

serialized: [5, 2, 9, 2]

serialize is the workhorse: a whole result crosses as one JSON array string, so the host asserts an entire sort in one compare. get(c, i) / has(c, i) read element-by-element, and is_sorted(c) returns the verdict.

The dispatcher: when on strings, errors as values

Every algorithm sits behind a single string-keyed entry. Unknown names are an ordinary value, not a trap — the empty string means success:

entry fn sort(c: opaque, algo: str) -> str {
    let b = opaque.downcast<?Bank>(c);
    let mut unknown = false;
    when (algo) {
        "insertion" -> { insertion_sort(b.data); },
        "bubble"    -> { bubble_sort(b.data); },
        "selection" -> { selection_sort(b.data); },
        "quick"     -> { quicksort(b.data, 0, b.data.len() - 1); },
        "merge"     -> { merge_sort(b.data); },
        else        -> { unknown = true; },
    }
    if (unknown) {
        return f"unknown algorithm: {algo}";
    }
    return "";
}

when with string-literal arms is the general dispatch idiom — see Control flow and when.

Deterministic input in one call

fill replaces the bank with n pseudo-random values from a linear-congruential generator, so sizing a benchmark input is one host round-trip, not one per element. The u32 math must wrap, and rut makes that explicit — plain * traps on overflow. The entry is verbatim (the Bank inlined so the block compiles alone), with a main that fills and prints what one call produces:

use ink::{ Logger };
use pouch::{ Vec };

struct Bank { data: ?Vec<i32>; }   // inlined from above — the block runs alone

entry fn fill(c: opaque, n: u32, seed: u32) {
    let mut b = opaque.downcast<?Bank>(c);
    let fresh: Vec<i32> = Vec.new();
    let mut x = seed | 1;         // the LCG needs an odd state
    for (let i = 0; i < n as i32; i += 1) {
        x = (x.wrapping_mul(1664525)).wrapping_add(1013904223);
        fresh.push((x % 1000) as i32);
    }
    b.data = fresh;
}

pub fn main() {
    let log = Logger.new("sort");
    let bank: ?Bank = Bank { data: nil };
    let c = opaque(bank);
    fill(c, 8, 42);
    let b = opaque.downcast<?Bank>(c);
    let xs = b.data;
    let mut out = "";
    for (let x of xs) {
        out = f"{out} {x}";
    }
    log.info(f"fill(8, seed=42):{out}");
}

fill(8, seed=42): 798 893 208 375 746 353 452 555

The wrapping family (wrapping_mul, wrapping_add, wrapping_shl) is the honest spelling of two’s-complement arithmetic — the playground corpus has a whole checked-arith case on the contrast.

Recursion under fuel

Quicksort partitions in place; merge sort builds out-of-place halves and merges back through the shared handle. Both are plain recursive fns — the call-frame stack is the VM’s, counted by the same fuel budget (the bytecode VM):

fn quicksort(mut xs: ?Vec<i32>, lo: i32, hi: i32) {
    if (lo >= hi) {
        return;
    }
    let p = partition(xs, lo, hi);
    quicksort(xs, lo, p - 1);
    quicksort(xs, p + 1, hi);
}

Note the mut xs parameter heads: vecs are handles, so an in-place swap inside a call is shared with the bank — but writing through the handle requires the mut binding head, while mere reads (and push) do not. That asymmetry is the mut-binding law, and every algorithm in this file declares it (Modules and visibility).

The embedder’s sweep

src/main.rs drives the sweep and prints the fuel deltas, which is how the table above gets its numbers:

#![allow(unused)]
fn main() {
println!("fill(16, seed=42), each algorithm:");
for algo in ["insertion", "bubble", "selection", "quick", "merge"] {
    vm.call::<_, ()>("fill", (c.clone(), 16u32, 42u32)).unwrap();
    let before = vm.fuel_used;
    vm.call::<_, String>("sort", (c.clone(), algo)).unwrap();
    let sorted: bool = vm.call("is_sorted", (c.clone(),)).unwrap();
    println!("  {algo:<9} {sorted}  fuel {:>6}  {}", vm.fuel_used - before, ser(&mut vm));
}
}

Takeaways

• Same host pattern as 00 — Todolist, one entry richer: a single string-keyed dispatcher keeps the entry fn surface small.
• Vec<T> never crosses; a serialized JSON array makes a whole result one host-side compare.
• Errors are values: an unknown algorithm comes back as a string, not a trap.
• mut on a binding is a capability law, not a suggestion — and the wrapping arithmetic family is explicit about overflow.
• Fuel budgets make algorithmic differences visible from the host, for free.

Deep-dives: the bytecode VM explains what a unit of fuel counts; 02 — Digest takes the same session shape to the byte level.

02 — Digest

The byte-level example, in the shape of 00 — Todolist and 01 — Sort — with a twist: this time the embedder is also the oracle. digest.rut is a byte-level library written in pure rut:

• encodings — hex (encode/decode, case-insensitive) and base64 (standard + URL-safe alphabets, padding, invalid-input rejection)
• crypto digests — MD5, SHA-1, SHA-256, SHA-512 behind one when-on-string dispatcher
• hashmap hash keys — CRC-32, FNV-1a 32/64, djb2, sdbm
• JSON — decode to an opaque tree, encode back, round-trip, with numbers stored as verbatim lexemes so round-trips are exact

Nothing in the rut file trusts itself: the Rust host cross-checks every algorithm against independent crates (the RustCrypto hash family, base64, crc32fast, serde_json) on canonical test vectors and on deterministic pseudo-random inputs at every padding-edge length, plus a 64 KiB stress blob. digest.rut knows nothing about the crates; only the host compares.

Run it

cargo run -p digests       # from the repo root
cargo test -p digests      # the oracle, asserted

The run prints one verified row per check — abridged:

hex([114, 117, 116, 33]) = 72757421
b64([102, 111, 111, 98, 97, 114], url=false) = Zm9vYmFy  OK
digests, rut vs crates:
  md5     empty         fuel    8419  d41d8cd98f00b204e9800998ecf8427e  OK
  sha256  "abc"         fuel   18866  ba7816bf...f20015ad  OK
  md5     1 KiB lcg(42) fuel  113117  d6c1961991b0106647e36ca4ba12d345  OK
sample_doc -> {"name":"rut","version":0.2,"tags":["tiny","fast","verified"],...}
serde_json parses it: OK
hash keys over that JSON text:
  crc32   eccc5960  OK
  fnv1a64 8ba697141da02e83  OK
hex_dec("zz")   = "hex: invalid character at index 0"
json_dec("{,}") = "json: expected a key string at index 1"
digest("md4")   = "unknown algorithm: md4"
every row agrees: OK
fuel used: 1014105 of Some(50000000)

Code tour

The integer surface is enough for real algorithms

digest.rut runs on hex literals, u32/u64, the wrapping family, and signedness-correct shifts. CRC-32 is the compact showcase — table-free, bitwise, and exactly the textbook loop. The entry is pure rut — no host, no manifest — so it runs on its own, here checked against the algorithm’s canonical test value:

use ink::{ Logger };

entry fn crc32(data: bytes) -> u32 {
    let mut crc: u32 = 0xFFFFFFFFu32;
    for (let b of data) {
        crc = crc ^ b as u32;
        for (let k = 0; k < 8; k += 1) {
            if ((crc & 1) == 1) {
                crc = (crc >> 1) ^ 0xEDB88320u32;
            } else {
                crc = crc >> 1;
            }
        }
    }
    return crc ^ 0xFFFFFFFFu32;
}

pub fn main() {
    let log = Logger.new("crc");
    let vector = "123456789".encode();   // the canonical CRC-32 test vector
    log.info(f"crc32(vector) = {crc32(vector)} — check value 0xCBF43926: {crc32(vector) == 0xCBF43926u32}");
}

crc32(vector) = 3421780262 — check value 0xCBF43926: true

SHA-512 is the demanding one: its 64-bit rotations need >> to be a logical shift on u64 and wrapping_shl to truncate to the operand width. The FNV/djb2/sdbm trio, by contrast, deliberately never shifts a 64-bit word — wrapping_mul, wrapping_add, and ^ carry them, showing how far the primitive surface alone goes.

bytes crosses directly; opaque appears exactly once

Byte payloads need no wrapper — bytes is in the crossing set, so entry fn hex_enc(data: bytes) -> str takes a host byte slice head-on (primitive types). The one erasure in the file is the recursive JSON tree: rut has no recursive dataclass, so the tree is a tagged union by hand with children boxed in opaque to break the recursion (opaque — erasure and downcast):

enum JTag { Null, False, True, Num, Str, Arr, Obj }

struct Json {
    tag:  JTag;
    num: str;          // verbatim lexeme — exact round-trips, no
    str: str;          // float formatting anywhere in this file
    arr:  Vec<opaque>;
    keys: Vec<str>;
    vals: Vec<opaque>;
}

Storing numbers as their verbatim lexemes is what makes round-trips exact: -3e2 decodes and re-encodes as -3e2, with no float formatting anywhere in the file.

The encode half rides the std json package

The encode side is not private code: it is an impl of the std json package’s serialization trait, driving the package’s writer. This is the orphan rule’s type-local case — json owns the trait, this file owns Json, so the pair is legal exactly here (Traits and dispatch):

impl JsonSerialize for Json {
    fn encode(self, mut w: JsonWriter) -> ?EncodeJsonError {
        when (self.tag) {
            JTag.Null -> { w.write_raw("null"); },
            JTag.False -> { w.write_raw("false"); },
            JTag.True -> { w.write_raw("true"); },
            JTag.Num -> { w.write_raw(self.num); },
            JTag.Str -> { w.write_str(self.str); },
            JTag.Arr -> {
                w.begin_array();
                for (let i = 0; i < self.arr.len(); i += 1) {
                    let ae: Json = opaque.downcast<Json>(self.arr[i]);
                    let e = ae.encode(w);
                    if (e != nil) { return e; }
                }
                w.end_array();
            },
            JTag.Obj -> {
                w.begin_object();
                for (let i = 0; i < self.keys.len(); i += 1) {
                    w.key(self.keys[i]);
                    let ve: Json = opaque.downcast<Json>(self.vals[i]);
                    let e = ve.encode(w);
                    if (e != nil) { return e; }
                }
                w.end_object();
            },
        }
        return nil;
    }
}

The entry surface then hands the tree to encodeJson and flattens the (str, err) pair it answers. The decode half stays a private cursor parser (strings iterate as codepoints, so the source is split once into single-char strings and walked by index) — and every decode error is an honest string value, never a trap:

hex_dec("zz")   = "hex: invalid character at index 0"
b64_dec("!*")   = "base64: invalid character `!`"
json_dec("{,}") = "json: expected a key string at index 1"

The host oracle, in miniature

The host keeps three-line reference implementations for the hash keys with no canonical crate, and crates for everything else — then compares:

#![allow(unused)]
fn main() {
// the hash-key trio with no canonical crate: three-line references
fn fnv1a32(b: &[u8]) -> u32 {
    let mut h = 0x811c9dc5u32;
    for &x in b {
        h ^= x as u32;
        h = h.wrapping_mul(16777619);
    }
    h
}
}

The same session runs under 50 M fuel for the demos and raises to 500 M for the 64 KiB stress blob — budgets are the host’s call, per call.

Takeaways

• The integer surface (hex literals, u32/u64, wrapping ops, logical shifts) is enough for MD5-through-SHA-512 — verified, not asserted, against independent Rust.
• bytes crosses the boundary directly; opaque is for the one place recursion needs breaking.
• The std json package is usable from day one: implement its serialize trait for your own type and its writer does the byte work (core and the swappable packages).
• Errors are values, and the host-as-oracle pattern is the strongest test shape in this chapter.

The oracle pattern returns in 06 — GitHub viewer CLI, where the fixture is a recorded HTTP lane instead of hash crates.

03 — Plugin

A Rust chat-room server with a rut moderator plugin — the first example built on two things at once: re-entrant vm.call (the host calls rut, and a host fn called by rut calls back into rut while the first call is still parked) and both opaque directions (rut hands the host a handle to its own state; the host hands rut a handle to the server’s event bus). It is also the packaging example: the plugin loads from a module directory and from a .rutbundle packed from that directory at runtime — the two forms of one contract (Module bundles).

Run it

cargo run -p plugin         # from the repo root
cargo test -p plugin        # transcript asserted + bundle round-trip gates

The demo drives one scripted session twice — once against the directory, once against the packed bundle — and prints both transcripts plus the round-trip proof. Abridged:

== transcript (module directory) ==
[system] *** ada joined (1 online)
[broadcast] <ada> hello world
...
[system] shutdown: 0 online, 3 msgs, 1 mutes
-- 3 messages moderated --

== packed form (examples/03-plugin/plugin -> NNNN bytes, written to /tmp/...) ==
transcript identical to the directory form: true

The test suite asserts the transcript exactly, proves every line crossed the nested render (emits == renders), and gates the bundle form: round-trip equality, byte-determinism, and refusal on an unknown format version or CRC corruption.

Code tour

The layering: callbacks at the edges, classes in the middle

Four layers, and neither business layer ever touches the crossing protocol:

RUST biz (main / tests)      ->  typed Plugin methods, no vm.call
RUST adapter (src/lib.rs)    ->  the ONLY vm.call sites
RUT adapter (plugin/plugin.rut) ->  the ONLY entry fns; one-line forwards
RUT biz (Moderator)          ->  pure logic + emit, no entry fn

The moderator rules themselves are plain rut — flood control (three consecutive messages from one sender mutes them), muted users rejected on rejoin, a !stats command, tick heartbeats:

pub fn on_msg(mut self, user: str, text: str) {
    if (self.is_muted(user)) {
        self.say("muted", user);
    } else if (text == "!stats") {
        self.say("direct", f"{user}: {self.stats()}");
    } else {
        if (user == self.last_sender) {
            self.streak += 1;
        } else {
            self.last_sender = user;
            self.streak = 1;
        }
        if (self.streak == 3) {
            self.muted.push(user);
            self.mutes += 1;
            self.say("system", f"{user} muted for flooding");
        } else {
            self.msgs += 1;
            self.say("broadcast", f"<{user}> {text}");
        }
    }
}

Every bus write funnels through one private say(topic, payload) — the business logic never spells a crossing.

The handshake: both opaque directions meet

Closures cannot cross the boundary in either direction, so callbacks register by name: the plugin hands the host the export names it wants wired to each topic, and returns the handle to its own state (init is the entire handshake — bus box in, state handle out):

entry fn init(bus: opaque) -> opaque {
    subscribe(bus, "join", "on_join");
    subscribe(bus, "msg", "on_msg");
    subscribe(bus, "leave", "on_leave");
    subscribe(bus, "tick", "on_tick");
    let mod_: ?Moderator = Moderator.new(bus);
    return opaque(mod_);
}

• rut’s moderator state comes back as a rut-constructed opaque — the host holds the handle and passes it back on every event.
• the host’s EventBus goes in as a host-constructed Opaque<EventBus> — subscribe and emit are that box’s callbacks, reached only through the borrow guards (Value boundary and borrows, Embedding and native modules).

The re-entrant call: emit re-enters rut mid-op

The host binds the two server rows over its bus. The emit body is the interesting one — while the emitting handler is still parked mid-op, it makes a nested vm.call("render_line") to format the wire line:

#![allow(unused)]
fn main() {
rut_vm::register!(
    hosts,
    "server::emit",
    (Opaque<EventBus>, &str, &str) -> (),
    |vm: &mut Vm, bus: Opaque<EventBus>, topic: &str, handler: &str| -> Result<(), Trap> {
        bus.with_mut(vm, |vm, b| -> Result<(), Trap> {
            let line: String =
                vm.call("render_line", (topic.to_string(), handler.to_string()))?;
            b.lines.push(line);
            b.emits += 1;
            b.renders += 1;
            Ok(())
        })?
    },
);
}

(The comment above this code in the source is worth reading too.) The bus stays mutably borrowed across the nested call — the value boundary’s borrow guard is what makes that sound: a second emit fired from inside render_line would trap on the guard instead of racing. On the rut side, render_line is the one-line entry the host re-enters — pure string work, so it runs on its own (the line it prints below is the transcript’s broadcast row):

use ink::{ Logger };

entry fn render_line(topic: str, payload: str) -> str {
    return f"[{topic}] {payload}";
}

pub fn main() {
    let log = Logger.new("bus");
    log.info(render_line("broadcast", "<ada> hello world"));
}

[broadcast] <ada> hello world

The packaging: one directory, two load forms

The plugin is a module directory — a manifest naming the entry plus its deps, loadable as-is and packable unchanged (Project structure and rut.toml):

# plugin/rut.toml
format = "rutbundle"
format_version = 4
name = "plugin"
entry.lib = "./plugin.rut"

[deps]
server = { path = "../server" }
pouch = { path = "../../../rut/pouch" }

server/ is the interesting dependency: a pure declaration surface — a host package whose manifest points at a .d.rut decl file, with the Rust embedder binding the bodies (Host fns and declaration files):

pub host fn subscribe(bus: opaque, topic: str, handler: str);

pub host fn emit(bus: opaque, topic: str, payload: str);

main.rs packs the same directory with rut_driver::pack_dir, writes plugin.rutbundle to temp, and loads it back through the identical Plugin::load — the transcript equality print is the proof. The CLI drives the same loader for any self-contained module:

rut run path/to/mod            # a module directory (rut.toml)
rut pack path/to/mod           # -> mod.rutbundle
rut run path/to/mod.rutbundle  # the packed form

The Rust side mirrors the rut layering: business code calls typed methods (p.join("ada"), p.msg(...)), and vm.call happens in exactly one dispatcher that looks up the subscribed export name per topic — unknown topics are dropped, not trapped, so a server keeps running when a plugin didn’t subscribe.

Takeaways

• One directory is one module; the manifest names the entry and the deps, and the same directory packs to a .rutbundle unchanged.
• Registration by name, not by closure — callbacks never cross the boundary as values, in either direction.
• Re-entrancy is sound by construction: a host fn can call back into rut mid-op, and the borrow guard turns a would-be data race into a loud trap.
• Both opaque directions compose: rut-state-out, host-state-in, and neither side can inspect what the other erased.
• The layering discipline — adapters own the crossing protocol, business logic stays pure — is what keeps a plugin auditable.

The crossing rules this example lives on are in the host boundary; the load forms are specified in Module bundles.

04 — Custom async

A parse-only example: examples/04-custom-async/custom_async.rut is a single rut file with no Cargo harness — you cannot run it today, and that is a deliberate disclosure, not an oversight. What it shows is the async vocabulary from the user side: a hand-written future type, an impl of the engine’s built-in Future trait, and a user-written launcher with per-checkpoint stats and cancellation audits. The runnable harness that would drive it end to end is the follow-up work; the file is kept in the repo now because the parser’s conformance suite compiles every example, so this vocabulary is checked to stay parseable (Async and await).

“Run” it

There is no harness. The file is exercised by the parser conformance test, which walks every .rut file in examples/:

cargo test -p rut-parser --test corpus    # parses every example, incl. this one

To read the same machinery running, see 06 — GitHub viewer CLI: its brain is an async fn driven by the standard launcher this file re-spells by hand.

Code tour

The audit log — the example’s reason to exist

CustomFuture is a stage machine, but the point of the file is the accounting around it: every launch, resumption, cancellation, and completion lands in one module-owned record the embedder can read after the run:

struct AuditLog {
    launches: u32;      // futures this log saw started
    yields: u32;        // resumptions driven — one per checkpoint
    cancels: u32;       // cancellation probes that answered true
    checkpoints: u32;   // high-water mark of the context ledger
    finished: u32;      // runs that walked every step they booked
}

The launcher takes a shared ?AuditLog, so the embedder holds one cell and reads the whole run’s story out of it afterwards — summary renders the one-line audit.

The machine — what async fn weaves, spelled out

When you write async fn, the engine weaves a hidden frame whose shape is exactly this: a stage counter, the payload the stages carry, and a done flag. CustomFuture spells that shape out in source, so you can see what the keyword hides. The machine itself is plain rut — only the driving harness is missing — so the block below adds a main that advances it by hand; that is as far as one can run it today:

use ink::{ Logger };

struct CustomFuture {
    steps: u32;      // checkpoints booked before the run finishes
    stage: str;      // what the current stage does (the audit's label)
    done: bool;      // the last stage ran
}

impl CustomFuture {
    fn new(steps: u32, stage: str) -> Self {
        return Self { steps: steps, stage: stage, done: false };
    }

    /// One stage of work — what one resumption advances. `false` when
    /// no stages are left: the runner's completion signal.
    fn advance(mut self) -> bool {
        if (self.done) {
            return false;
        }
        if (self.steps == 0) {
            self.done = true;
            return false;
        }
        self.steps -= 1;
        return true;
    }
}

pub fn main() {
    let log = Logger.new("future");
    let mut f = CustomFuture.new(3, "poll");
    let mut polls = 0;
    while (f.advance()) {
        polls += 1;
    }
    log.info(f"3 steps took {polls} advancing polls, then advance() answered false (done={f.done})");
}

3 steps took 3 advancing polls, then advance() answered false (done=true)

The trait surface: a user impl of a built-in trait

Future is an engine-named built-in trait — the engine weaves it for every async fn’s hidden frame — but built-in traits are engine named, not engine closed. A hand-written machine registers through the ordinary nominal path, one impl block, and rides the same drive law (Traits and dispatch):

impl Future<nil> for CustomFuture {
    fn yield(self, cx: RunContext) {
        // the ledger view: the frame's resume state, read as data
        let at = cx.checkpoint();
        // the cancellation probe: a cancelled frame stops advancing —
        // the audit sees it as "died here, did not advance" — and runs
        // its drop path instead of the next stage
        if (cx.cancelled()) {
            self.done = true;
            self.stage = f"{self.stage}@{at}:cancelled";
        }
    }
}

The receiver is the frame — the machine’s fields are its state — and the context is the only handle a resumption needs. The frozen context protocol reads as data: checkpoint answers this frame’s resume state, cancelled answers the task’s abort flag. Cancellation is a value the frame inspects, not an exception it catches.

The user launcher

The engine’s standard launcher set (launch_future, LaunchedFutureHandle, sleep) is ordinary code any module may re-spell — that is the point of launch_custom. It supplies the driving and the audit over the same Future surface, so the machine never knows which launcher started it:

use async_engine::{ __abort, __launch };

fn launch_custom(f: Future<nil>, log: ?AuditLog) -> CustomLaunched {
    __launch(opaque(f));
    log.note_launch();
    return CustomLaunched { task: f, log: log, alive: true };
}

The returned CustomLaunched receipt is deliberately not a future — it cannot be awaited, and it is not re-launchable (that is a type error, never a runtime check). Its one real member is the cancel edge, which flags the task and lets the loop’s re-drive run the probe:

    fn cancel(mut self) -> bool {
        if (!self.alive) {
            return false;
        }
        self.alive = false;
        let t = self.task;
        if (t == nil) {
            return false;
        }
        let log = self.log;
        if (log != nil) {
            log.note_cancel();
        }
        return __abort(opaque(t));
    }

Alongside sits audit_drive, the audit twin of the engine loop’s drive columns: run a stage, count the resumption, stop on completion.

Scope, honestly

Two boundaries to keep straight when you read this file:

• User futures are launcher-drivable — the driving loop finds the Future::yield row in the vtable, exactly as it does for woven frames.
• await targets engine-woven futures only in the current build (async-fn results and sleep); awaiting an arbitrary user impl, and joining concurrent futures, land with the next async milestone.

So today the file is a parse-checked design corpus and a teaching document: the shape of the weave, the shape of a launcher, and the proof that the future trait is a user-extensible surface — not a runnable demo. When you want the runnable version of the same story, read 06 — GitHub viewer CLI, and for the model behind it, the async model.

Takeaways

• async fn compiles to a hidden frame implementing Future — this file spells that frame out in user source.
• Built-in traits are engine-named, not engine-closed: impl Future<nil> for YourType registers through the ordinary path.
• Cancellation is data the frame reads (cx.cancelled()), and every checkpoint is observable (cx.checkpoint()).
• A launcher is just code: driving + audit over the public Future surface, re-spellable by any module.
• The file is parse-only by disclosure; the runnable harness is follow-up work — the machine itself is plain rut (it ran above), but nothing launches or drives it as a future yet.

05 — Todolist web

One page app — a todolist with a simulated server — where every DOM move and every timer goes through ten declared host crossings, and the page’s brain is a rut project of two packages. ui is the framework: an atom store (the jotai shape, in rut), a widget type, a keyed diff, and a component vocabulary. biz is the domain: the todolist machine expressed as store mutations, plus the app shell. The host — web-sys on wasm32 in the browser, a fake-DOM twin on native in the tests — owns the loop; rut owns the state. Pure rut: no event loop, no async keywords on the rut side; every asynchronous fact enters through a door named for its event.

Run it

cargo test -p todolist-web       # the twin + the law (95 tests), from the repo root
cd examples/05-todolist-web
node tests/e2e-browser.mjs       # the through-the-artifact gate (node tier + browser tier)

cargo test runs the whole story on the fake-DOM twin — a HashMap element tree with real DOM semantics and a virtual timer clock — over the same rut sources the browser runs. The e2e script builds nothing silently and skips nothing silently: tier 1 (plain node) drives the real wasm artifact through the loader’s own ABI on a fake DOM; tier 2 (when geckodriver + Firefox exist) types and clicks the live page.

To open the page yourself:

cd examples/05-todolist-web
cargo build -p todolist-web --target wasm32-unknown-unknown --release
wasm-bindgen --target web --out-dir gen --out-name web_host \
  ../../target/wasm32-unknown-unknown/release/todolist_web.wasm
python3 -m http.server        # then open http://localhost:8000/

What you’ll see: type a title — the status line echoes the typing and the counts never move (the draft is not a counts dependency). Press Add — an italic pending line paints immediately, the counts line flips to 1 in flight, and ~400 ms later the committed row replaces it. Toggle a row — the title goes italic for ~250 ms, then the check fills and the title strikes through. The row animates because the keyed diff kept the node alive — nothing is cleared and rebuilt, ever.

Code tour

The ABI is the page: main plus the doors

rut/biz/app.rut — the boot turn builds the app container and returns it as an opaque (rut has no mutable module state, so the host holds the state and re-passes it every turn — the 00 — Todolist pattern at page scale):

entry fn main() -> opaque {
    let boot: World = world_boot("booted — type a title, press Add");
    let root = AppRoot {
        world: boot,
        t1: t1_mount("app"),
    };
    paint(root);
    return opaque(root);
}

Every asynchronous fact enters through a door named for its event — on_click/on_input for DOM events, on_timer for the clock. Each door re-passes the container and answers the entry-err pair: (opaque(c), "") on a clean turn, (nil, why) on a soft failure the pump reports while keeping the page alive.

fn dom_event(mut r: AppRoot, id: str, detail: str) -> (?opaque, str) {
    let booked = t1_event(r.t1, id, detail);
    let req = opaque.downcast<Req>(booked);
    if (req != nil) {
        tim_after(req.latency, req.tag);
    }
    paint(r);
    return (opaque(r), "");
}

The “server” is a request table, not a scheduler: adding never touches the list — the machine books a request and the app books one tim_after(latency, tag); the list changes only when the timer’s turn runs the answer mutation (per-kind latency, so deadline-ordered commits are visible across kinds).

The ten crossings

web.d.rut (flat at the example root, registered by hand in both lanes) declares the whole host surface. Elements cross as opaque handles; everything else is strings, ints, and bools — no app names, no data shipping, no callbacks (the host boundary):

pub host fn ui_get(id: str) -> opaque;
pub host fn ui_create(tag: str) -> opaque;
pub host fn ui_set_text(el: opaque, text: str);
pub host fn ui_attr(el: opaque, name: str, value: str);
pub host fn ui_append(parent: opaque, child: opaque);
pub host fn ui_remove(parent: opaque, child: opaque) -> bool;
pub host fn ui_clear(el: opaque);
pub host fn ui_set_input_value(el: opaque, v: str);
pub host fn ui_listen(el: opaque, event: str) -> i64;
pub host fn tim_after(ms: i64, tag: str);

A wiring bug is loud: a missing id traps (web::ui_get: no element '#x'), a kind mismatch names both sides. The host never grew an app-specific crossing — the entire widget system fits over these ten rows, unchanged.

The store: jotai’s shape over private traits

rut/ui/store.rut is the kernel. Handles are keys, not objects — Source<T>, Derived<T>, Mutation<A, R> carry ids and have no logic of their own beyond routing through their store. The machinery traits are module-private, so the domain package cannot name them even to import them — which is how “a derived cell is not writable” is enforced at the type level (Traits and dispatch):

trait Readable<T> {
    fn atom_id(self) -> u32;
    fn materialize(self, st: Store) -> nil; // first touch: the seed lands
}

trait Writable<A, R> {
    fn atom_id(self) -> u32;
}

Freshness is pull-on-read: a write bumps a generation, and a get recomputes a stale derived at most once per write-set. There is no flush step anywhere. Dependencies are discovered, never declared — the ctx.get calls inside a derive closure ARE the dependency list, re-recorded on every recompute. The domain’s counts line is the worked example (rut/biz/world.rut):

let counts$ = store.derive(fn (ctx) -> str {
    let items = ctx.get(items$);
    let reqs = ctx.get(reqs$);
    let mut open = 0;
    for (let t of items) {
        if (t.done == false) {
            open += 1;
        }
    }
    let done_n = items.len() - open;
    return f"{open} open | {done_n} done | {reqs.len()} in flight";
});

Writes go through mutation fns — add_m, toggle_m, remove_m, answer_m — multi-step write programs that run in the one write lane; the machine’s counters are sources too, because with no domain container there is nowhere else for state to live.

Widgets are data; the diff does the DOM

view(r) is a pure function from app state to a Widget tree — it runs no crossing and reads nothing (reads are reactive props, resolved at the render door). t1_render diffs the new tree against the previous one held in T1Root and fires only deltas: match children by key, patch in place, re-append on reorder, retire gone keys’ listeners. Nothing changed = nothing fires (HashMaps and sets carry the path-keyed tables):

pub struct T1Root {
    parent: opaque; // the mounted root element
    prev: ?Widget = nil; // the previous tree — the diff's left side
    els: HashMap<str, opaque>; // path -> live handle (ops application)
    regs: HashMap<str, Ev>; // listener id (as crossed) -> the
    // widget's event wiring (a data-shaped binding)
    lids: HashMap<str, i64>; // path -> listener id (retirement)
}

Event wiring rides the widgets as data, not closures — a row’s toggle mutation carries its argument bound (.on_row(w.toggle_row, t.id)), and the framework resolves a firing listener id to that wiring. Styling is a token contract: the stylesheet keys only the lowered t1-* tokens, and the app spells no class.

Two packages, two manifests

A real project is not one file — but the package boundary is also the privacy boundary, which is why there are exactly two (Project structure and rut.toml):

# rut/biz/rut.toml — the project root
name = "app"
entry.lib = "./biz.rut"
entry.libs = ["./domain.rut", "./world.rut", "./app.rut"]

[deps]
ui = { path = "../ui" }
pouch = { path = "../../../../rut/pouch" }
nmapset = { path = "../../../../rut/nmapset" }

entry.libs splices several files into ONE module (base first, array order), so a name private to store.rut is visible to components.rut and to nothing outside ui — single-file privacy, kept at package scale. ui is marked inline = true (its generic exports splice by law), and the native lane mounts the directory — the manifest, not a Rust fn, is the module list. The wasm lane mounts the same packages by hand as a mirror, and a test pins both lanes to byte-identical binaries.

Takeaways

• The page ABI is main plus doors named for their events; state lives in the container the host re-passes every turn.
• Ten thin crossings carried an entire reactive framework — the host stayed generic and never learned the word “todo”.
• The store is jotai’s shape in rut: discovered deps, pull-on-read freshness, mutations as the write lane, and type-level non-writability through private traits.
• Widgets are values; the keyed diff is the only thing that speaks DOM, and patch-in-place is what makes the UI animatable.
• Soft failures are data ((nil, why) and the pump keeps draining); a panic alone kills the page, loud.

The async shape this page simulates (the request table + timers) is the real thing in 06 — GitHub viewer CLI; the store’s building blocks are in the swappable packages.

06 — GitHub viewer CLI

rgh lists and downloads files from public GitHub repositories over the jsDelivr CDN — no GitHub API, no tokens. Its brain is a rut async free fn: argv carving, the URL building, the tree JSON decode, the human-size formatter, every message and exit code run in the VM. The Rust half is a pure embedder: mount packages, bind host bodies, launch the brain, pump the driving loop to idle, exit with the brain’s i32 (0 ok, 1 runtime error, 2 usage). This is the worked example for the std http lane’s redesigned face — HttpClient, builder-style construction, and async-only send with true streaming.

Run it

cargo run -p rgh -- --repo=jquery/jquery --ref=3.7.1 list
cargo run -p rgh -- --repo=jquery/jquery --ref=3.7.1 download test/data/1x1.jpg
cargo test -p rgh                  # the offline suite — zero network
RGH_LIVE=1 cargo test -p rgh live_smoke   # opt-in live CDN check

list prints one line per file, depth-first in the API’s own order (directories are walked, never printed):

<repo path>\t<human size>\t<hash8>

The size ladder is N B under 1024, then KiB/MiB/GiB with one decimal only when the remainder is nonzero (1536 → 1.5 KiB, 1048577 → 1.0 MiB); the last column is the first 8 characters of the entry’s base64 integrity hash, or - when absent. The offline suite rides a fixture lane keyed on method + URL with a virtual clock — the fixture map’s keys ARE the assertions — and covers every usage error, the boundary tree’s exact output, streamed binary downloads verified byte-verbatim, wire deaths, and status mappings.

Code tour

The brain is async; the host launches and pumps

rgh.rut — the entry point is one boot fn: the host crosses argv in as a single \n-joined string (no arg lists in the crossing set), and boot launches the brain with the standard launcher (Tasks):

entry fn boot(args: str) -> nil {
    launch_future(rgh_main(args));
}

The embedder then pumps the driving loop to idle — real reqwest workers settle the completers from their threads, and the process’s one-way exit row fires mid-pump:

#![allow(unused)]
fn main() {
loop {
    match vm.run_ready() {
        Ok(_) => {}
        Err(t) => {
            eprintln!("rgh: trap: {} — {}", t.name(), t.msg);
            std::process::exit(1);
        }
    }
    if vm.pending_tasks() == 0 {
        // the brain retired WITHOUT exiting — a brain bug: loud
        eprintln!("rgh: the brain retired without exit (a brain bug)");
        std::process::exit(1);
    }
    std::thread::sleep(std::time::Duration::from_millis(2));
}
}

The awaits live at the fetch sites and only there — everything else (argv carving with the scan/slice tokenizer primitives, flags, JSON, formatting) is the same sync code it always was.

The http face: build a request, await the send

The std http package is async-only and unsuffixed: only the operations that really wait are async points, everything else is sync construction sugar. The five verbs are build sugars (get/post/ put/patch/del — the DELETE verb spells del because delete is a removed word in rut’s grammar; the wire still sees canonical DELETE), and send(cx) is THE async point, resolving at headers — the wire body stays unread (the async model):

async fn do_list(cx: RunContext, client: HttpClient, owner: str, repo: str, rf: str) -> i32 {
    let url = f"https://data.jsdelivr.com/v1/packages/gh/{owner}/{repo}@{rf}";
    let resp = await client.get(url).build().send(cx);
    let err = map_response(resp, "no such repo or ref", "data.jsdelivr.com");
    if (err != nil) {
        let why: str = err;
        eprint(why);
        return 1;
    }
    let (tree, e) = decodeJsonBytes<Root>(await resp.body(cx));

list is the drain lane: one body(cx) await pulls the whole tree, and the JSON decode goes through the std json package’s reader with impl JsonDeserialize for Entry in this file. Status mapping is one function: status() == 0 is the reserved transport verdict, 404 names the host that was checked, 403 is the rate-limit note, anything else non-2xx is the bare status.

The download: true streaming, chunk by chunk

download walks a ByteStream — next(cx) answers one chunk per await (nil = EOF-or-failed; the sticky error() names which), and each chunk lands through the sync append_file host row. The destination is truncated once first, so a stale file never leaks its tail into a fresh download:

    let stream = resp.byte_stream();
    let mut total: i32 = 0;
    while (true) {
        let c = await stream.next(cx);
        if (c == nil) {
            // EOF — or a mid-read failure? the sticky error names it
            let rerr = stream.error();
            if (rerr != nil) {
                let why: str = rerr;
                eprint(f"rgh: {dest}: {why}");
                return 1;
            }
            break;
        }
        let chunk: bytes = c;
        let werr: ?str = append_file(dest, chunk);
        if (werr != nil) {
            let why: str = werr;
            eprint(f"rgh: {dest}: {why}");
            return 1;
        }
        total += chunk.len();
    }

Bounded memory end to end, and every failure on the data path is a message plus an exit code — never a panic, never a trap. The lane’s one-shot law is worth knowing: per response it is body() xor byte_stream(), and a late/second taker degrades (an empty drain, a dead reader) rather than trapping.

The readbacks, on the response handle

The Response class wraps the host’s opaque handle with sync readbacks — status, the 2xx test, the transport text, and the sticky mid-read failure (the std packages):

impl Response {
    /// the HTTP status word — 0 means the transport failed (0 is never
    /// a real status; any real status, 4xx/5xx included, is not one)
    pub fn status(self) -> i32 { return http_status(self.r); }

    /// the 2xx test
    pub fn ok(self) -> bool {
        let s = self.status();
        return s >= 200 && s < 300;
    }

    /// the transport-failure text — nil unless status is 0
    pub fn transport_error(self) -> ?str { return http_err(self.r); }

    /// the sticky mid-read failure — nil until one fails, then
    /// non-nil forever; meaningful after awaiting `body()`/`next()`
    pub fn read_error(self) -> ?str { return http_read_err(self.r); }

The embedder’s mount list

src/main.rs shows the whole program closure in one table — the collections, json, and the http pair, then assemble_peers runs the peer gate so json’s impl-only integration groups mount because the collections are in the closure (Dependency kinds):

#![allow(unused)]
fn main() {
const MOUNT_DIRS: &[&str] = &[
    "rut/pouch",
    "rut/nmapset",
    "rut/json",
    "rut/http_host",
    "rut/http",
];
}

The HTTP bodies bind through install_std_http (the reqwest lane); the example’s own rows are CLI I/O only — out (stdout; print is a removed core name), eprint, the file pair, and exit — declared in the example-local rgh_host decl package and verified against the bindings at boot (Host fns and declaration files). One consequence: rut run cannot host rgh itself — its rows are example-local — but ordinary HTTP programs do run under rut run, which mounts the std http pair by presence.

Takeaways

• An async rut program in production shape: the brain awaits at the fetch sites only; the embedder launches, pumps to idle, and exits with the brain’s code.
• Headers-first send + one-shot body/stream is the whole mental model of the std http lane — drain JSON in one await, stream files chunk by chunk.
• Failures are values end to end: transport errors, 404s, wire deaths, and io errors all become messages plus exit codes.
• The fixture lane is the test gate: recorded replies keyed on method + URL, deterministic chunks on a virtual clock, zero network.
• The peer gate is load-bearing here: mounting the collections is what makes json’s Vec<T> serde impls compile into this unit.

The lane’s declarations live in the std tree; for the runner behind rut run, see the rut CLI.

The playground corpus

The classics: seventeen short, self-contained rut programs in demo/src/examples/ that the web playground offers in its picker and runs in your browser. They are not copies — the playground imports the .rut files raw, so what you edit there is what this repo ships. The classics are the fastest way to see the language surface in working code: algorithms first, then the language-surface tours, then the memory shapes. The same order is the playground’s.

Run it

The playground itself:

cd demo && npm run dev      # serve the playground locally
# or use the deployed instance: https://playground.rut.hpp2334.com

Pick a case and press run — and the classics shown in the tour below run in the book too, on their ▶ buttons. The gates that keep the corpus honest:

cargo test -p rut-cli --test playground   # from the repo root — the native gate
cd demo && npm run smoke                  # the wasm gate, headless

Concretely:

• cargo test -p rut-cli --test playground compiles and runs every classic through the full pipeline natively — a compile failure or a trap fails the gate.
• cd demo && npm run smoke builds the demo bundle (wasm included) and drives every case through it, headless — the same run through the wasm engine.

Both gates drive the same sources through the same engine — native and wasm — so a classic that stops running cleanly fails in CI, not in front of a reader.

The seventeen cases

Output goes through ink’s Logger (the log.info lines above) — the same logging surface the std packages use (core and the swappable packages).

Code tour

A classic, whole

demo/src/examples/quicksort.rut is the archetype — imports, one algorithm, one log line — and the shared-handle mutation law in action (the sort writes through the caller’s vec). Verbatim, so what runs here is exactly what the playground edits:

use pouch::{ Vec };
// Quicksort — in-place Vec<i32> mutation (vecs are handles: the
// mutation is shared with the caller), recursion, explicit conversions.

use ink::{ Logger };

fn swap(mut xs: Vec<i32>, a: i32, b: i32) {
    let t = xs[a];
    xs[a] = xs[b];
    xs[b] = t;
}

fn partition(xs: Vec<i32>, lo: i32, hi: i32) -> i32 {
    let pivot = xs[hi];
    let mut i = lo - 1;
    for (let j = lo; j < hi; j += 1) {
        if (xs[j] <= pivot) {
            i += 1;
            swap(xs, i, j);
        }
    }
    swap(xs, i + 1, hi);
    return i + 1;
}

fn quicksort(xs: Vec<i32>, lo: i32, hi: i32) {
    if (lo >= hi) { return; }
    let p = partition(xs, lo, hi);
    quicksort(xs, lo, p - 1);
    quicksort(xs, p + 1, hi);
}

pub fn main() {
    let log = Logger.new("sort");
    let xs = Vec<i32>.from([5, 2, 9, 1, 7, 3, 8, 2]);   // fixed -> growable
    quicksort(xs, 0, xs.len() - 1);

    let mut out = "";
    for (let i = 0; i < xs.len(); i += 1) {
        out = f"{out}{xs[i]} ";      // `mut`: rebinding; the f-string form builds in place
    }
    log.info(f"sorted: {out}");
}

sorted: 1 2 2 3 5 7 8 9 

(The line above ends with the trailing space the program builds — one after every element — kept byte-for-byte.)

Compare with 01 — Sort: same algorithm, no host — run it here and compare with the fuel-counted host sweep.

Erasure and checked recovery, in one screen

The opaque case is the reference for the erasure primitive — opaque(v) forgets the static type, opaque.downcast<T> answers the nullable, and is names the box, never the payload (opaque — erasure and downcast). The case’s erase_and_recover verbatim, with its two payload types and a main so it runs in place:

use ink::{ Logger };

struct Point { x: f32; y: f32 }
enum Flavor { Sweet, Sour }

fn erase_and_recover() {
    let log = Logger.new("opaque");
    let box1 = opaque(Point { x: 1, y: 2 });    // erasure = type-call;
    let box2 = opaque(Flavor.Sour);             // zero-copy (shares the cell)
    let box3 = opaque("hello");

    let p = opaque.downcast<Point>(box1);       // ?Point — the nullable
    when (p != nil) {
        true -> { log.info(f"point {p.x} {p.y}"); },
        else  -> { log.info("point: nil"); },
    }
    let wrong = opaque.downcast<i32>(box2);     // wrong type: nil, no trap
    log.info(f"sour? {opaque.downcast<Flavor>(box2) != nil} wrong? {wrong == nil}");
    log.info(f"is str: {box3 is str}");   // `is` names the box — misses every payload type; downcast recovers
}

pub fn main() {
    erase_and_recover();
}

point 1 2
sour? true wrong? true
is str: false

How a case is wired

Each classic is registered in demo/src/examples/index.ts — an id, a blurb, and the raw source, in the playground’s order. The table above quotes each case’s first log line, and the tour’s blocks run right here — quicksort exactly as shipped. Two details worth noticing when you browse: the corpus is walked by the parser conformance test too (alongside examples/ and the std tree — every .rut file in the repo must parse clean), and one quicksort log line ends with a trailing space the program builds on purpose — run it above and look closely.

Takeaways

• The classics are live sources, not string copies: the playground edits what the repo ships.
• Every case is exercised by two gates — native and wasm — over the same engine.
• Seventeen files cover the language surface in run-sized doses: algorithms, types and traits, strings and bytes, erasure, patterns, maps, and the memory shapes.
• When you change the language, these files are the first smoke test — and often the clearest place to demonstrate the change.

For the bigger, host-driven versions of the same ideas, start at 00 — Todolist and work up to 06 — GitHub viewer CLI.

Lexical structure

The character-level rules of rut source: files, comments, identifiers, the keyword set, and the enforced naming conventions.

Source model

• Files are UTF-8, extension .rut. Both LF and CRLF line endings are accepted (CRLF is normalized); a leading BOM is skipped.
• Comments:
  • // line comment
  • /* block comment */ — block comments do not nest
  • /// doc comment (also /** ... */) — attaches to the following declaration and is kept for tooling; it is not semantic
• There is no off-side rule: statements end with ; (required), blocks are braced.

Identifiers and $

ident := (letter | "_" | "$") (letter | digit | "_" | "$")*

$ is an ordinary identifier character, valid anywhere in a name: on_mount$, viewport_size$, $temp, $x1, even $ alone. There is no $ punctuation token and no $-interpolation (f-string holes use { } — see Literals and inference).

The trailing $ is a naming convention, not a lexical category: it marks dispatch-inverted members — anything a runtime fires or owns rather than you calling it. Event props (on_click$), lifecycle hooks (on_mount$, before_destroy$), subscription updates (on_update$), watch controls (start$, stop$), engine atoms (viewport_size$), and mutation handles generally. Never on functions you call, widget builders, or types.

Keywords

The keyword set is exactly:

Contextual words — ordinary identifiers elsewhere:

panic(msg) and assert(cond, msg?) are prelude functions, not keywords.

Reserved words

Each reserved word is a hard error whose message names the rut replacement:

Naming conventions (enforced)

• Types are PascalCase — user types and parameterized builtins: Vec<T>, [T], Weak<T>, opaque, Task<T>, Point, Drawable. Scalars and simple buffers stay lowercase: i32, u8, f32, bool, str, bytes.
• Functions and methods are lower_snake_case — unwrap_or(d), push(v), checked_add(y), spawn_worker(..).
• Construction is a method call, never a type-call. User classes construct through their own class methods: Rect.new(3, 4), Rect.from(other), Version.parse(s) — see Classes and constructors. Only builtin surfaces keep call forms: bytes.zeroed(n), Weak(v), opaque(v), the repeat [v; n], and Vec<T>.from(..) (see Builtin generic types).
• The trailing-$ marker is kept meaningful by this style rule alone; the compiler attaches no semantics to it.

Modules and visibility

Module scope contains declarations only — every statement lives inside a function, and loading a module executes nothing. Visibility is private by default, with package-scoped forms for libraries.

Module structure

Allowed at module scope: