Rotifer v0.1: CLI Framework & Rust Core

The first alpha of the Rotifer Playground is here. This release establishes the full gene development lifecycle in a single CLI, backed by a Rust core that takes WASM sandboxing, fitness computation, and algebraic composition seriously from day one.

Why Rust?

The choice of Rust for the core engine was deliberate. We evaluated three options:

• Node.js native modules — familiar to TypeScript developers, but garbage collection pauses make deterministic performance measurement impossible. When you're computing fitness scores that determine gene rankings, you need reproducible timing.
• Go — excellent concurrency primitives and fast compilation, but its WASM runtime options (wazero) were less mature than wasmtime at the time. More critically, Go's garbage collector introduces the same non-determinism problem.
• Rust — zero-cost abstractions, deterministic execution, and direct access to wasmtime (the industry-standard WASM runtime, also written in Rust). No garbage collector means fuel consumption measurements are accurate and reproducible.

The trade-off is clear: Rust imposes a steeper learning curve on contributors, but it delivers the execution guarantees the protocol requires. Since the CLI layer remains in TypeScript (via napi-rs bridge), gene authors never need to touch Rust.

10 CLI Commands

The CLI covers the entire gene lifecycle out of the box:

rotifer init          # scaffold a project with genesis genes
rotifer scan          # discover candidate functions from source
rotifer wrap          # wrap functions as genes (phenotype generation)
rotifer test          # sandbox testing
rotifer compile       # phenotype validation + fingerprinting
rotifer arena submit  # submit to local Arena with admission gate
rotifer arena list    # view rankings: F(g), V(g), Fidelity
rotifer arena watch   # placeholder for live ranking updates
rotifer agent create  # create Agents with gene genomes
rotifer agent list    # view all registered Agents

Rust Core

The rotifer-core crate provides the foundational type system and engines:

• Type System — Context, GeneResult, Phenotype, Gene, Agent, AlgebraExpr
• WASM Sandbox — wasmtime-based with resource limits, fuel consumption, and epoch interruption
• Arena Engine — local ranking with fitness-based sorting
• Algebra Executor — Seq, Par, Cond, Try, Transform composition operators
• Fitness Computation — simplified fitness score (F(g)) model with admission threshold
• SQLite Storage — persistent genes, agents, and arena entries

The WASM Sandbox Architecture

The sandbox is built on wasmtime with three layers of resource control:

1. Fuel metering — each gene receives a fuel budget (default: 1,000,000 units). Every WASM instruction consumes fuel. When the budget is exhausted, execution halts immediately. This prevents infinite loops and ensures fair resource allocation in the Arena.
2. Memory limits — each gene's linear memory is capped (default: 16 MB). Attempts to grow beyond the limit result in a trap. This prevents memory exhaustion attacks where a malicious gene could starve the host process.
3. Epoch interruption — a wall-clock timeout (default: 30 seconds) catches cases where a gene is technically making progress (consuming fuel slowly) but taking too long. The epoch counter is checked between function calls, providing a coarse-grained timeout without the overhead of per-instruction checks.

These three mechanisms are independent and composable. A gene must satisfy all three to complete execution successfully.

5 Genesis Genes

Every new project ships with 5 pre-installed genes:

Gene	Domain
genesis-web-search	Full search with multiple results
genesis-web-search-lite	Lightweight single-answer search
genesis-file-read	Local file reading
genesis-code-format	Source code formatting
genesis-l0-constraint	L0 sandbox constraint checker

Design Philosophy

The genesis genes are not just examples — they're a carefully chosen set that demonstrates the protocol's key concepts. genesis-web-search and genesis-web-search-lite show how two genes in the same domain (search) compete in the Arena; the lite version wins on speed while the full version wins on completeness, illustrating the fitness trade-off. genesis-l0-constraint is a meta-gene: it checks whether other genes comply with the protocol's invariants, demonstrating that genes can reason about other genes.

Together, the five genesis genes provide enough diversity for a new developer to run rotifer arena list and see meaningful rankings within minutes of scaffolding a project.

Developer Experience

Following the "Three-Act Demo" design pattern:

1. Wow (30s) — rotifer init scaffolds a working project with Arena preview
2. Aha (5min) — wrap your own function, submit to Arena, see it ranked
3. Hooked (30min) — compose genes, create Agents, explore fitness dynamics

Error messages follow Rust conventions: error codes, actionable suggestions, and documentation links.

By the Numbers

• 10 CLI commands
• 29 tests (unit + E2E)
• 5 genesis genes
• napi-rs bridge connecting Rust core to TypeScript CLI

Get Started

npm install -g @rotifer/playground
rotifer init my-project

Looking Ahead

v0.1 was a statement of architectural intent: the protocol takes sandboxing, composition, and fitness computation seriously from day one. Every subsequent version built on this foundation — the IR compiler (v0.2), TypeScript compilation (v0.3), cloud registry (v0.4), and reputation system (v0.5) all depend on the type system and execution engines established here.

• Full Changelog