Gene Lifecycle Commands

rotifer init

Initialize a new Rotifer project with Genesis genes and Arena preview.

rotifer init [project-name]

Arguments:

Argument	Required	Description
project-name	No	Directory name (defaults to current directory)

What it creates:

my-project/
├── rotifer.json          # Project configuration
├── genes/                # Gene source directory
│   ├── genesis-web-search/
│   ├── genesis-web-search-lite/
│   ├── genesis-file-read/
│   ├── genesis-code-format/
│   └── genesis-l0-constraint/
└── .rotifer/
    └── playground.db     # Local Arena database

Example:

$ rotifer init my-project
✨ Project initialized at ./my-project

$ cd my-project && rotifer arena list
# Shows Genesis genes pre-ranked in the local Arena

---

rotifer scan

Scan source files for candidate functions that can be wrapped as genes.

rotifer scan [path]

Arguments:

Argument	Required	Description
path	No	Path to scan (defaults to genes/)

Supported languages: TypeScript (.ts, .js), Rust (.rs)

Detection patterns:

• export function name()
• export async function name()
• export const name =
• pub fn name() / pub async fn name()

Example:

$ rotifer scan src/tools/
  Scanning src/tools/search.ts...

  Found 3 candidate functions:
  ┌────┬──────────────┬──────────────────────┬──────┐
  │ #  │ Name         │ File                 │ Line │
  ├────┼──────────────┼──────────────────────┼──────┤
  │ 1  │ webSearch    │ src/tools/search.ts  │ 12   │
  │ 2  │ fileRead     │ src/tools/file.ts    │ 8    │
  │ 3  │ codeFormat   │ src/tools/format.ts  │ 5    │
  └────┴──────────────┴──────────────────────┴──────┘

---

rotifer wrap

Wrap a function as a Rotifer gene, generating a Phenotype and shim code.

rotifer wrap <name> --domain <domain> [options]

Arguments:

Argument	Required	Description
name	Yes	Gene name

Options:

Flag	Description
--domain <domain>	Functional domain (e.g., search.web, file.read)
--file <path>	Source file path

Generated files:

genes/<name>/
├── phenotype.json    # Gene metadata (domain, schemas, fidelity)
├── index.ts          # Express function wrapper
└── shim.ts           # Compatibility shim

Example:

$ rotifer wrap my-search --domain search.web
  ✓ Gene 'my-search' wrapped successfully

  Domain:   search.web
  Fidelity: Wrapped
  Version:  0.1.0

---

rotifer test

Execute L2 sandbox tests against a gene, validating schemas and behavior.

rotifer test <name> [options]

Arguments:

Argument	Required	Description
name	Yes	Gene name to test

Options:

Flag	Description
--verbose	Show detailed input/output for each test case

Test cases run automatically:

1. Schema validation — Phenotype conforms to Gene Standard
2. Express function — express() is exported and callable
3. Input/Output conformance — Output matches outputSchema
4. Error handling — Graceful failure on invalid input
5. Null check — express() returns non-null data

Example:

$ rotifer test my-search
  Running tests for 'my-search'...

  ✓ Phenotype schema is valid
  ✓ express() returned successfully
  ✓ Output conforms to outputSchema
  ✓ Error handling works correctly

  All 4 tests passed ✓
  Fitness: F(g) = 0.8234  V(g) = 0.9100

---

rotifer compile

Compile a gene to Rotifer IR (WASM with custom sections).

rotifer compile [name] [options]

Arguments:

Argument	Required	Description
name	No	Gene name (auto-detects if omitted)

Options:

Flag	Description
--lang <ts|wasm>	Force compilation mode
--wasm	Emit WASM output

Compilation pipeline:

TypeScript source
    ↓ esbuild (bundle + minify)
WASI-compatible JavaScript
    ↓ Javy (QuickJS → WASM)
Raw WASM module
    ↓ Rotifer IR Injector
gene.ir.wasm (with custom sections)

Custom sections injected:

• rotifer.version — Protocol version
• rotifer.phenotype — Serialized phenotype
• rotifer.constraints — L0 constraint metadata
• rotifer.metering — Fuel/resource limits

Example:

$ rotifer compile my-search
  Compiling 'my-search'...

  Pipeline: TypeScript → esbuild → Javy → IR
  ✓ Compiled successfully

  IR Hash:  a3f2b1...c4d5
  Size:     142.3 KB
  Sections: version, phenotype, constraints, metering

Output: genes/<name>/gene.ir.wasm