# Rotifer Protocol — Full Specification Summary

> Open-source evolution framework for AI agents.
> This is the detailed version of llms.txt for Agents that need deep protocol understanding.

## 1. Problem Statement

AI agents face three systemic challenges:
1. Static logic fragility — capabilities frozen at deployment
2. Super-linear maintenance cost — O(n × m) for n agents × m environment variables
3. Intelligence silos — individual experience cannot efficiently propagate

Core contradiction: we use static, centralized methods to operate dynamic, distributed systems.

## 2. Design Principles

| Axiom | Statement |
|-------|-----------|
| Gene-Centric | The Gene (not the Agent) is the unit of selection |
| Environment-Agnostic | Protocol defines abstract interfaces; bindings handle specifics |
| Fail-Safe Default | Unknown states are treated as potentially harmful |

## 3. Gene Standard

A Gene is the atomic unit of Agent capability.

### Gene Metadata (Phenotype)
- `name`: Unique identifier (e.g., "search.web.google-v2")
- `domain`: Capability domain (e.g., "search.web")
- `fidelity`: Wrapped | Hybrid | Native | Unknown
  - Wrapped: Thin envelope around an external API call
  - Hybrid: Mix of native WASM logic and external calls
  - Native: Entire logic is pure WASM — fully sandboxed
  - Unknown: Forward-compatibility fallback
- `version`: Semver string
- `inputSchema` / `outputSchema`: JSON Schema (deterministic subset)
- `securityRequirements`: Declared permissions
- `transparency` / `visibility`: Audit and inspection level

### Gene Lifecycle
1. Created by creator or synthesized by Agent
2. L2 Calibration: static analysis → sandbox simulation → controlled live trial
3. Arena entry (if F(g) >= 0.3 and V(g) >= 0.7)
4. Competition on F(g); ranking determines expression priority
5. Runtime data feeds back to update F(g)

## 4. Fitness Model F(g)

The multiplicative fitness function:

```
F(g) = [S_r · ln(1 + C_util) · (1 + R_rob)] / [L · Resource_Cost]
```

Where:
- S_r (Success Rate): fraction of successful executions
- C_util (Coverage Utilization): breadth of capability exercised
- R_rob (Robustness): resilience to edge cases and failures
- L (Latency Score): normalized response time
- Resource_Cost: computational resource consumption

F(g) is computed purely from objective runtime metrics. No voting, no human preference.

### Safety Score V(g)
- Separate from F(g)
- Hard gate: V(g) >= 0.7 required for Arena entry
- Derived from L2 calibration results

## 5. Architecture: URAA (5 Layers)

### L0 — Kernel
Immutable trust anchor. Enforces security constraints that no higher layer can override. The only layer that does not participate in evolution.

### L1 — Synthesis
The protocol's ribosome. Rotifer IR compiles to WASM for sandboxed execution with fuel metering, memory caps, and deterministic resource accounting.

### L2 — Calibration
Three-stage gene validation:
1. Static analysis
2. Sandbox simulation
3. Controlled live trial
Emulates biological thymic selection.

### L3 — Competition & Exchange
Game-theoretic Arena where Genes compete on F(g). High-fitness Gene metadata propagates via P2P; Agents pull full Genes based on capability gaps.

### L4 — Collective Immunity
Records security incidents, malicious Gene fingerprints, and defense strategies across the network. Threat broadcasting with temporal decay and consensus-verified writes.

## 6. Composition Algebra

Genes compose into Genomes using four operators:
- **Seq(g1, g2, ...)**: Sequential execution
- **Par(g1, g2, ...)**: Parallel execution
- **Cond(predicate, g_true, g_false)**: Conditional branching
- **Try(g_primary, g_fallback)**: Error recovery

## 7. Intermediate Representation (IR)

Environment-agnostic IR enables cross-binding portability:
- Compiles to WASM for sandboxed execution
- Supports Cloud, Web3, Edge, TEE environments
- Uses JSON Schema deterministic subset for input/output schemas
- DataFlowGraph for dependency resolution

## 8. Agent Access Channels

### MCP Server (Operation Layer)
Full Gene lifecycle: search, run, compare. F(g) data returned with every execution.

```json
{
  "mcpServers": {
    "rotifer": {
      "command": "npx",
      "args": ["@rotifer/mcp-server"]
    }
  }
}
```

Tools: search_genes, run_gene, compare_genes

### OpenClaw Skill (Discovery Layer)
Thin MCP wrapper available in OpenClaw marketplace. One-click install for OpenClaw users.

### WebMCP (Perception Layer)
W3C draft standard. rotifer.dev and rotifer.ai register WebMCP tools for zero-config browser Agent access.
- Declarative: `<form toolname="search_docs">` on rotifer.dev
- Imperative: `navigator.modelContext.registerTool()` for get_mcp_config

### CLI (Creator)
```
npx -y @rotifer/playground@latest init my-agent
cd my-agent
npx -y @rotifer/playground@latest hello --template quality-advisor
rotifer wrap <gene-name>
rotifer arena submit <gene-name>
rotifer arena list
```

## 9. Links

- Documentation: https://rotifer.dev/docs
- Gene Marketplace: https://rotifer.ai
- Protocol Specification: https://github.com/rotifer-protocol/rotifer-spec
- IR Specification: https://github.com/rotifer-protocol/rotifer-spec (rotifer-ir-specification)
- Playground CLI: https://github.com/rotifer-protocol/rotifer-playground
- Papers: https://github.com/rotifer-protocol/rotifer-papers