ContextQMD
Back to Ruflo

ADR-0001: ruflo-arena plugin contract

plugins/ruflo-arena/docs/adrs/0001-arena-contract.md

3.10.393.2 KB
Original Source

ADR-0001: ruflo-arena plugin contract

Status: Proposed Date: 2026-06-07 Plugin: ruflo-arena

Context

ruflo-arena implements the first executable slice of the competitive-ruliology initiative (Ruflo ADR-147 competitive arena/tournament modes, ADR-148 co-evolution, ADR-150 visualization split), following Stephen Wolfram's Games Between Programs: The Ruliology of Competition. This ADR pins the plugin's public contract so downstream surfaces (commands, dashboards, the RuVector data layer) can depend on stable shapes.

Decision

Tool surface (./mcp-tools)

ToolPurpose
arena/runone deterministic match between two named strategies
tournament/runround-robin → competitive array (mean-payoff matrix) + ranking
evolve/runhill-climb an FSM vs the field; returns program + fitness curve
coevolve/runmutual co-evolution (arms race) trace
run/get, run/listfetch/list persisted run records

Every tool returns the Ruflo envelope { success: boolean; result?: T; error?: { message } } and validates input with Zod at the boundary. Numeric inputs are coerced (MCP/CLI friendliness).

Core types (. / ./engine)

  • GameSpec — payoff matrix over an action set (prisoners-dilemma, match-or-not).
  • Strategy — FsmStrategy (deterministic Moore machine: output on state, transition on opponent action) or FnStrategy (closure, e.g. random). This is "strategy as program".
  • MatchResult, TournamentResult, EvolutionResult, CoevolutionResult, RunRecord.

Persistence contract

  • TS code persists full artifacts via RunStore (FileRunStore → .ruflo/arena/<runId>.json; InMemoryRunStore for tests). This is the local stand-in for RuVector ADR-197.
  • AgentDB persistence is performed at the command/agent layer (Ruflo convention): each tool result carries an agentdb payload { namespace:"arena", key, value, tags } for mcp__claude-flow__memory_store, making runs semantically searchable.

Determinism

All runs are reproducible under seed. The RunRecord captures seed and the full artifact for bit-for-bit replay — Wolfram's requirement that competitions be re-runnable.

Consequences

  • Positive: stable, typed contract; zero runtime deps beyond Zod; engine is pure and unit-tested; no Ruflo-core changes; clean seam for the RuVector data layer and the dashboard.
  • Negative / Costs: v1 only ships simple-program + stochastic strategies; LLM strategies (ADR-151), sandboxing (ADR-153), and the dashboard UI (ADR-149) are out of scope here.
  • Neutral / Risks: the AgentDB summary schema (agentdb.value) is unversioned in v1; formalize with the RuVector integration contract (ADR-152 ↔ ADR-200) before cross-repo use.

References