---
type: reference
title: "Pokémon TCG — Local Platform Implementation Specification"
description: "Execution contract for the normalized local platform: schema families, services, dashboard surfaces, deterministic workflows and acceptance gates, separated from the partially implemented runtime."
tags: [pokemon-tcg, implementation, specification, sqlite, dashboard, replay, idempotency, acceptance]
timestamp: "2026-08-15T17:34:00-03:00"
---

# Pokémon TCG — Local Platform Implementation Specification

## Role and provenance

`docs/implementation-spec.md` is the execution-oriented companion to the
project's local-overhaul task. It is a normative design contract for a future
implementation, not a delivery report. The document was introduced in
`05c4435` on 2026-07-27, alongside the detailed architectural and schema
specifications. The live project endpoint is later, at `20d7d0d` on
`develop`; the current code status therefore takes precedence over this
contract when the two differ.

The specification explicitly excludes the future blockchain or HashMath
compute ledger, Proof-of-Work tournaments, decentralized matchmaking, on-chain
identity and an always-on home-lab service. Stable domain identities may remain
compatible with those ideas, but they are not part of the local acceptance
scope.

## Target topology

```mermaid
flowchart LR
    C[Catalog and identity] --> S[Submission service]
    S --> T[Tournament and match service]
    T --> R[Replay parser and normalized state]
    R --> A[Rating and evidence service]
    X[Experiment and training records] --> A
    P[Daily source-scoped pipeline] --> C
    P --> R
    D[Streamlit dashboard and CLI] --> C
    D --> S
    D --> T
    D --> R
    D --> X
    D --> A
```

The intended rule is that dashboard and command-line surfaces call typed
services. They do not write SQL directly or create a parallel schema that the
application does not use.

## Implementation order versus live state

The source contract proposes nine runnable phases. The reconciliation below
keeps the order while replacing vague completion language with the live
boundary observed at `20d7d0d`:

| Phase in the specification | Live status | Evidence boundary |
|---|---|---|
| Replace `results_db`, seed references and enforce FKs | Partial/current schema v2 | `rl/results_db.py` has a populated SQLite schema, source tables and receipts, but the full reference-table and target-v2 contract is not present; the current database audit still reports FK violations. |
| Catalog, model, deck and submission services | Partial | Cards, decks, submissions and deck fingerprints exist; full model-revision, immutable-deck-revision and lifecycle-service semantics remain incomplete. |
| Tournament, match and rating persistence | Partial/current | Tournament and local match rows, card/deck Elo and idempotent recording exist; target policies, epochs, submission/model ratings and append-only rating events are not complete. |
| Replay parser and reconstruction adapter | Partial | Steps, options, events, snapshots and field Pokémon are stored; complete zones, movements, serial effects and verified external visualizer reconstruction remain open. |
| Experiment, training and anamnese services | Not implemented as the target family | Training artifacts and experiment narratives exist, but the normalized experiment observation model is still a design requirement. |
| Arena integration and daily pipeline | Partial/current | A synchronous local runner and remote intake exist; the target source-scoped run identity and full service boundary are not complete. |
| Dashboard queries and views | Partial | Streamlit exposes real cards, decks, arena, replay and configuration surfaces; the full submission, experiment, source-filter and failure-state contract is larger. |
| Official visualizer adapter | Not verified as complete | The official visualizer path is documented, but the route, method, payload and both-player behavior still require fixture-backed verification. |
| Full acceptance suite and removal of legacy readers/writers | Not passed | The specification's completion definition is not satisfied at the current project endpoint. |

This table is deliberately conservative. A source file, generated test or
handoff milestone can establish that a phase was planned or scaffolded without
establishing that its acceptance gate passed.

## Invariants the target is designed to preserve

### Identity and revision

- Models have stable identities and immutable revisions.
- Deck families can be renamed, while deck compositions are immutable
  revisions with content digests.
- A submission is a concrete model revision plus deck revision, with local and
  remote lineage kept separate.
- External identifiers carry a source/provider and a source-scoped uniqueness
  constraint.

### Evidence and storage

- SQLite is the local phase's storage boundary.
- Every connection enables `PRAGMA foreign_keys = ON` immediately.
- Immutable artifacts carry a digest; historical evidence is append-only.
- Replays are parsed into typed relations. JSON is an ingestion source, not a
  database escape hatch; serialized action arrays, opaque blobs and HTML are
  excluded from the target model.
- Every operation is repeatable through an idempotency key or immutable source
  identity, with an `operation_receipt` recording the applied result.

### Rating and source separation

The target separates submission, model, deck and card ratings. A deck rating is
an outcome for a composition, not an average of its cards. Local and remote
observations are separate source pools, and a remote send creates a new rating
lineage at the declared initial value rather than reusing local state.

### Temporal research records

Experiments are first-class containers and do not imply that a training run
exists. Training configurations, checkpoint/data digests, validation policy,
deck set, tournament protocol and post-run observations are recorded as
separate facts. Anamnese is append-only: a later interpretation does not
rewrite what was believed or observed earlier.

## Deterministic workflows

The specification makes four workflows explicit because they are where silent
state corruption would otherwise hide:

1. **Local match:** resolve persistent submissions, verify eligibility and
   configuration, create a seeded matchup, run the environment, persist the
   replay atomically, apply each rating policy once and return a receipt.
2. **Replay retry:** digest the source, look up
   `(source_locator, digest, parser_version)`, return the existing result when
   present, or insert the import and all child rows in one transaction.
3. **Local rating reset:** create a new epoch with a reason, initialize the
   requested local submission at 600 in that epoch, preserve previous events
   and return the same epoch for a repeated idempotency key.
4. **Remote send:** register the external mapping, create a remote lineage at
   600 and never reuse local submission-rating state.

These are target semantics. Their presence in the document does not prove
that every current command implements them.

## Acceptance gates

The target is only complete when the following evidence exists together:

- an empty database initializes with enforced FKs, reference seeds and tested
  constraints;
- every service command has an idempotency retry test;
- replay fixtures are lossless and reconstructible without source JSON;
- the official visualizer contract is tested for both players;
- ratings cannot double-apply and local/remote filters are enforced in SQL and
  the UI;
- dashboard views cover catalog, submissions, arena, replays, experiments and
  configuration, including empty, stale, invalid and failure states;
- the daily pipeline is re-runnable;
- legacy readers/writers and `replay_html` are removed;
- the implementation, task contract, tests and Wikifita agree on status.

The current [[pokemon_tcg_local_platform_status]] page is the live status
authority for this list. The current database and ETL warnings in
[[pokemon_tcg_aug14_data_etl_database_audit]] remain unresolved evidence, not
reasons to silently downgrade or rebuild the corpus.

## Migration boundary

The specification permits a rebuild only behind an evidence-preserving
boundary: export a read-only inventory outside the canonical database, retain
the source snapshot, backfill only unambiguous fields and record every skipped
field with its reason. It explicitly rejects using a JSON escape hatch for
ambiguous agent strings, serialized replay fields or data that cannot be
losslessly normalized. This is consistent with the zero-trust ETL position in
[[pokemon_tcg_data_oracle_etl]] and the current integrity ledger in
[[pokemon_tcg_sqlite_schema_current]].

## Cross-references

- [[pokemon_tcg_local_platform_design]] — current synchronous boundary and
  future application seam.
- [[pokemon_tcg_schema_evolution]] — current physical debt versus relational
  v2 design.
- [[pokemon_tcg_replay_data_model]] — replay relations and visualizer boundary.
- [[pokemon_tcg_experiments_and_anamnesis]] — temporal experiment model.
- [[pokemon_tcg_submissions_and_elo]] — identity and rating lineage.
- [[pokemon_tcg_current_state_reconciliation]] — project-commit reconciliation.
- [[pokemon_tcg_repository_timeline]] — introduction and subsequent evolution.

## Source anchors

- `docs/implementation-spec.md`, introduced at project commit `05c4435`.
- `docs/local-overhaul-design.md`, introduced in the same architectural wave.
- `rl/results_db.py`, `scripts/tournament.py` and `scripts/dashboard.py` at
  project commit `20d7d0d` for the current implementation boundary.