Pokémon Center: add Bluetooth Link Counter trading and in-game-currency sales between TrainerOS devices #45

Product decision

Add a Link Counter inside Pokémon Center for nearby TrainerOS-to-TrainerOS Pokémon exchange over Bluetooth.

Primary use cases:

• trade one Pokémon for another;
• transfer a Pokémon when the destination game/provider supports import;
• optional sale for in-game currency only when both exact providers safely support Pokémon transfer and currency mutation.

This is intentionally local/offline and should feel like a modern TrainerOS equivalent of a link cable.

Transport

Use Bluetooth as the nearby transport.

Requirements:

• discover compatible nearby TrainerOS peers;
• explicit user selection/pairing/acceptance;
• no internet account required;
• exchange only compact semantic transaction data, not entire saves;
• authenticate the live session enough to prevent accidental cross-session commits;
• clear disconnect/cancel states.

Do not couple Pokémon serialization to Bluetooth transport. The transport moves a semantic transaction envelope; game providers own save interpretation.

Semantic exchange

Never copy arbitrary binary save slices from one device into another.

Flow conceptually:

source exact save provider
→ verified semantic PokemonRecord/export package
→ TrainerOS Link protocol
→ destination provider validation/import preparation
→ destination exact save

The exported package must preserve every required field needed for legitimate identity/round-trip compatibility, including original Trainer identity/provenance where supported.

Do not create a fresh clone merely from species/level/moves.

Compatibility negotiation

Before either save changes, both peers exchange capabilities and validate the specific selected Pokémon.

The destination must explicitly answer whether it can import the record without unsafe loss/corruption.

Possible outcomes:

• compatible trade allowed;
• transfer allowed one way only;
• held item/move/form/data unsupported → reject with clear reason;
• exact source/destination game combination not validated → reject;
• currency sale unsupported → trade may still be available.

Do not invent broad Gen III ↔ Gen III compatibility. Use the exact per-build matrix from #42.

Two-device transaction protocol

A trade must not duplicate or lose Pokémon if Bluetooth drops.

Use a two-phase/transactional protocol with a unique transaction ID, conceptually:

1. both peers resolve and stable-read their exact saves;
2. both create verified protection backups;
3. both validate selected outgoing/incoming records;
4. both prepare candidate saves without committing;
5. both verify checksums/semantic deltas;
6. peers exchange READY(transactionId, sourceRevision, candidateDigest);
7. commit only when both sides are ready;
8. both read back and verify committed state;
9. exchange final COMMITTED receipts;
10. if commit cannot safely complete, recover/rollback according to a documented deterministic protocol.

The protocol must explicitly handle a disconnect during prepare, between commits, and after one peer committed but before receipt.

Do not call a trade successful merely because one side wrote successfully.

Trade UI

Inside Center → Link Counter:

Find nearby Trainers
→ choose TrainerOS peer
→ Trade / Sell
→ choose Pokémon from Party/Storage
→ inspect both sides
→ both confirm
→ transaction progress
→ success / safe recovery state

Both users must see exactly what leaves and arrives before confirmation.

Sale semantics

Sell means exchange a Pokémon for the destination/source game's in-game money, not real money.

Only expose it when providers support:

• exact Pokémon export/import/remove;
• exact money read/write;
• safe bounded arithmetic;
• agreed deterministic price/entered price policy.

The buyer must see price and resulting balance before confirmation. The seller's target save/currency credit must be equally transaction-safe.

If cross-game currency semantics are awkward or cannot be represented safely, disable sale for that pairing rather than approximating it.

Ownership / origin

Preserve original Trainer/game-origin data whenever the game format defines it.

TrainerOS may add its own private activity metadata such as:

Transferred from Trainer X · FireRed → Emerald

but must not rewrite game-native origin fields merely to make the record look local.

Trade evolutions

Do not implement generic trade evolution in the first transport increment.

A later provider-specific capability may apply trade-evolution rules only after the exact game's rules, held-item consumption and resulting record mutation are validated.

Same-device extension

The transaction service may later support transfer between two local Trainer profiles/saves without Bluetooth, but do not let that complicate the first two-device Link Counter implementation.

Privacy

Broadcast/discovery should reveal minimal information before explicit connection.

Do not expose save paths, raw account tokens, full Trainer histories or unnecessary Pokémon collection data to nearby devices.

Tests

Cover at minimum:

• discover/connect/cancel;
• incompatible provider pair rejects before mutation;
• successful trade with two fake devices;
• source revision changes during negotiation;
• disconnect before READY;
• disconnect after READY;
• simulated one-sided commit failure and deterministic recovery;
• protection-backup failure;
• duplicate transaction/replay does not duplicate Pokémon;
• original Trainer/provenance survives supported transfer;
• sale insufficient funds/overflow/cancel;
• no real-money semantics;
• physical two-Flip/TrainerOS-device validation when a second supported device is available.

Acceptance

• Two nearby TrainerOS devices can negotiate a Pokémon exchange over Bluetooth without launching the games.
• Save providers exchange semantic Pokémon records rather than binary save chunks.
• No unsupported game pairing is assumed compatible.
• Bluetooth failure cannot silently duplicate or destroy Pokémon.
• Optional sale uses only verified in-game currency and the same two-device transaction guarantees.