Validation Checklist

Validation Checklist

Before opening Link Cable to live players, run this test pass on a single test account. It catches the failure modes that are easy to miss during initial setup — shared-storage misconfigurations, owner-epoch issues, restore-time mistakes, and migration mismatches.

Plan to spend 15-20 minutes on this end-to-end. Don’t skip steps; the order matters because each step builds on the previous one’s confidence.

---

Prerequisites

Before starting:

• All backend servers are up and logging the expected [Link Cable] lines from Installation step 7.
• The orchestrator and at least two participants are online.
• You have a test account that nobody else is using.
• You have console access on every backend.

---

1. Cross-Server Switching

The simplest test, and the one that catches the most setup issues.

1. Connect to the orchestrator backend.
2. Catch a Pokémon, drop something distinctive in your inventory, set your XP to a known number.
3. /server <participant-1> (or the proxy command for switching backends).
4. Verify on participant-1: party Pokémon present, inventory item present, XP matches.
5. /server <participant-2>.
6. Verify the same.
7. /server <orchestrator>.
8. Verify the same.
9. Repeat the round-trip three or four more times.

The full pass is “every lane survives every transfer in any direction”. If something is missing on a specific destination, it’s almost always one of:

• That backend isn’t pointed at the same Mongo as the others.
• That backend’s orchestratorServerId doesn’t match the orchestrator’s serverId.
• Cobblemon on that backend is on file-system persistence instead of Mongo.

---

2. Verify Every Sync Lane

Once basic switching works, verify each lane individually. Use the same test account; it should still be where the previous step left it.

Cobblemon lanes:

Lane	What to check
Party	Six known Pokémon, in a known order, with known nicknames
PC	A specific Pokémon in a specific box and slot
General	Any Cobblemon-tracked player state (current battle counts, etc.)
Pokedex	Catch a previously-uncaught species, note the entry

Player-core lane (the broad one):

Item	What to check
Inventory	A distinctive item in a specific hotbar slot
Selected slot	Hold something specific, transfer, confirm the same slot is selected
Armor	All four armor slots filled with known items (carried inside Inventory)
Ender chest	A distinctive item in a known slot
XP	A specific XP level and a non-zero progress bar — both must match
Hunger	A non-default hunger level (eat something to change it)
Saturation	Eat steak so saturation is non-default; verify after transfer
Health	Take some damage, transfer, confirm the same health value
Game mode	Switch to creative, then back to survival, then transfer
Abilities	If you’ve enabled creative-fly on a survival player, transfer and confirm flight state survives
Recipe book	Unlock a specific recipe (e.g. via discovery), transfer, confirm it’s still unlocked
Score	Note the current score number, transfer, confirm it matches

Per-player Molang:

Item	What to check
Molang state	Any Cobblemon Molang variable set on the player (use /cobblemon debug commands or a script that sets one) — transfer, confirm it persists

Third-party mod attachments:

Item	What to check
Mod data	If you have other mods that attach data to the player (Cardinal Components or Fabric Attachment API), pick one with a player-visible state — e.g. accessories slots, a leveling system’s XP, a mod-tracked stat — and verify it survives a transfer

Switch backends. Every lane should match. Diagnostic guidance:

• Cobblemon lanes are missing (party, PC, Pokedex) — Cobblemon’s MongoDB isn’t shared, or one of the backends is on file-system fallback.
• Player-core fields are missing (inventory, hunger, XP, etc.) — Link Cable’s player-core lane isn’t writing. Check [Link Cable] logs around the transfer for warnings.
• Third-party mod data is missing but vanilla player-core is fine — the mod isn’t using Cardinal Components or the Fabric Attachment API to store its data. (Older mods that store directly to NBT under non-allowlisted keys won’t sync.) Check the mod’s documentation for its data persistence approach.

---

3. Create and Inspect a Backup

/linkcable backup create <player>

Expected output: a clickable header confirming the backup, plus a summary line with the backup ID, size, and timestamp. Click the backup ID to inspect it.

/linkcable backup list <player>

The backup you just created should appear. Check that the size and reason match what you expect.

/linkcable backup browse <player>

Opens an in-game browser. Verify the party and PC lanes are populated correctly inside the backup.

If backup create fails, the canonical storage layer isn’t writing — check [Link Cable] log lines for canonical-storage errors and confirm Mongo connectivity from this backend.

---

4. Restore on an Offline Test Player

Restores are intentionally offline-only. The flow:

1. Have your test player log out.
2. From any backend’s console (not the player’s last server — it doesn’t matter), run:

   /linkcable backup restore <player> <backupId>

3. Confirm the success message and the restored backup’s summary line in chat. (The pre-restore backup is taken automatically before the overwrite; it’ll show up in /linkcable backup list <player> afterwards as a separate entry with reason starting pre-restore:.)
4. Have the player log in. The restored state should be present on whichever backend they spawn into.

If the restore command rejects with Player <uuid> is not offline, that’s working as intended. Have them log out, wait a few seconds for the runtime state to settle to OFFLINE, and try again.

---

5. Pre-Migration Backup (UltraSync only)

If you’re not migrating from UltraSync, skip this step.

If you are, validate the migration on one test account before bulk-migrating:

1. Pick an UltraSync account that’s never logged into Link Cable.
2. Confirm the player is offline.
3. Run:

   /linkcable migrate ultrasync active 1

4. Confirm the success message and the count of migrated players (1).
5. Have the player log in.
6. Verify the player-core lane (inventory, ender chest, XP, hunger, game mode) matches what UltraSync had stored for them.
7. Verify the Cobblemon lanes (party, PC, Pokedex) are unchanged.

The 1 at the end limits the migration to a single record. Without that limit, the command would migrate everything in the UltraSync collection, which you don’t want until you’ve validated the result on one account.

See UltraSync Migration for the full migration flow once you’ve validated.

---

6. Heartbeat and Ownership Health

This step doesn’t require a player; it’s a sanity pass on the network coordination layer.

Cycle the test player between servers as you’ve been doing. Watch each backend’s console while doing it. With debug = false (the default), successful transfers are silent — you should not see warnings or [safety] lines during a clean transfer.

You should not see, in particular:

• Repeated Released stale owner lines during normal transfers (only visible with debug = true). One-off recovery after a backend crash is expected; repeated lines during normal play mean heartbeat or proxy timing is off.
• Sustained Player state is busy, retrying spam. A few during stress is fine; sustained means the network is thrashing — usually a proxy script firing duplicate connect attempts.
• [safety] player=… warnings during normal play. These flag pasture safety violations and other guardrail trips; investigate any that appear.
• Failed to start handoff for …, Failed to mark player … active, or Failed verified persistence for … warnings. These point at concrete failures in the transfer or save path.

To see the per-step trace of a single transfer, set debug = true in config.json and restart the backend. The verbose output makes it obvious which lane (load, save, or handoff) is failing if anything is.

---

7. (Staging Only) Mutate-Bounce and Audit

If you have access to a staging network with the dev tooling enabled, run these before promoting the config to production:

/linkcable dev mutate-bounce <serverA> <serverB> <hops> <delayTicks>
/linkcable dev audit
/linkcable dev pasture-audit

The mutate-bounce test moves the test player back and forth between two backends with stat mutations between hops. The audits check player and pasture state for inconsistencies. If any of them flag, do not promote the config until they’re clean.

These commands are only available in development environments — they aren’t registered on production servers.

---

You’re Done

Once steps 1-6 pass cleanly, the setup is good. Open the network. Read Beta and Production Rollout for the day-of and ongoing operations notes.

If anything in this checklist failed, don’t open the network. The failure modes here are all easier to fix when the only person hitting them is you.