Arena Commands
The Arena is where genes compete. Same-domain genes fight head-to-head on fitness metrics. The fittest survive.
rotifer arena submit
Section titled “rotifer arena submit”Submit a gene to the Arena for competitive ranking.
rotifer arena submit <gene-name> [options]Arguments:
| Argument | Required | Description |
|---|---|---|
gene-name | Yes | Gene name to submit |
Options:
| Flag | Description |
|---|---|
--cloud | Submit to Cloud Arena (requires login) |
--skip-test | Skip pre-submission testing |
--allow-credentials <list> | Let external genes use these credentials from your environment, each only at its host: KEY@api.example.com,KEY2@other.example.com. It has no effect today: only Hybrid genes can declare a credential, and arena submit scores Hybrid genes without running them, so it has nothing to ask about |
Process:
- Run the pre-submission tests (unless
--skip-test). - If the gene is compiled (
gene.ir.wasmexists) and the native runtime is available, run it 3 times in the WASM sandbox and measure success, latency and fuel. Otherwise the score is derived from the gene’s content hash, and the output saysNot executed. - Compute fitness F(g) and safety V(g), and apply the fidelity discount.
- Check admission and record the entry.
Local Arena stores rankings in .rotifer/playground.db.
Cloud Arena (--cloud) requires login and a gene already published with rotifer publish.
How F(g) is scored (since v0.9.3)
Section titled “How F(g) is scored (since v0.9.3)”-
Reference scale. The latency and cost terms of F(g) are measured against the median of genes in the same domain with the same fidelity, measured in the current Arena season. Each author’s gene counts once (its latest published version), only runs recorded by the gene’s own author count, and invalidated entries are left out.
-
Fallback. The median is used only when at least 5 such genes have been measured this season. With fewer, or when the registry cannot be reached, fixed constants are used instead (1000 ms for latency, 10,000 fuel for cost). The output always says which one it used:
Reference scale: season <N> median of <n> <domain> / <fidelity> genes (L_ref <ms> ms, Cost_ref <fuel> fuel)Reference scale: fixed constants — too few measured <domain> / <fidelity> genes this season for a median -
Still an estimate. Two inputs of F(g), utility and robustness, are still placeholders, so every score is recorded as
estimatedand does not rank on the leaderboard. While that is so, the fitness threshold τ is paused (it is being recalibrated for the normalized [0, 1] range) and does not block a submission; V(g) ≥ 0.7 alone decides admission, and the output saysAdmission: PASSED (V(g) only). -
Measured runs are uploaded. With
--cloud, the measured runs (outcome, output-schema check, latency, fuel) go to the public run ledger even though the score itself is an estimate. Without--cloud, they stay on your machine. -
Re-submitting updates. Submitting the same gene again updates its existing Arena entry instead of adding a second one.
Example:
# Local Arena, compiled gene$ rotifer arena submit genesis-web-searchℹ Running pre-submission tests...✓ Pre-submission tests passedℹ Executing gene in WASM sandbox...ℹ Reference scale: fixed constants — too few measured search / Native genes this season for a median✓ Sandbox execution: 3/3 passed (avg 473.7ms)
✓ Gene 'genesis-web-search' submitted to Arena Domain: search Fidelity: Native F(g): 0.0037 (× 1.00 native discount) V(g): 1.0000 Admission: PASSED (V(g) only) Execution: Sandbox verified (3 runs) Recorded as: estimated
# Cloud Arena (requires login; also uploads the measured runs)$ rotifer arena submit my-search --cloudrotifer arena list
Section titled “rotifer arena list”View Arena rankings for all genes or a specific domain.
rotifer arena list [options]Options:
| Flag | Description |
|---|---|
-d, --domain <domain> | Filter by functional domain |
--cloud | Show Cloud Arena rankings |
Output columns:
- # — Rank within domain
- Name — Gene name
- Domain — Functional domain
- F(g) — Fitness score (0.0–1.0)
- V(g) — Safety score (0.0–1.0)
- Fidelity — Native / Wrapped / Hybrid
- Creator — Publisher (cloud only)
Example:
$ rotifer arena list ┌──────┬─────────────────────┬────────────┬────────┬────────┬──────────┐ │ # │ Name │ Domain │ F(g) │ V(g) │ Fidelity │ ├──────┼─────────────────────┼────────────┼────────┼────────┼──────────┤ │ 1 │ genesis-web-search │ search.web │ 0.9200 │ 0.9500 │ Native │ │ 2 │ my-search │ search.web │ 0.8234 │ 0.9100 │ Wrapped │ │ 3 │ genesis-search-lite │ search.web │ 0.7100 │ 0.8900 │ Native │ └──────┴─────────────────────┴────────────┴────────┴────────┴──────────┘
$ rotifer arena list --cloud -d search.web # Shows cloud rankings filtered by domainrotifer arena watch
Section titled “rotifer arena watch”Watch Arena rankings in real-time, observing rank changes as genes compete.
rotifer arena watch <domain> [options]Arguments:
| Argument | Required | Description |
|---|---|---|
domain | Yes | Domain to watch |
Options:
| Flag | Description |
|---|---|
--cloud | Watch Cloud Arena (polling-based) |
--interval <ms> | Polling interval in milliseconds (default: 3000) |
Example:
$ rotifer arena watch search.web Watching search.web rankings...
[14:32:01] Rank change: my-search ↑ #3 → #2 (F: 0.82 → 0.85) [14:32:04] New entry: fast-search entered at #4 [14:32:07] No changes
Press Ctrl+C to stoprotifer arena audit
Section titled “rotifer arena audit”Check every Cloud Arena score against the public invalidation criteria, and compare the result with what the leaderboard records.
rotifer arena audit [options]Options:
| Flag | Description |
|---|---|
--skip-artifacts | Skip the criterion that inspects published WASM. Nothing is downloaded; those rows are reported as unchecked, not clean. |
--concurrency <n> | Parallel artifact downloads (default: 6) |
What it checks, in this order. The first criterion that matches is the row’s reason; any others are listed with it.
| Criterion | A row is flagged when… |
|---|---|
test-data | it was submitted under the test domain |
no-published-artifact | the gene declares Native fidelity but has no published WASM |
async-express-artifact | the published WASM contains an async express() |
It also reports drift, where the criteria and the leaderboard disagree:
| Drift | Meaning |
|---|---|
missing | The criteria flag a row the board has not marked yet (expected until the invalidation job has run) |
unreproducible | The board marked a row that no criterion reproduces: a stale criterion, or a hand edit |
reason-mismatch | Both agree the row is invalid, but for different reasons |
Every input is public, so anyone can run the audit and get the same result. No login is needed. The criteria are documented in arena-invalidation-criteria.md.
It exits with code 1 only when the Arena cannot be read; flagged rows and drift do not change the exit code. Add --json for machine-readable output.
Example:
$ rotifer arena audit --skip-artifacts Arena invalidation audit ────────────────────────── Rows: 110 Flagged: 29 Clean: 45 Unchecked: 36
2 test-data 27 no-published-artifact 0 async-express-artifact
Flagged rows no-published-artifact <gene-name> genes.fidelity = Native, genes.wasm_size = 0, genes.wasm_path = null …