# Simulation System ("The Arena")

**Last Updated:** 2026-01-31
**Confidence:** High
**Status:** Phase 1 Complete (Spine validation)

## Summary

The Simulation is an Agent-Based Modeling (ABM) environment that validates StemeDB under emergent, adversarial, and evolutionary pressure. It simulates a society of AI agents with conflicting goals living within the knowledge graph.

**Key Facts:**
- Codename: "The Arena"
- Purpose: Integration testing via societal stress tests, not unit tests
- Architecture: `stemedb-sim` binary orchestrating agent swarms via tokio
- Agents communicate **only** through StemeDB reads/writes

**File Pointers:**
- Implementation: `crates/stemedb-sim/src/main.rs`
- Vision document: `/simulation-vision.md`
- Incremental roadmap: `/arena-roadmap.md`

## Agent Personas

| Persona | Goal | Behavior |
|---------|------|----------|
| Scientist | Converge on truth | High-confidence assertions, cites sources |
| Troll | Sow chaos | Low-confidence contradictions, frequent forks |
| Believer | Amplify consensus | Trusts high-reputation agents |
| Skeptic | Find variance | Reduces confidence of unverified claims |
| Historian | Preserve context | Resurrects dormant truths with new evidence |

## The Gameplay Loop

1. **Assertion**: Agent reads ground truth, creates assertion
2. **Fork**: Adversarial agent forks reality with contradiction
3. **Lens Resolution**: Query agent applies Lens (e.g., Consensus)
4. **Reputation Update**: TrustRank adjusts agent reputations
5. **Decay**: Unverified assertions fade via Dormancy Protocol

## Success Criteria

- Truth survives: High-reputation assertions outlive spam
- Lenses work: Consensus lens filters Troll noise
- Performance: 1000 concurrent agents without locking
- Emergence: Trust clusters form without hardcoded rules

## Metrics

Tracked via Prometheus/Grafana:
- `global_truth_convergence` - Entropy of the graph
- `agent_reputation_distribution` - Reputation spread
- `fork_depth_max` - Deepest branch depth

## Current Status

The simulator currently validates **Phase 1: The Spine** (WAL + Ingestor + KV Store). It proves the write path works end-to-end with signature verification.

**What's implemented:**
- 3 agents (2 Scientists, 1 Troll)
- 10 ticks of assertion creation
- Ed25519 signature verification
- WAL → Ingestor → KV Store pipeline

**What's NOT implemented yet:**
- Query path (uses direct KV access, not QueryEngine)
- Voting and consensus
- TrustRank reputation
- Concurrent agents
- Agent persona differentiation

## Roadmap

See [arena-roadmap.md](/arena-roadmap.md) for the incremental path from current state to full ABM environment.

## Related Topics

- [TrustRank](./trust-rank.md) - Reputation algorithm
- [Branching](./branching.md) - Fork mechanics
- [Lens System](../services/lens.md) - Query resolution