Pokémon TCG — Future Arena Architecture

Status and provenance

docs/arena-future-architecture.md was introduced in the architectural wave at project commit 05c4435 on 2026-07-27. It is a future-boundary document, not evidence that distributed workers, a network protocol or an always-on service exists. The current local product remains synchronous and is described in pokemon_tcg_local_platform_status.

The purpose of the design is to keep the domain independent from one process or computer without prematurely turning the research platform into a distributed systems project.

Current synchronous boundary

flowchart LR
    UI[Streamlit dashboard] --> C[Local arena controller]
    C --> S[Submission selector]
    S --> R[Local match runner]
    R --> E[Game engine]
    R --> P[Replay persistence]
    P --> DB[(Normalized SQLite)]
    C --> RT[Rating service]
    RT --> DB
    DB --> Q[Dashboard queries]
    Q --> UI

The controller owns one local execution at a time. A match, its normalized replay rows and its rating evidence should commit atomically. This boundary does not promise concurrent SQLite writers, network services, queue consensus, or a hosted competition control plane.

Future application seam

flowchart TB
    D[Dashboard or CLI] --> API[Arena application boundary]
    API --> O[Orchestrator]
    O --> Q[Work queue]
    Q --> W1[Worker: local machine]
    Q --> W2[Worker: future home lab]
    W1 --> E[Engine adapter]
    W2 --> E
    E --> RP[Replay persistence]
    E --> RR[Rating updates]
    RP --> DB[(Shared or replicated relational store)]
    RR --> DB
    O --> SNAP[Run and rating snapshots]
    DB --> REPORT[Research reports]

The seam is an application boundary, not a mandate to introduce a network service now. A future worker receives a serializable work claim containing submission IDs, deck IDs, configuration ID and seed. It executes the engine and returns structured result rows. It does not own domain rules, invent schema decisions or silently alter rating policy.

Patterns worth preserving

The source design draws on three analogies, each with a limited scope:

• Red Team Arena: a controller owns orchestration; agent implementations use stable interfaces; ratings are explicit pools and snapshots; experiments produce structured results; dashboard queries are separate from execution.
• Co-Scientist: experiments have lifecycle and durable provenance; configuration is frozen per execution; long work can pause and resume; a report is derived from structured records.
• Bitcoin Core: the useful analogy is disciplined state transition, explicit inputs, atomic persistence, recovery and inspectable records. It is not a reason to import peer-to-peer consensus or cryptographic machinery.

These analogies are design rationale, not implementation evidence.

Deliberate non-goals

The future page explicitly keeps the following out of the synchronous v2 baseline:

• distributed workers and a network protocol;
• an always-on daemon;
• concurrent SQLite writers;
• a required queue table;
• consensus or peer-to-peer replication.

This boundary prevents throughput pressure from erasing the evidence and reproducibility requirements of the local research loop.

Schema implications

The relational model should include stable concepts that remain meaningful if a worker layer is added later:

Record	Minimum meaning
arena_runs	execution identity, configuration, lifecycle and source
arena_run_submissions	submissions selected for the run
matches	individual game evidence linked to the run
rating_snapshots	point-in-time ratings associated with the run
immutable configuration	frozen parameters and seed for the execution
result status/failure metadata	recoverable outcome rather than an implied success

These are ordinary relational records in the synchronous version. A future queue can claim an arena_run or match partition without changing the meaning of the evidence.

Research reporting contract

Every run should eventually answer, from persisted records:

1. Which model artifact and deck revision participated?
2. Which opponent and deck revision were used?
3. Which tournament configuration and random seed applied?
4. Which source pool produced the rating evidence?
5. Which replay rows and observations support the result?
6. What changed from the previous experiment or submission?

Throughput and always-on execution are secondary. A service future is only a successful extension if these six answers remain inspectable.

Cross-references

• pokemon_tcg_local_platform_design — current/future platform split.
• pokemon_tcg_implementation_specification — target services and gates.
• pokemon_tcg_schema_evolution — relational v2 evidence graph.
• pokemon_tcg_tournament_system — current tournament runner and cohorts.
• pokemon_tcg_experiments_and_anamnesis — lifecycle and temporal records.
• pokemon_tcg_aug14_architecture_and_handoff_audit — blueprint status at the August 14 handoff.

Source anchor

docs/arena-future-architecture.md, introduced at project commit 05c4435. The current absence of a distributed worker runtime is verified against the project source tree at 20d7d0d.