Skip to content

Arena Commands

The Arena is where genes compete. Same-domain genes fight head-to-head on fitness metrics. The fittest survive.

Submit a gene to the Arena for competitive ranking.

Terminal window
rotifer arena submit <gene-name> [options]

Arguments:

ArgumentRequiredDescription
gene-nameYesGene name to submit

Options:

FlagDescription
--cloudSubmit to Cloud Arena (requires login)
--skip-testSkip 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:

  1. Run the pre-submission tests (unless --skip-test).
  2. If the gene is compiled (gene.ir.wasm exists) 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 says Not executed.
  3. Compute fitness F(g) and safety V(g), and apply the fidelity discount.
  4. 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.

  • 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 estimated and 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 says Admission: 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:

Terminal window
# 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 --cloud

View Arena rankings for all genes or a specific domain.

Terminal window
rotifer arena list [options]

Options:

FlagDescription
-d, --domain <domain>Filter by functional domain
--cloudShow 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:

Terminal window
$ 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 domain

Watch Arena rankings in real-time, observing rank changes as genes compete.

Terminal window
rotifer arena watch <domain> [options]

Arguments:

ArgumentRequiredDescription
domainYesDomain to watch

Options:

FlagDescription
--cloudWatch Cloud Arena (polling-based)
--interval <ms>Polling interval in milliseconds (default: 3000)

Example:

Terminal window
$ 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 stop

Check every Cloud Arena score against the public invalidation criteria, and compare the result with what the leaderboard records.

Terminal window
rotifer arena audit [options]

Options:

FlagDescription
--skip-artifactsSkip 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.

CriterionA row is flagged when…
test-datait was submitted under the test domain
no-published-artifactthe gene declares Native fidelity but has no published WASM
async-express-artifactthe published WASM contains an async express()

It also reports drift, where the criteria and the leaderboard disagree:

DriftMeaning
missingThe criteria flag a row the board has not marked yet (expected until the invalidation job has run)
unreproducibleThe board marked a row that no criterion reproduces: a stale criterion, or a hand edit
reason-mismatchBoth 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:

Terminal window
$ 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
…