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

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:

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.
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.
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.
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.