Architecture Deep-Dive

This guide provides a deep technical explanation of the Rotifer Protocol architecture, covering each layer of the URAA stack, the fitness model, Arena mechanics, Agent lifecycle, and the Binding architecture.

URAA Five-Layer Architecture

The Universal Rotifer Autonomous Architecture (URAA) separates concerns into five immutable layers. Each layer has a single responsibility, and layers communicate only through standardized interfaces.

┌─────────────────────────────────────────────────┐
│  L4: Collective Immunity — Species Memory       │
├─────────────────────────────────────────────────┤
│  L3: Competition & Exchange — Selection         │
├─────────────────────────────────────────────────┤
│  L2: Calibration — Immune System                │
├─────────────────────────────────────────────────┤
│  L1: Synthesis — Gene Expression                │
├─────────────────────────────────────────────────┤
│  L0: Kernel — Immutable Trust Anchor            │
└─────────────────────────────────────────────────┘

L0: Kernel (Constraint Layer)

The root of trust. L0 enforces immutable constraints that no higher layer can override.

• Constraint enforcement: Every gene execution is gated by L0 checks (permissions, resource limits, ethical boundaries)
• State anchoring: Agent state is compressed to a fixed-size digest and persisted tamper-proof
• Permission isolation: Genes run in isolated permission domains — no cross-gene state access

In the Playground, L0 is implemented as the WASM sandbox with fuel metering and memory caps.

L1: Synthesis (Execution Layer)

The “ribosome” — transforms raw inputs into standardized gene fragments and executes them.

• WASM Sandbox: wasmtime engine with configurable fuel (instruction budget), memory limits, and epoch interruption
• IR Compiler: Genes compile to Rotifer IR (WASM + custom sections: rotifer.version, rotifer.phenotype, rotifer.constraints, rotifer.metering)
• Dual execution modes: Direct (express export) and WASI (_start entry point)

L2: Calibration (Testing Layer)

Multi-stage validation inspired by thymic selection:

1. Static Analysis: Schema validation, export checks, prohibited instruction detection
2. Sandbox Simulation: rotifer test runs genes with sample inputs in an isolated environment
3. Controlled Trial: Gradual rollout to a subset of agents (future)

L3: Competition & Exchange (Evolution Layer)

Two mechanisms drive evolution:

• Arena: Same-domain genes compete on fitness F(g). Rankings are maintained locally and on the cloud. Genes are selected automatically based on fitness scores.
• Horizontal Logic Transfer (HLT): High-fitness gene metadata propagates via P2P. Agents pull genes based on capability gaps. (Foundation in v0.5, full implementation in v0.6+)

L4: Collective Immunity (Emergence Layer)

Network-wide defense and pattern detection:

• Malicious gene fingerprints are broadcast across the network
• Defense strategies are shared between agents
• Temporal decay ensures stale threat data expires
• Consensus-verified write operations prevent false positives

Fitness Model F(g)

Every gene has a measurable fitness score. The fitness function combines multiple metrics:

F(g) = w₁·success_rate + w₂·latency_score + w₃·resource_efficiency + w₄·safety_score

Where:
  success_rate        = successful_calls / total_calls
  latency_score       = 1 - (avg_latency / max_acceptable_latency)
  resource_efficiency = 1 - (fuel_consumed / fuel_budget)
  safety_score        = V(g) from L0 constraint checks

Admission Gate

Genes must pass a minimum fitness threshold before entering the Arena:

• F(g) >= 0.3 for Wrapped fidelity genes
• F(g) >= 0.5 for Native fidelity genes

Deterministic Rankings

In the Playground, fitness is computed deterministically from the gene’s content hash, ensuring consistent rankings without runtime execution.

Safety Score V(g)

The safety score evaluates a gene’s compliance with L0 constraints:

V(g) = constraint_compliance_rate × permission_score × resource_score

Where:
  constraint_compliance_rate = passed_checks / total_checks
  permission_score           = 1.0 if within declared permissions, penalized otherwise
  resource_score             = 1.0 if within limits, scaled by overage otherwise

Reputation System R(g) — v0.5

Reputation adds a time-decaying trust signal beyond instantaneous fitness:

R(g) = α·Arena_Score + β·Usage_Score + γ·Stability_Score

Where:
  α = 0.5, β = 0.3, γ = 0.2
  Arena_Score    = F(g) history, weighted by recency
  Usage_Score    = log(downloads + 1) / log(1000), capped at 1.0
  Stability_Score = total_calls / 100, capped at 1.0

Time-based decay prevents reputation stagnation:

R(g, t) = R(g, t-1) × (1 - 0.05)    // 5% decay per month, floor at 0.01

Developer Reputation:

R(d) = avg(R(g_i)) + community_bonus    // bonus = min(arena_wins × 0.02, 0.2)

Arena Mechanics

Selection Pressure

The Arena operates on epochs. Within each epoch:

1. Genes are submitted via rotifer arena submit
2. Fitness F(g) is computed (or estimated from content hash in Playground mode)
3. Genes are ranked within their domain
4. Top-ranked genes are selected for agent expression
5. Diversity mechanisms prevent monoculture (epoch reset when diversity drops below threshold)

Domain Isolation

Genes compete only within their declared domain (e.g., search.web, code.format). Cross-domain genes do not compete against each other.

Cloud Arena

The Cloud Arena extends local competition across developers:

• rotifer arena submit --cloud uploads fitness results to Supabase
• Server-side get_arena_rankings() produces global rankings
• Reputation scores (R(g)) are displayed alongside F(g) and V(g)

Agent Lifecycle

Agents progress through four states:

Created → Active → Suspended → Terminated
           ↕
        Suspended

Gene Selection

When an Agent runs, it selects genes from its genome and executes them using the composition algebra:

1. Manual selection: --genes gene1,gene2,gene3
2. Auto-selection: --domain search.web --top 3 picks the top-ranked genes from the Arena
3. Pipeline execution: Genes are composed via Seq (sequential) by default

Binding Architecture

The protocol is binding-agnostic. The same gene IR runs on any binding:

┌───────────────────┐
│   Gene IR (WASM)  │  ← Write once
├───────────────────┤
│   RotiferBinding  │  ← Swap binding
├─────┬──────┬──────┤
│Local│Cloud │Web3  │  ← Runtime target
└─────┴──────┴──────┘

Local Binding (v0.1+)

• SQLite storage, wasmtime sandbox, local Arena
• Self-contained, no network dependency

Cloud Binding (v0.4+)

• Supabase backend (PostgreSQL + Storage + Auth + Realtime)
• GitHub OAuth (PKCE flow)
• REST API for publish/search/install/arena
• Endpoint-agnostic: configurable via ~/.rotifer/cloud.json or --endpoint

P2P Binding (v0.5 Foundation)

• Cloud-first hybrid model: Cloud Registry as primary source, P2P as supplement
• Gene metadata announcement via GossipSub protocol
• Gene discovery via Kademlia DHT
• Full binary transfer deferred to v0.6 (uses Cloud CDN for now)

Web3 Binding (Future)

• Smart contract-based constraint enforcement
• On-chain reputation and fitness records
• Token-incentivized gene marketplace

Data Flow Example

A complete gene lifecycle:

Developer writes gene
    → rotifer scan (discover candidates)
    → rotifer wrap (generate Phenotype)
    → rotifer test (L2 sandbox validation)
    → rotifer compile (WASM + IR custom sections)
    → rotifer arena submit (local ranking)
    → rotifer publish (Cloud Registry)
    → rotifer arena submit --cloud (global ranking)
    → Other developers: rotifer search + rotifer install
    → Reputation accumulates: R(g) grows with usage
    → P2P network announces gene metadata