@aephia/atlas-kit 0.6.0-next.12 → 0.6.0-next.121

package/dist/claim-stakes/actions/index.js

@@ -1,21 +1,42 @@
-import { getAddressEncoder, getBytesEncoder, getProgramDerivedAddress, isAddress, } from '@solana/kit';
+import { deriveCurrencyCache, validateCurrencyCache, } from '../../internal/c4/currency-cache.js';
+import { isAddress } from '@solana/kit';
 import { InvalidActionInputError, SageSdkError } from '../../client/errors.js';
 import { readContextRawAccounts } from '../../client/reconciliation.js';
-import { sage } from '../../internal/c4/bindings.js';
+import { StarbaseLevel } from '../../internal/c4/runtime-bindings.js';
 import { readFreshGameClaimStakeConfiguration, } from '../../registry/claim-stakes.js';
-import { characterAccountDefinition, findCharacterPda, } from '../../internal/c4/identity.js';
+import { characterAccountDefinition, findCharacterPda, } from '../../internal/c4/character.js';
 import { deriveFactionOwnershipAddress, factionOwnershipAccountDefinition, } from '../../internal/c4/factions.js';
 import { claimStakeAccountDefinition } from '../../internal/c4/claim-stake.js';
-import { deriveFleetCrewBindingAddress, fleetCrewBindingAccountDefinition, } from '../../internal/c4/fleet-crew-binding.js';
+import { factionValue } from '../../internal/c4/faction.js';
+import { deriveFleetCrewBindingAddress, fleetCrewBindingAccountDefinition, matchesFleetCrewBindingIdentity, } from '../../internal/c4/fleet-crew-binding.js';
 import { deriveFleetAddress, fleetAccountDefinition, } from '../../internal/c4/fleet.js';
 import { deriveProfileFactionAddress, profileFactionIdentityAccountDefinition, } from '../../internal/c4/profile-faction.js';
 import { deriveStarbasePlayerAddress, starbasePlayerAccountDefinition, } from '../../internal/c4/starbase.js';
-import { celestialBodyAccountDefinition, decodeIndexedCelestialBodyAccount, deriveCelestialBodyAddress, deriveStarSystemAddress, starSystemAccountDefinition, } from '../../internal/c4/world.js';
+import { celestialBodyAccountDefinition, deriveCelestialBodyAddress, deriveStarSystemAddress, starSystemAccountDefinition, } from '../../internal/c4/world.js';
+import { resolveXpRuntime } from '../../internal/planning/xp-runtime.js';
+import { requireProfileStarbasePlayer } from '../../internal/planning/starbase-player-owner.js';
 import { requireGameAddress } from '../../internal/game-context.js';
-import { adaptCancelClaimStakeBuildingChangesInstruction, adaptClaimStakeBuildingChangesInstruction, adaptDeconstructClaimStakeInstruction, adaptFinalizeClaimStakeBuildingChangesInstruction, adaptPlaceClaimStakeInstruction, adaptRecoverClaimStakeFleetTransferInstruction, adaptStartClaimStakeFleetTransferInstruction, adaptTopUpClaimStakeRentInstruction, validatePlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
-import { createPlan, } from '../../planning/index.js';
+import { cargoStorageUnits } from '../../internal/cargo.js';
+import { adaptCancelClaimStakeBuildingChangesInstruction, adaptClaimStakeBuildingChangesInstruction, adaptDeconstructClaimStakeInstruction, adaptFinalizeClaimStakeBuildingChangesInstruction, adaptPlaceClaimStakeInstruction, adaptRecoverClaimStakeFleetTransferInstruction, adaptStartClaimStakeFleetTransferInstruction, adaptTopUpClaimStakeRentInstruction, readPlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
+import { buildPlannerPlan } from '../../planning/plan-construction.js';
 import { readFreshGameCargoDefinitions } from '../../registry/cargo.js';
 import { resolveCargo } from '../../registry/index.js';
+import { accountAbsentPrecondition, accountStatePrecondition, } from '../../internal/planning/account-state.js';
+async function resolveClaimStakeXp(ctx, game, structure, character) {
+    const xp = await resolveXpRuntime(ctx, {
+        game,
+        structure,
+        ...(character === undefined ? {} : { character }),
+    });
+    const guard = {
+        kind: 'xp-runtime',
+        address: game,
+        intent: xp.intent,
+        accounts: xp.accounts,
+        describes: 'The Game and canonical Claim Stake XP accounts remain supported; accrued XP may change. Initialize or repair missing XP state using the game client, then recreate the Plan.',
+    };
+    return { accounts: xp.accounts, guard };
+}
 const U64_MAX = (1n << 64n) - 1n;
 const U16_MAX = 65_535;
 const I32_MAX = 2_147_483_647;
@@ -31,13 +52,13 @@ const LEVEL_INDEX = Object.freeze({
     css: 6,
 });
 const CLAIM_STAKE_PLOT_LEVELS = Object.freeze([
-    sage.StarbaseLevel.Level0,
-    sage.StarbaseLevel.Level1,
-    sage.StarbaseLevel.Level2,
-    sage.StarbaseLevel.Level3,
-    sage.StarbaseLevel.Level4,
-    sage.StarbaseLevel.Level5,
-    sage.StarbaseLevel.Css,
+    StarbaseLevel.Level0,
+    StarbaseLevel.Level1,
+    StarbaseLevel.Level2,
+    StarbaseLevel.Level3,
+    StarbaseLevel.Level4,
+    StarbaseLevel.Level5,
+    StarbaseLevel.Css,
 ]);
 const TIER_INDEX = Object.freeze({
     one: 0,
@@ -90,15 +111,7 @@ function validateOptions(value) {
         'hubBuildingId',
         'initialRentAmount',
     ]);
-    const authorizationRecord = record(options.authorization, 'authorization');
-    exactKeys(authorizationRecord, 'authorization', ['profile', 'authority', 'keyIndex'], ['certificate']);
-    const authorization = authorizationRecord;
-    address(authorization.profile, 'authorization.profile');
-    address(authorization.authority, 'authorization.authority');
-    if (authorization.certificate !== undefined) {
-        address(authorization.certificate, 'authorization.certificate');
-    }
-    validatePlanAuthorization(authorization);
+    const authorization = readPlanAuthorization(options.authorization);
     if (typeof options.initialRentAmount !== 'bigint' ||
         options.initialRentAmount <= 0n ||
         options.initialRentAmount > U64_MAX) {
@@ -112,22 +125,10 @@ function validateOptions(value) {
         initialRentAmount: options.initialRentAmount,
     };
 }
-function validateAuthorization(value) {
-    const authorizationRecord = record(value, 'authorization');
-    exactKeys(authorizationRecord, 'authorization', ['profile', 'authority', 'keyIndex'], ['certificate']);
-    const authorization = authorizationRecord;
-    address(authorization.profile, 'authorization.profile');
-    address(authorization.authority, 'authorization.authority');
-    if (authorization.certificate !== undefined) {
-        address(authorization.certificate, 'authorization.certificate');
-    }
-    validatePlanAuthorization(authorization);
-    return authorization;
-}
 function validateBuildingChangeOptions(value) {
     const options = record(value, 'options');
     exactKeys(options, 'options', ['authorization', 'buildingChanges']);
-    const authorization = validateAuthorization(options.authorization);
+    const authorization = readPlanAuthorization(options.authorization);
     const values = options.buildingChanges;
     if (!Array.isArray(values) || values.length === 0) {
         invalid('buildingChanges', values, 'a non-empty dense array of add/remove building changes', 'Provide at least one exact building change before retrying.');
@@ -168,22 +169,22 @@ function validateBuildingChangeOptions(value) {
 function validateFinalizeBuildingChangeOptions(value) {
     const options = record(value, 'options');
     exactKeys(options, 'options', ['authorization']);
-    return { authorization: validateAuthorization(options.authorization) };
+    return { authorization: readPlanAuthorization(options.authorization) };
 }
 function validateCancelBuildingChangeOptions(value) {
     const options = record(value, 'options');
     exactKeys(options, 'options', ['authorization']);
-    return { authorization: validateAuthorization(options.authorization) };
+    return { authorization: readPlanAuthorization(options.authorization) };
 }
 function validateDeconstructOptions(value) {
     const options = record(value, 'options');
     exactKeys(options, 'options', ['authorization']);
-    return { authorization: validateAuthorization(options.authorization) };
+    return { authorization: readPlanAuthorization(options.authorization) };
 }
 function validateTopUpRentOptions(value) {
     const options = record(value, 'options');
     exactKeys(options, 'options', ['amount', 'authorization']);
-    const authorization = validateAuthorization(options.authorization);
+    const authorization = readPlanAuthorization(options.authorization);
     if (typeof options.amount !== 'bigint' ||
         options.amount <= 0n ||
         options.amount > U64_MAX) {
@@ -220,7 +221,7 @@ function validateCargoRequests(value, field, seen) {
 function validateStartFleetTransferOptions(value) {
     const options = record(value, 'options');
     exactKeys(options, 'options', ['authorization', 'load', 'unload']);
-    const authorization = validateAuthorization(options.authorization);
+    const authorization = readPlanAuthorization(options.authorization);
     const seen = new Set();
     const load = validateCargoRequests(options.load, 'load', seen);
     const unload = validateCargoRequests(options.unload, 'unload', seen);
@@ -232,7 +233,7 @@ function validateStartFleetTransferOptions(value) {
 function validateRecoverFleetTransferOptions(value) {
     const options = record(value, 'options');
     exactKeys(options, 'options', ['atUnixSeconds', 'authorization']);
-    const authorization = validateAuthorization(options.authorization);
+    const authorization = readPlanAuthorization(options.authorization);
     if (typeof options.atUnixSeconds !== 'bigint' ||
         options.atUnixSeconds < 0n ||
         options.atUnixSeconds > U64_MAX) {
@@ -240,53 +241,9 @@ function validateRecoverFleetTransferOptions(value) {
     }
     return { atUnixSeconds: options.atUnixSeconds, authorization };
 }
-async function deriveCurrencyCacheAddress(game) {
-    const [derived] = await getProgramDerivedAddress({
-        programAddress: sage.SAGE_PROGRAM_ADDRESS,
-        seeds: [
-            getBytesEncoder().encode(new TextEncoder().encode('CurrencyConfig')),
-            getAddressEncoder().encode(game),
-        ],
-    });
-    return derived;
-}
-function validateCurrencyCache(account, game, canonicalAddress, action) {
-    const decoder = sage.getCurrencyConfigCacheDecoder();
-    const validDiscriminator = sage.CURRENCY_CONFIG_CACHE_DISCRIMINATOR.every((byte, index) => account.data[index] === byte);
-    if (account.address !== canonicalAddress ||
-        account.owner !== sage.SAGE_PROGRAM_ADDRESS ||
-        account.data.length !== decoder.fixedSize ||
-        !validDiscriminator ||
-        decoder.decode(account.data).gameId !== game) {
-        fail(`CurrencyCache ${account.address} does not match the configured Game, canonical PDA, owner, or pinned account layout. Refresh the Game currency configuration and retry ${action}.`, account.address);
-    }
-}
 function requireAccount(account, accountAddress, message) {
     return account ?? fail(message, accountAddress);
 }
-async function hashAccountState(account) {
-    const owner = getAddressEncoder().encode(account.owner);
-    const canonical = new Uint8Array(owner.length + account.data.length);
-    canonical.set(owner);
-    canonical.set(account.data, owner.length);
-    const digest = new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', canonical));
-    return [...digest].map((byte) => byte.toString(16).padStart(2, '0')).join('');
-}
-async function precondition(account, describes) {
-    return Object.freeze({
-        address: account.address,
-        dataHash: await hashAccountState(account),
-        describes,
-        kind: 'account-state',
-    });
-}
-function absentPrecondition(accountAddress, describes) {
-    return Object.freeze({
-        address: accountAddress,
-        describes,
-        kind: 'account-absent',
-    });
-}
 function findDefinition(configuration, id, game) {
     const definition = configuration.claimStakes.definitions.find((candidate) => candidate.id === id);
     return (definition ??
@@ -332,17 +289,7 @@ export async function planPlaceClaimStake(ctx, body, player, input) {
     if (canonicalBody !== body.address) {
         fail(`Celestial Body ${body.address} is not the canonical Body ${String(body.id)} for the configured Game. Refresh the Body and retry.`, body.address);
     }
-    if (player.playerProfile.address !== options.authorization.profile) {
-        fail(`Starbase Player ${player.address} does not belong to authorization Profile ${options.authorization.profile}. Refresh the Starbase Player for that Profile and retry.`, player.address);
-    }
-    const character = await findCharacterPda(options.authorization.profile, game);
-    if (player.character.address !== character) {
-        fail(`Starbase Player ${player.address} does not reference the canonical Character ${character} for authorization Profile ${options.authorization.profile}. Refresh the Starbase Player and retry.`, player.address);
-    }
-    const canonicalPlayer = await deriveStarbasePlayerAddress(player.system.address, character);
-    if (canonicalPlayer !== player.address) {
-        fail(`Starbase Player ${player.address} is not canonical for its Character and System. Refresh the Starbase Player and retry.`, player.address);
-    }
+    const character = await requireProfileStarbasePlayer(player, options.authorization.profile, game);
     if (body.system.address !== player.system.address) {
         fail(`Celestial Body ${body.address} belongs to System ${body.system.address}, but Starbase Player ${player.address} belongs to System ${player.system.address}. Choose both snapshots from the same System and retry.`, body.address);
     }
@@ -385,11 +332,10 @@ export async function planPlaceClaimStake(ctx, body, player, input) {
     }
     const currentBodyAccount = requireAccount(bodyAccount, body.address, `Celestial Body ${body.address} is missing. Refresh the Body and retry placement.`);
     const currentPlayerAccount = requireAccount(playerAccount, player.address, `Starbase Player ${player.address} is missing. Refresh it and retry placement.`);
-    const currentCharacterAccount = requireAccount(characterAccount, character, `Canonical Character ${character} is missing. Refresh the Profile Character and retry placement.`);
     const currentSystemAccount = requireAccount(systemAccount, body.system.address, `Star System ${body.system.address} is missing. Refresh the System and retry placement.`);
     const currentBody = celestialBodyAccountDefinition.decode(currentBodyAccount);
     const currentPlayer = starbasePlayerAccountDefinition.decode(currentPlayerAccount);
-    const currentCharacter = characterAccountDefinition.decode(currentCharacterAccount);
+    const { account: currentCharacterAccount } = requireProfileCharacter(characterAccount, character, options.authorization.profile, game, 'placement');
     const currentSystem = starSystemAccountDefinition.decode(currentSystemAccount);
     const canonicalSystem = await deriveStarSystemAddress(game, currentSystem.systemId);
     if (canonicalSystem !== body.system.address ||
@@ -411,10 +357,6 @@ export async function planPlaceClaimStake(ctx, body, player, input) {
         currentPlayer.totalCrew - currentPlayer.busyCrew !== player.availableCrew) {
         fail(`Starbase Player ${player.address} changed or does not match the authorization Profile, canonical Character, System, or available crew. Refresh it and retry.`, player.address);
     }
-    if (currentCharacter.playerProfile !== options.authorization.profile ||
-        currentCharacter.game !== game) {
-        fail(`Character ${character} does not match authorization Profile ${options.authorization.profile} and configured Game ${game}. Refresh the Character and retry.`, character);
-    }
     const currentCargo = currentPlayer.cargo.amounts.find(({ cargoId }) => cargoId === definition.cargoId)?.amount ?? 0n;
     if (currentCargo !== cargoQuantity || currentCargo < 1n) {
         fail(`Starbase Player ${player.address} Claim Stake cargo changed from the loaded snapshot or is no longer sufficient. Refresh its cargo and retry.`, player.address);
@@ -432,19 +374,19 @@ export async function planPlaceClaimStake(ctx, body, player, input) {
         fail(`Planet ${body.name} (${body.address}) has no available ${definition.name} plot at Starbase ${currentSystem.starbase.level}; ${String(usedPlots)} of ${String(plotLimit)} known plots are occupied. Choose another eligible Planet or tier, refresh it, and retry.`, body.address);
     }
     const profileFaction = await deriveProfileFactionAddress(options.authorization.profile);
-    const currencyCache = await deriveCurrencyCacheAddress(game);
+    const currencyCache = await deriveCurrencyCache(game).then(([address]) => address);
     const description = `Place ${definition.name} on Planet ${body.name} (${body.address}) with bundled hub ${hub.name}, ${String(hub.neededCrew)} crew, and ${String(options.initialRentAmount)} raw initial rent.`;
-    return createPlan({
+    return buildPlannerPlan({
         kind: 'claim-stakes.place',
         preconditions: [
             ...(await Promise.all([
-                precondition(freshGame.account, `The configured Game retains Claim Stake definition ${String(definition.id)} and bundled hub ${String(hub.id)} eligibility.`),
-                precondition(currentBodyAccount, `Planet ${body.name} retains an available ${definition.name} plot and its configured Game/System relationship.`),
-                precondition(currentPlayerAccount, `Starbase Player ${player.address} retains its Profile, Character, System, available crew, and ${cargoName} balance.`),
-                precondition(currentCharacterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game.`),
-                precondition(currentSystemAccount, `Star System ${currentSystem.name} retains its configured Game, sequence, and active Starbase level.`),
+                accountStatePrecondition(freshGame.account, `The configured Game retains Claim Stake definition ${String(definition.id)} and bundled hub ${String(hub.id)} eligibility.`),
+                accountStatePrecondition(currentBodyAccount, `Planet ${body.name} retains an available ${definition.name} plot and its configured Game/System relationship.`),
+                accountStatePrecondition(currentPlayerAccount, `Starbase Player ${player.address} retains its Profile, Character, System, available crew, and ${cargoName} balance.`),
+                characterPrecondition(currentCharacterAccount, options.authorization.profile),
+                accountStatePrecondition(currentSystemAccount, `Star System ${currentSystem.name} retains its configured Game, sequence, and active Starbase level.`),
             ])),
-            absentPrecondition(options.claimStake, 'The caller-supplied Claim Stake signer address remains unallocated.'),
+            accountAbsentPrecondition(options.claimStake, 'The caller-supplied Claim Stake signer address remains unallocated.'),
         ],
         steps: [
             {
@@ -492,12 +434,165 @@ function sameStakeState(left, right) {
                 sameQuantities(left.buildings, right.buildings));
     }
 }
-const LEGACY_CONTROLLER_ID = Object.freeze({
-    unaligned: 0,
-    mud: 1,
-    oni: 2,
-    ustur: 3,
-});
+// Common facts for planners acting on an owned, placed Claim Stake. Each
+// planner keeps its own eligibility checks and Plan wording at its call site;
+// `action` completes the shared remedies ("retry <action>").
+/** Requires the loaded Claim Stake to belong to the configured Game and to the
+ * authorization Profile's canonical Character, which it returns. */
+async function requireOwnedStake(stake, game, profile) {
+    if (stake.game !== game) {
+        fail(`Claim Stake ${stake.address} does not match the configured Game ${game}. Refresh it through this context and retry.`, stake.address);
+    }
+    const character = await findCharacterPda(profile, game);
+    if (stake.ownerCharacter.address !== character) {
+        fail(`Claim Stake ${stake.address} does not belong to authorization Profile ${profile}'s canonical Character ${character}. Choose an owned Claim Stake, refresh it, and retry.`, stake.address);
+    }
+    return character;
+}
+/** Reads and decodes the fresh Claim Stake and Body, with `extra` accounts in
+ * the same batch. */
+async function readOwnedStake(ctx, stake, action, extra = []) {
+    const [stakeCandidate, bodyCandidate, ...extraAccounts] = await readContextRawAccounts(ctx, [
+        stake.address,
+        stake.body.address,
+        ...extra,
+    ]);
+    const stakeAccount = requireAccount(stakeCandidate, stake.address, `Claim Stake ${stake.address} is missing. Refresh it and retry ${action}.`);
+    const bodyAccount = requireAccount(bodyCandidate, stake.body.address, `Celestial Body ${stake.body.address} is missing. Refresh the Claim Stake Body and retry ${action}.`);
+    return {
+        bodyAccount,
+        currentBody: celestialBodyAccountDefinition.decode(bodyAccount),
+        currentStake: claimStakeAccountDefinition.decode(stakeAccount),
+        extraAccounts,
+        stakeAccount,
+    };
+}
+/** Whether the fresh Claim Stake keeps the loaded ownership, Body,
+ * definitions, buildings and System generation. */
+function sameOwnedStake(current, stake, game, character) {
+    return (current.game === game &&
+        current.body === stake.body.address &&
+        current.ownerCharacter === character &&
+        current.claimStakeDefinitionId === stake.claimStakeDefinitionId &&
+        current.claimStakeDefinitionSeqId === stake.claimStakeDefinitionSeqId &&
+        current.buildingDefinitionSeqId === stake.buildingDefinitionSeqId &&
+        current.systemSeqId === stake.systemSeqId &&
+        sameQuantities(current.buildings, stake.buildings));
+}
+/** Whether the fresh Claim Stake keeps the loaded transfer facts: ownership,
+ * Body, active state, System generation, resources and capacity. */
+function sameTransferStake(current, stake, game, character) {
+    return (current.game === game &&
+        current.ownerCharacter === character &&
+        current.body === stake.body.address &&
+        current.systemSeqId === stake.systemSeqId &&
+        current.state.kind === 'active' &&
+        current.production.cargoPod.storageCost ===
+            stake.resources.capacity.usedRaw &&
+        current.production.resourceCapacityRaw ===
+            stake.resources.capacity.totalRaw &&
+        sameCargoAmounts(current.production.cargoPod.amounts, stake.resources.inventory.items.map(({ id, quantityRaw }) => ({
+            amount: quantityRaw,
+            id,
+        }))));
+}
+/** Whether the fresh Fleet keeps the loaded Game, owner, name, cargo and
+ * capacities. */
+function sameTransferFleet(current, fleet, game, profile) {
+    return (current.game === game &&
+        current.ownerProfile === profile &&
+        current.name === fleet.name &&
+        current.ammoBank.cargoId === fleet.ammo.id &&
+        current.ammoBank.amount === fleet.ammo.amount &&
+        current.fuelTank.cargoId === fleet.fuel.id &&
+        current.fuelTank.amount === fleet.fuel.amount &&
+        current.cargoHold.storageCost === fleet.cargoHold.storageCost &&
+        sameCargoAmounts(current.cargoHold.amounts, fleet.cargoHold.items) &&
+        current.stats.cargo.ammoCapacity === fleet.capacities.ammo.total &&
+        current.stats.cargo.fuelCapacity === fleet.capacities.fuel.total &&
+        current.stats.cargo.cargoCapacity === fleet.capacities.cargo.total);
+}
+/** Requires the fresh Body to be the Claim Stake's canonical Planet in the
+ * configured Game at the Claim Stake's System generation. */
+async function requireStakePlanet(currentBody, stake, game, action) {
+    if (currentBody.kind !== 'planet' ||
+        currentBody.game !== game ||
+        currentBody.systemSequenceId !== stake.systemSeqId ||
+        (await deriveCelestialBodyAddress(game, currentBody.id)) !==
+            stake.body.address) {
+        fail(`Celestial Body ${stake.body.address} does not match the Claim Stake's configured Game, canonical Planet identity, or System generation. Refresh the Body and Claim Stake before retrying ${action}.`, stake.body.address);
+    }
+    return currentBody;
+}
+/** Requires and decodes the canonical Character of the authorization Profile in
+ * the configured Game. */
+function requireProfileCharacter(candidate, character, profile, game, action) {
+    const account = requireAccount(candidate, character, `Canonical Character ${character} is missing. Refresh the Profile Character and retry ${action}.`);
+    const current = characterAccountDefinition.decode(account);
+    if (current.playerProfile !== profile || current.game !== game) {
+        fail(`Character ${character} does not match authorization Profile ${profile} and configured Game ${game}. Refresh the Character and retry ${action}.`, character);
+    }
+    return { account, current };
+}
+/** Reads the Claim Stake's System and the authorization Profile's canonical
+ * Starbase Player there, with `extra` accounts in the same batch. Requires a
+ * canonical, current System with an active Starbase that lists the Body, and a
+ * Starbase Player of the Profile, Character and System. */
+async function readStakeStarbase(ctx, stake, game, system, character, profile, action, extra = []) {
+    const player = await deriveStarbasePlayerAddress(system, character);
+    const [systemCandidate, playerCandidate, ...extraAccounts] = await readContextRawAccounts(ctx, [system, player, ...extra]);
+    const systemAccount = requireAccount(systemCandidate, system, `Star System ${system} is missing. Refresh the Claim Stake's System and retry ${action}.`);
+    const playerAccount = requireAccount(playerCandidate, player, `Starbase Player ${player} is missing for authorization Profile ${profile}. Register or refresh it in the Claim Stake's System before retrying ${action}.`);
+    const currentSystem = starSystemAccountDefinition.decode(systemAccount);
+    const currentPlayer = starbasePlayerAccountDefinition.decode(playerAccount);
+    if (currentSystem.game !== game ||
+        currentSystem.sequenceId !== stake.systemSeqId ||
+        currentSystem.starbase === undefined ||
+        !currentSystem.celestialBodyAddresses.includes(stake.body.address) ||
+        (await deriveStarSystemAddress(game, currentSystem.systemId)) !== system) {
+        fail(`Star System ${system} does not match the configured Game, canonical identity, Claim Stake generation, active nested Starbase, or Claim Stake Body relationship. Refresh the System and retry ${action}.`, system);
+    }
+    if (currentPlayer.playerProfile !== profile ||
+        currentPlayer.character !== character ||
+        currentPlayer.system !== system) {
+        fail(`Starbase Player ${player} does not match the authorization Profile, canonical Character, and Claim Stake System. Refresh it and retry ${action}.`, player);
+    }
+    return {
+        currentPlayer,
+        currentSystem,
+        extraAccounts,
+        player,
+        playerAccount,
+        starbase: currentSystem.starbase,
+        systemAccount,
+    };
+}
+async function claimStakeCurrencyCache(game) {
+    const [currencyCache] = await deriveCurrencyCache(game);
+    return currencyCache;
+}
+/** Requires the canonical CurrencyCache and returns its Plan guard. */
+async function requireCurrencyCache(candidate, currencyCache, game, action, planName) {
+    await validateCurrencyCache(requireAccount(candidate, currencyCache, `Canonical CurrencyCache ${currencyCache} is missing for configured Game ${game}. Refresh the Game currency configuration and retry ${action}.`), game, planName);
+    return {
+        kind: 'currency-cache',
+        address: currencyCache,
+        game,
+        describes: 'The canonical CurrencyCache remains assigned to the configured Game; shared accounting may change.',
+    };
+}
+function planetPrecondition(account, system) {
+    return accountStatePrecondition(account, `The Claim Stake Planet remains assigned to System ${system} at the current generation.`);
+}
+function characterPrecondition(account, profile) {
+    return accountStatePrecondition(account, `The canonical Character remains assigned to Profile ${profile} in the configured Game.`);
+}
+function systemPrecondition(account, name) {
+    return accountStatePrecondition(account, `Star System ${name} retains its configured Game, sequence, nested Starbase, and Claim Stake Body relationship.`);
+}
+function playerPrecondition(account, player, facts = 'Profile, Character, and System') {
+    return accountStatePrecondition(account, `Starbase Player ${player} retains its ${facts}.`);
+}
 function buildingDescription(change, name) {
     return `${change.kind} ${String(change.quantity)} ${name}`;
 }
@@ -509,6 +604,9 @@ function buildingDescription(change, name) {
  * construction cargo. Rent synchronization and the final concurrent sequence
  * race remain chain-authoritative.
  *
+ * Requires Game 2 and its existing canonical Claim Stake XP ledger.
+ * Missing XP state must be repaired outside this Plan; no accounts are created.
+ *
  * @example
  * ```ts
  * declare const ctx: SageContext;
@@ -521,88 +619,40 @@ function buildingDescription(change, name) {
 export async function planClaimStakeBuildingChanges(ctx, stake, input) {
     const options = validateBuildingChangeOptions(input);
     const game = requireGameAddress(ctx);
+    const { profile } = options.authorization;
     if (stake.state.kind === 'deactivated') {
         fail(`Claim Stake ${stake.address} is deactivated; building changes require an active or design Claim Stake. Refresh it or choose another owned Claim Stake before retrying.`, stake.address);
     }
-    if (stake.game !== game) {
-        fail(`Claim Stake ${stake.address} does not match the configured Game ${game}. Refresh it through this context and retry.`, stake.address);
-    }
-    const character = await findCharacterPda(options.authorization.profile, game);
-    if (stake.ownerCharacter.address !== character) {
-        fail(`Claim Stake ${stake.address} does not belong to authorization Profile ${options.authorization.profile}'s canonical Character ${character}. Choose an owned Claim Stake, refresh it, and retry.`, stake.address);
-    }
-    const [freshGame, firstAccounts] = await Promise.all([
+    const character = await requireOwnedStake(stake, game, profile);
+    const action = 'building changes';
+    const [freshGame, loaded] = await Promise.all([
         readFreshGameClaimStakeConfiguration(ctx),
-        readContextRawAccounts(ctx, [stake.address, stake.body.address, character]),
+        readOwnedStake(ctx, stake, action, [character]),
     ]);
     if (freshGame === undefined) {
         fail(`Configured Game ${game} is missing. Refresh the Game catalog and retry building changes.`, game);
     }
-    const stakeAccount = requireAccount(firstAccounts[0], stake.address, `Claim Stake ${stake.address} is missing. Refresh it and retry building changes.`);
-    const bodyAccount = requireAccount(firstAccounts[1], stake.body.address, `Celestial Body ${stake.body.address} is missing. Refresh the Claim Stake Body and retry building changes.`);
-    const characterAccount = requireAccount(firstAccounts[2], character, `Canonical Character ${character} is missing. Refresh the Profile Character and retry building changes.`);
-    const currentStake = claimStakeAccountDefinition.decode(stakeAccount);
-    const currentBody = celestialBodyAccountDefinition.decode(bodyAccount);
-    const currentCharacter = characterAccountDefinition.decode(characterAccount);
-    if (currentStake.game !== game ||
-        currentStake.body !== stake.body.address ||
-        currentStake.ownerCharacter !== character ||
-        currentStake.claimStakeDefinitionId !== stake.claimStakeDefinitionId ||
-        currentStake.claimStakeDefinitionSeqId !==
-            stake.claimStakeDefinitionSeqId ||
-        currentStake.buildingDefinitionSeqId !== stake.buildingDefinitionSeqId ||
-        currentStake.systemSeqId !== stake.systemSeqId ||
-        !sameQuantities(currentStake.buildings, stake.buildings) ||
+    const { bodyAccount, currentStake, stakeAccount } = loaded;
+    if (!sameOwnedStake(currentStake, stake, game, character) ||
         currentStake.neededCrew !== stake.neededCrew) {
         fail(`Claim Stake ${stake.address} changed or does not match its loaded ownership, Body, definitions, buildings, crew, or System generation. Refresh it and retry building changes.`, stake.address);
     }
-    if (currentCharacter.playerProfile !== options.authorization.profile ||
-        currentCharacter.game !== game) {
-        fail(`Character ${character} does not match authorization Profile ${options.authorization.profile} and configured Game ${game}. Refresh the Character and retry building changes.`, character);
-    }
-    if (currentBody.kind !== 'planet' ||
-        currentBody.game !== game ||
-        currentBody.systemSequenceId !== stake.systemSeqId ||
-        (await deriveCelestialBodyAddress(game, currentBody.id)) !==
-            stake.body.address) {
-        fail(`Celestial Body ${stake.body.address} does not match the Claim Stake's configured Game, canonical Planet identity, or System generation. Refresh the Body and Claim Stake before retrying.`, stake.body.address);
-    }
-    const system = currentBody.system;
-    const [player, ownership, profileFaction] = await Promise.all([
-        deriveStarbasePlayerAddress(system, character),
+    const { system } = await requireStakePlanet(loaded.currentBody, stake, game, action);
+    const { account: characterAccount } = requireProfileCharacter(loaded.extraAccounts[0], character, profile, game, action);
+    const [ownership, profileFaction] = await Promise.all([
         deriveFactionOwnershipAddress(game, 'starbase', system),
-        deriveProfileFactionAddress(options.authorization.profile),
-    ]);
-    const [systemAccountCandidate, playerAccountCandidate, ownershipAccount, profileFactionAccountCandidate,] = await readContextRawAccounts(ctx, [
-        system,
-        player,
-        ownership,
-        profileFaction,
+        deriveProfileFactionAddress(profile),
     ]);
-    const systemAccount = requireAccount(systemAccountCandidate, system, `Star System ${system} is missing. Refresh the Claim Stake's System and retry building changes.`);
-    const playerAccount = requireAccount(playerAccountCandidate, player, `Starbase Player ${player} is missing for authorization Profile ${options.authorization.profile}. Register or refresh it in the Claim Stake's System before retrying.`);
-    const profileFactionAccount = requireAccount(profileFactionAccountCandidate, profileFaction, `ProfileFaction ${profileFaction} is missing for authorization Profile ${options.authorization.profile}. Choose or repair the Profile faction, refresh it, and retry building changes.`);
-    const currentSystem = starSystemAccountDefinition.decode(systemAccount);
-    const currentPlayer = starbasePlayerAccountDefinition.decode(playerAccount);
+    const { currentPlayer, currentSystem, extraAccounts: [ownershipAccount, profileFactionCandidate], player, playerAccount, starbase, systemAccount, } = await readStakeStarbase(ctx, stake, game, system, character, profile, action, [ownership, profileFaction]);
+    const profileFactionAccount = requireAccount(profileFactionCandidate, profileFaction, `ProfileFaction ${profileFaction} is missing for authorization Profile ${profile}. Choose or repair the Profile faction, refresh it, and retry building changes.`);
     const currentProfileFaction = profileFactionIdentityAccountDefinition.decode(profileFactionAccount);
-    if (currentSystem.game !== game ||
-        currentSystem.sequenceId !== stake.systemSeqId ||
-        currentSystem.starbase === undefined ||
-        (await deriveStarSystemAddress(game, currentSystem.systemId)) !== system) {
-        fail(`Star System ${system} does not match the configured Game, canonical identity, Claim Stake generation, or an active nested Starbase. Refresh the System and retry building changes.`, system);
-    }
-    if (currentPlayer.playerProfile !== options.authorization.profile ||
-        currentPlayer.character !== character ||
-        currentPlayer.system !== system) {
-        fail(`Starbase Player ${player} does not match the authorization Profile, canonical Character, and Claim Stake System. Refresh it and retry building changes.`, player);
+    if (currentProfileFaction.profile !== profile) {
+        fail(`ProfileFaction ${profileFaction} does not match authorization Profile ${profile}. Refresh or repair the Profile faction before retrying building changes.`, profileFaction);
     }
-    if (currentProfileFaction.profile !== options.authorization.profile) {
-        fail(`ProfileFaction ${profileFaction} does not match authorization Profile ${options.authorization.profile}. Refresh or repair the Profile faction before retrying building changes.`, profileFaction);
-    }
-    let controllerFactionId = LEGACY_CONTROLLER_ID[currentSystem.starbase.owner];
+    let controllerFactionId = factionValue(starbase.owner);
     let ownershipPrecondition;
     if (ownershipAccount === undefined) {
-        ownershipPrecondition = absentPrecondition(ownership, `The canonical Starbase FactionOwnership ${ownership} remains unallocated so the chain applies its legacy controller gate.`);
+        ownershipPrecondition = accountAbsentPrecondition(ownership, `The canonical Starbase FactionOwnership ${ownership} remains unallocated so the chain applies its legacy controller gate.`);
     }
     else {
         const currentOwnership = factionOwnershipAccountDefinition.decode(ownershipAccount);
@@ -614,7 +664,7 @@ export async function planClaimStakeBuildingChanges(ctx, stake, input) {
         }
         controllerFactionId =
             currentOwnership.controllingFactionId ?? controllerFactionId;
-        ownershipPrecondition = await precondition(ownershipAccount, `The Starbase FactionOwnership remains assigned to System ${system} at its current generation.`);
+        ownershipPrecondition = await accountStatePrecondition(ownershipAccount, `The Starbase FactionOwnership remains assigned to System ${system} at its current generation.`);
     }
     if (currentProfileFaction.factionId !== controllerFactionId) {
         fail(`ProfileFaction ${profileFaction} faction ${String(currentProfileFaction.factionId)} does not match the current Starbase controller faction ${String(controllerFactionId)}. Use a Profile aligned with the current controller, refresh the faction relationship, and retry building changes.`, profileFaction);
@@ -744,26 +794,29 @@ export async function planClaimStakeBuildingChanges(ctx, stake, input) {
     if (currentStake.production.cargoPod.storageCost > resourceStorageRaw) {
         fail(`The resulting Claim Stake design provides ${String(resourceStorageRaw)} raw storage capacity, below the fresh known cargo usage of ${String(currentStake.production.cargoPod.storageCost)}. Keep enough storage buildings, remove cargo, refresh the Claim Stake, and retry building changes.`, stake.address);
     }
-    const currencyCache = await deriveCurrencyCacheAddress(game);
+    const currencyCache = await claimStakeCurrencyCache(game);
     const description = `Change buildings on Claim Stake ${stake.address}: ${descriptions.join('; ')}.`;
-    return createPlan({
+    const xp = await resolveClaimStakeXp(ctx, game, stake.address);
+    return buildPlannerPlan({
         kind: 'claim-stakes.building-changes',
         preconditions: [
             ...(await Promise.all([
-                precondition(freshGame.account, 'The configured Game retains the exact Claim Stake and building definitions.'),
-                precondition(stakeAccount, `Claim Stake ${stake.address} retains its ownership, design sequence, buildings, cargo, crew, and Body relationship.`),
-                precondition(bodyAccount, `The Claim Stake Planet remains assigned to System ${system} at the current generation.`),
-                precondition(characterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game.`),
-                precondition(systemAccount, `Star System ${currentSystem.name} retains its configured Game, sequence, and nested Starbase.`),
-                precondition(playerAccount, `Starbase Player ${player} retains its Profile, Character, System, and available crew.`),
-                precondition(profileFactionAccount, `ProfileFaction ${profileFaction} remains assigned to Profile ${options.authorization.profile} and aligned with the current Starbase controller.`),
+                accountStatePrecondition(freshGame.account, 'The configured Game retains the exact Claim Stake and building definitions.'),
+                accountStatePrecondition(stakeAccount, `Claim Stake ${stake.address} retains its ownership, design sequence, buildings, cargo, crew, and Body relationship.`),
+                planetPrecondition(bodyAccount, system),
+                characterPrecondition(characterAccount, profile),
+                systemPrecondition(systemAccount, currentSystem.name),
+                playerPrecondition(playerAccount, player, 'Profile, Character, System, and available crew'),
+                accountStatePrecondition(profileFactionAccount, `ProfileFaction ${profileFaction} remains assigned to Profile ${profile} and aligned with the current Starbase controller.`),
             ])),
             ownershipPrecondition,
+            xp.guard,
         ],
         steps: [
             {
                 describes: description,
                 instruction: adaptClaimStakeBuildingChangesInstruction({
+                    ...xp.accounts,
                     authorization: options.authorization,
                     buildingChanges: options.buildingChanges.map(({ buildingId, kind, quantity }) => [buildingId, kind === 'add' ? quantity : -quantity]),
                     celestialBody: stake.body.address,
@@ -789,6 +842,10 @@ export async function planClaimStakeBuildingChanges(ctx, stake, input) {
  * CurrencyCache, and a known positive rent balance. Rent timing and the final
  * crew/building validation remain chain-authoritative.
  *
+ * Requires Game 2 and its existing canonical Claim Stake XP ledger.
+ * The Character XP budget and configuration must also be reconciled.
+ * Missing XP state must be repaired outside this Plan; no accounts are created.
+ *
  * @example
  * ```ts
  * declare const ctx: SageContext;
@@ -804,22 +861,18 @@ export async function planClaimStakeBuildingChanges(ctx, stake, input) {
 export async function planFinalizeClaimStakeBuildingChanges(ctx, stake, input) {
     const options = validateFinalizeBuildingChangeOptions(input);
     const game = requireGameAddress(ctx);
+    const { profile } = options.authorization;
     if (stake.state.kind !== 'design') {
         fail(`Claim Stake ${stake.address} is not in design state. Refresh it and finalize only a pending building design.`, stake.address);
     }
-    if (stake.game !== game) {
-        fail(`Claim Stake ${stake.address} does not match the configured Game ${game}. Refresh it through this context and retry.`, stake.address);
-    }
-    const character = await findCharacterPda(options.authorization.profile, game);
-    if (stake.ownerCharacter.address !== character) {
-        fail(`Claim Stake ${stake.address} does not belong to authorization Profile ${options.authorization.profile}'s canonical Character ${character}. Choose an owned Claim Stake, refresh it, and retry.`, stake.address);
-    }
+    const character = await requireOwnedStake(stake, game, profile);
     if (stake.rentBalanceRaw <= 0n) {
         fail(`Claim Stake ${stake.address} has a known delinquent rent balance of ${String(stake.rentBalanceRaw)} raw units. Top up rent, refresh the Claim Stake, and retry finalization.`, stake.address);
     }
-    const [freshGame, firstAccounts] = await Promise.all([
+    const action = 'finalization';
+    const [freshGame, loaded] = await Promise.all([
         readFreshGameClaimStakeConfiguration(ctx),
-        readContextRawAccounts(ctx, [stake.address, stake.body.address, character]),
+        readOwnedStake(ctx, stake, action, [character]),
     ]);
     if (freshGame === undefined) {
         fail(`Configured Game ${game} is missing. Refresh the Game catalog and retry finalization.`, game);
@@ -828,75 +881,40 @@ export async function planFinalizeClaimStakeBuildingChanges(ctx, stake, input) {
         freshGame.data.buildings.sequenceId !== stake.buildingDefinitionSeqId) {
         fail(`Claim Stake ${stake.address} definition sequence is stale against the current Game catalog. Refresh the Claim Stake and definitions to rule out stale local data. If the on-chain generation still differs, use a Claim Stake matching the current catalog before retrying finalization.`, stake.address);
     }
-    const stakeAccount = requireAccount(firstAccounts[0], stake.address, `Claim Stake ${stake.address} is missing. Refresh it and retry finalization.`);
-    const bodyAccount = requireAccount(firstAccounts[1], stake.body.address, `Celestial Body ${stake.body.address} is missing. Refresh the Claim Stake Body and retry finalization.`);
-    const characterAccount = requireAccount(firstAccounts[2], character, `Canonical Character ${character} is missing. Refresh the Profile Character and retry finalization.`);
-    const currentStake = claimStakeAccountDefinition.decode(stakeAccount);
-    const currentBody = celestialBodyAccountDefinition.decode(bodyAccount);
-    const currentCharacter = characterAccountDefinition.decode(characterAccount);
-    if (currentStake.game !== game ||
-        currentStake.body !== stake.body.address ||
-        currentStake.ownerCharacter !== character ||
-        currentStake.claimStakeDefinitionId !== stake.claimStakeDefinitionId ||
-        currentStake.claimStakeDefinitionSeqId !==
-            stake.claimStakeDefinitionSeqId ||
-        currentStake.buildingDefinitionSeqId !== stake.buildingDefinitionSeqId ||
-        currentStake.systemSeqId !== stake.systemSeqId ||
+    const { bodyAccount, currentStake, stakeAccount } = loaded;
+    if (!sameOwnedStake(currentStake, stake, game, character) ||
         currentStake.rentBalanceRaw !== stake.rentBalanceRaw ||
-        !sameQuantities(currentStake.buildings, stake.buildings) ||
         currentStake.state.kind !== 'design' ||
         currentStake.state.sequenceId !== stake.state.sequenceId ||
         !sameQuantities(currentStake.state.buildings, stake.state.buildings)) {
         fail(`Claim Stake ${stake.address} changed or does not match its loaded ownership, Body, definitions, buildings, design sequence, rent, or System generation. Refresh it and retry finalization.`, stake.address);
     }
-    if (currentCharacter.playerProfile !== options.authorization.profile ||
-        currentCharacter.game !== game) {
-        fail(`Character ${character} does not match authorization Profile ${options.authorization.profile} and configured Game ${game}. Refresh the Character and retry finalization.`, character);
-    }
-    if (currentBody.kind !== 'planet' ||
-        currentBody.game !== game ||
-        currentBody.systemSequenceId !== stake.systemSeqId ||
-        (await deriveCelestialBodyAddress(game, currentBody.id)) !==
-            stake.body.address) {
-        fail(`Celestial Body ${stake.body.address} does not match the Claim Stake's configured Game, canonical Planet identity, or System generation. Refresh the Body and Claim Stake before retrying finalization.`, stake.body.address);
-    }
-    const system = currentBody.system;
-    const player = await deriveStarbasePlayerAddress(system, character);
-    const currencyCache = await deriveCurrencyCacheAddress(game);
-    const [systemCandidate, playerCandidate, currencyCandidate] = await readContextRawAccounts(ctx, [system, player, currencyCache]);
-    const systemAccount = requireAccount(systemCandidate, system, `Star System ${system} is missing. Refresh the Claim Stake's System and retry finalization.`);
-    const playerAccount = requireAccount(playerCandidate, player, `Starbase Player ${player} is missing for authorization Profile ${options.authorization.profile}. Register or refresh it in the Claim Stake's System before retrying finalization.`);
-    const currencyAccount = requireAccount(currencyCandidate, currencyCache, `Canonical CurrencyCache ${currencyCache} is missing for configured Game ${game}. Refresh the Game currency configuration and retry finalization.`);
-    const currentSystem = starSystemAccountDefinition.decode(systemAccount);
-    const currentPlayer = starbasePlayerAccountDefinition.decode(playerAccount);
-    if (currentSystem.game !== game ||
-        currentSystem.sequenceId !== stake.systemSeqId ||
-        currentSystem.starbase === undefined ||
-        (await deriveStarSystemAddress(game, currentSystem.systemId)) !== system) {
-        fail(`Star System ${system} does not match the configured Game, canonical identity, Claim Stake generation, or an active nested Starbase. Refresh the System and retry finalization.`, system);
-    }
-    if (currentPlayer.playerProfile !== options.authorization.profile ||
-        currentPlayer.character !== character ||
-        currentPlayer.system !== system) {
-        fail(`Starbase Player ${player} does not match the authorization Profile, canonical Character, and Claim Stake System. Refresh it and retry finalization.`, player);
-    }
-    validateCurrencyCache(currencyAccount, game, currencyCache, 'finalization');
+    const { system } = await requireStakePlanet(loaded.currentBody, stake, game, action);
+    const { account: characterAccount } = requireProfileCharacter(loaded.extraAccounts[0], character, profile, game, action);
+    const currencyCache = await claimStakeCurrencyCache(game);
+    const { currentSystem, extraAccounts: [currencyCandidate], player, playerAccount, systemAccount, } = await readStakeStarbase(ctx, stake, game, system, character, profile, action, [currencyCache]);
+    const currencyGuard = await requireCurrencyCache(currencyCandidate, currencyCache, game, action, 'Claim Stake finalization');
     const description = `Finalize building changes on Claim Stake ${stake.address}.`;
-    return createPlan({
+    const xp = await resolveClaimStakeXp(ctx, game, stake.address, character);
+    return buildPlannerPlan({
         kind: 'claim-stakes.finalize-building-changes',
-        preconditions: await Promise.all([
-            precondition(freshGame.account, 'The configured Game remains current.'),
-            precondition(stakeAccount, `Claim Stake ${stake.address} retains its ownership, design sequence, rent balance, Body, and System generation.`),
-            precondition(characterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game.`),
-            precondition(bodyAccount, `The Claim Stake Planet remains assigned to System ${system} at the current generation.`),
-            precondition(systemAccount, `Star System ${currentSystem.name} retains its configured Game, sequence, and nested Starbase.`),
-            precondition(playerAccount, `Starbase Player ${player} retains its Profile, Character, and System.`),
-            precondition(currencyAccount, 'The canonical CurrencyCache remains assigned to the configured Game.'),
-        ]),
+        preconditions: [
+            xp.guard,
+            ...(await Promise.all([
+                accountStatePrecondition(freshGame.account, 'The configured Game remains current.'),
+                accountStatePrecondition(stakeAccount, `Claim Stake ${stake.address} retains its ownership, design sequence, rent balance, Body, and System generation.`),
+                characterPrecondition(characterAccount, profile),
+                planetPrecondition(bodyAccount, system),
+                systemPrecondition(systemAccount, currentSystem.name),
+                playerPrecondition(playerAccount, player),
+            ])),
+            currencyGuard,
+        ],
         steps: [
             {
                 describes: description,
                 instruction: adaptFinalizeClaimStakeBuildingChangesInstruction({
+                    ...xp.accounts,
                     authorization: options.authorization,
                     celestialBody: stake.body.address,
                     character,
@@ -920,6 +938,9 @@ export async function planFinalizeClaimStakeBuildingChanges(ctx, stake, input) {
  * state; rent arithmetic and concurrent state transitions remain
  * chain-authoritative.
  *
+ * Requires Game 2 and its existing canonical Claim Stake XP ledger.
+ * Missing XP state must be repaired outside this Plan; no accounts are created.
+ *
  * @example
  * ```ts
  * declare const ctx: SageContext;
@@ -934,80 +955,42 @@ export async function planFinalizeClaimStakeBuildingChanges(ctx, stake, input) {
 export async function planCancelClaimStakeBuildingChanges(ctx, stake, input) {
     const options = validateCancelBuildingChangeOptions(input);
     const game = requireGameAddress(ctx);
+    const { profile } = options.authorization;
     if (stake.state.kind !== 'design') {
         fail(`Claim Stake ${stake.address} is not in design state. Refresh it and cancel only a pending building design.`, stake.address);
     }
-    if (stake.game !== game) {
-        fail(`Claim Stake ${stake.address} does not match the configured Game ${game}. Refresh it through this context and retry.`, stake.address);
-    }
-    const character = await findCharacterPda(options.authorization.profile, game);
-    if (stake.ownerCharacter.address !== character) {
-        fail(`Claim Stake ${stake.address} does not belong to authorization Profile ${options.authorization.profile}'s canonical Character ${character}. Choose an owned Claim Stake, refresh it, and retry.`, stake.address);
-    }
-    const firstAccounts = await readContextRawAccounts(ctx, [
-        stake.address,
-        stake.body.address,
-    ]);
-    const stakeAccount = requireAccount(firstAccounts[0], stake.address, `Claim Stake ${stake.address} is missing. Refresh it and retry cancellation.`);
-    const bodyAccount = requireAccount(firstAccounts[1], stake.body.address, `Celestial Body ${stake.body.address} is missing. Refresh the Claim Stake Body and retry cancellation.`);
-    const currentStake = claimStakeAccountDefinition.decode(stakeAccount);
-    const currentBody = celestialBodyAccountDefinition.decode(bodyAccount);
-    if (currentStake.game !== game ||
-        currentStake.body !== stake.body.address ||
-        currentStake.ownerCharacter !== character ||
-        currentStake.claimStakeDefinitionId !== stake.claimStakeDefinitionId ||
-        currentStake.claimStakeDefinitionSeqId !==
-            stake.claimStakeDefinitionSeqId ||
-        currentStake.buildingDefinitionSeqId !== stake.buildingDefinitionSeqId ||
-        currentStake.systemSeqId !== stake.systemSeqId ||
-        !sameQuantities(currentStake.buildings, stake.buildings) ||
+    const character = await requireOwnedStake(stake, game, profile);
+    const action = 'cancellation';
+    const { bodyAccount, currentBody, currentStake, stakeAccount } = await readOwnedStake(ctx, stake, action);
+    if (!sameOwnedStake(currentStake, stake, game, character) ||
         currentStake.state.kind !== 'design' ||
         currentStake.state.sequenceId !== stake.state.sequenceId ||
         !sameQuantities(currentStake.state.buildings, stake.state.buildings)) {
         fail(`Claim Stake ${stake.address} changed or does not match its loaded ownership, Body, definitions, buildings, design sequence, or System generation. Refresh it and retry cancellation.`, stake.address);
     }
-    if (currentBody.kind !== 'planet' ||
-        currentBody.game !== game ||
-        currentBody.systemSequenceId !== stake.systemSeqId ||
-        (await deriveCelestialBodyAddress(game, currentBody.id)) !==
-            stake.body.address) {
-        fail(`Celestial Body ${stake.body.address} does not match the Claim Stake's configured Game, canonical Planet identity, or System generation. Refresh the Body and Claim Stake before retrying cancellation.`, stake.body.address);
-    }
-    const system = currentBody.system;
-    const player = await deriveStarbasePlayerAddress(system, character);
-    const currencyCache = await deriveCurrencyCacheAddress(game);
-    const [systemCandidate, playerCandidate, currencyCandidate] = await readContextRawAccounts(ctx, [system, player, currencyCache]);
-    const systemAccount = requireAccount(systemCandidate, system, `Star System ${system} is missing. Refresh the Claim Stake's System and retry cancellation.`);
-    const playerAccount = requireAccount(playerCandidate, player, `Starbase Player ${player} is missing for authorization Profile ${options.authorization.profile}. Register or refresh it in the Claim Stake's System before retrying cancellation.`);
-    const currencyAccount = requireAccount(currencyCandidate, currencyCache, `Canonical CurrencyCache ${currencyCache} is missing for configured Game ${game}. Refresh the Game currency configuration and retry cancellation.`);
-    const currentSystem = starSystemAccountDefinition.decode(systemAccount);
-    const currentPlayer = starbasePlayerAccountDefinition.decode(playerAccount);
-    if (currentSystem.game !== game ||
-        currentSystem.sequenceId !== stake.systemSeqId ||
-        currentSystem.starbase === undefined ||
-        (await deriveStarSystemAddress(game, currentSystem.systemId)) !== system) {
-        fail(`Star System ${system} does not match the configured Game, canonical identity, Claim Stake generation, or an active nested Starbase. Refresh the System and retry cancellation.`, system);
-    }
-    if (currentPlayer.playerProfile !== options.authorization.profile ||
-        currentPlayer.character !== character ||
-        currentPlayer.system !== system) {
-        fail(`Starbase Player ${player} does not match the authorization Profile, canonical Character, and Claim Stake System. Refresh it and retry cancellation.`, player);
-    }
-    validateCurrencyCache(currencyAccount, game, currencyCache, 'cancellation');
+    const { system } = await requireStakePlanet(currentBody, stake, game, action);
+    const currencyCache = await claimStakeCurrencyCache(game);
+    const { currentSystem, extraAccounts: [currencyCandidate], player, playerAccount, systemAccount, } = await readStakeStarbase(ctx, stake, game, system, character, profile, action, [currencyCache]);
+    const currencyGuard = await requireCurrencyCache(currencyCandidate, currencyCache, game, action, 'Claim Stake cancellation');
     const description = `Cancel the pending building design on Claim Stake ${stake.address} and return it to active state.`;
-    return createPlan({
+    const xp = await resolveClaimStakeXp(ctx, game, stake.address);
+    return buildPlannerPlan({
         kind: 'claim-stakes.cancel-building-changes',
-        preconditions: await Promise.all([
-            precondition(stakeAccount, `Claim Stake ${stake.address} retains its ownership, design sequence, buildings, Body, and System generation.`),
-            precondition(bodyAccount, `The Claim Stake Planet remains assigned to System ${system} at the current generation.`),
-            precondition(systemAccount, `Star System ${currentSystem.name} retains its configured Game, sequence, and nested Starbase.`),
-            precondition(playerAccount, `Starbase Player ${player} retains its Profile, Character, and System.`),
-            precondition(currencyAccount, 'The canonical CurrencyCache remains assigned to the configured Game.'),
-        ]),
+        preconditions: [
+            xp.guard,
+            ...(await Promise.all([
+                accountStatePrecondition(stakeAccount, `Claim Stake ${stake.address} retains its ownership, design sequence, buildings, Body, and System generation.`),
+                planetPrecondition(bodyAccount, system),
+                systemPrecondition(systemAccount, currentSystem.name),
+                playerPrecondition(playerAccount, player),
+            ])),
+            currencyGuard,
+        ],
         steps: [
             {
                 describes: description,
                 instruction: adaptCancelClaimStakeBuildingChangesInstruction({
+                    ...xp.accounts,
                     authorization: options.authorization,
                     celestialBody: stake.body.address,
                     claimStakeInstance: stake.address,
@@ -1043,46 +1026,25 @@ export async function planCancelClaimStakeBuildingChanges(ctx, stake, input) {
 export async function planDeconstructClaimStake(ctx, stake, input) {
     const options = validateDeconstructOptions(input);
     const game = requireGameAddress(ctx);
+    const { profile } = options.authorization;
     if (stake.state.kind !== 'active') {
         fail(`Claim Stake ${stake.address} is not in active state. Refresh it, finalize or cancel any pending design, and retry deconstruction.`, stake.address);
     }
-    if (stake.game !== game) {
-        fail(`Claim Stake ${stake.address} does not match the configured Game ${game}. Refresh it through this context and retry.`, stake.address);
-    }
-    const character = await findCharacterPda(options.authorization.profile, game);
-    if (stake.ownerCharacter.address !== character) {
-        fail(`Claim Stake ${stake.address} does not belong to authorization Profile ${options.authorization.profile}'s canonical Character ${character}. Choose an owned Claim Stake, refresh it, and retry.`, stake.address);
-    }
-    const [freshGame, firstAccounts] = await Promise.all([
+    const character = await requireOwnedStake(stake, game, profile);
+    const action = 'deconstruction';
+    const [freshGame, { bodyAccount, currentBody, currentStake, stakeAccount }] = await Promise.all([
         readFreshGameClaimStakeConfiguration(ctx),
-        readContextRawAccounts(ctx, [stake.address, stake.body.address]),
+        readOwnedStake(ctx, stake, action),
     ]);
     if (freshGame === undefined) {
         fail(`Configured Game ${game} is missing. Refresh the Game definitions and retry deconstruction.`, game);
     }
-    const stakeAccount = requireAccount(firstAccounts[0], stake.address, `Claim Stake ${stake.address} is missing. Refresh it and retry deconstruction.`);
-    const bodyAccount = requireAccount(firstAccounts[1], stake.body.address, `Celestial Body ${stake.body.address} is missing. Refresh the Claim Stake Body and retry deconstruction.`);
-    const currentStake = claimStakeAccountDefinition.decode(stakeAccount);
-    const currentBody = decodeIndexedCelestialBodyAccount(bodyAccount);
-    if (currentStake.game !== game ||
-        currentStake.body !== stake.body.address ||
-        currentStake.ownerCharacter !== character ||
-        currentStake.claimStakeDefinitionId !== stake.claimStakeDefinitionId ||
-        currentStake.claimStakeDefinitionSeqId !==
-            stake.claimStakeDefinitionSeqId ||
-        currentStake.buildingDefinitionSeqId !== stake.buildingDefinitionSeqId ||
-        currentStake.systemSeqId !== stake.systemSeqId ||
-        !sameQuantities(currentStake.buildings, stake.buildings) ||
+    if (!sameOwnedStake(currentStake, stake, game, character) ||
         currentStake.state.kind !== 'active') {
         fail(`Claim Stake ${stake.address} changed or does not match its loaded ownership, Body, definitions, buildings, active state, or System generation. Refresh it and retry deconstruction.`, stake.address);
     }
-    if (currentBody.kind !== 'planet' ||
-        currentBody.game !== game ||
-        currentBody.systemSequenceId !== stake.systemSeqId ||
-        (await deriveCelestialBodyAddress(game, currentBody.id)) !==
-            stake.body.address) {
-        fail(`Celestial Body ${stake.body.address} does not match the Claim Stake's configured Game, canonical Planet identity, or System generation. Refresh the Body and Claim Stake before retrying deconstruction.`, stake.body.address);
-    }
+    const planet = await requireStakePlanet(currentBody, stake, game, action);
+    const { system } = planet;
     if (freshGame.data.claimStakes.sequenceId !== stake.claimStakeDefinitionSeqId) {
         fail(`Claim Stake ${stake.address} definition generation is stale against the current Game catalog. Refresh the Claim Stake and definitions to rule out stale local data. If the on-chain generation still differs, use a Claim Stake matching the current catalog before retrying deconstruction.`, stake.address);
     }
@@ -1104,18 +1066,19 @@ export async function planDeconstructClaimStake(ctx, stake, input) {
         bundledHub.hubValue !== claimDefinition.hubValue ||
         bundledHub.minimumTier !== claimDefinition.tier ||
         bundledHub.constructionCost.length !== 0) {
+        // Only a building with a construction cost is player-funded; a zero-cost
+        // hub from another definition family is a foreign bundled hub.
         const hasPlayerFundedBuilding = stake.buildings.some((building) => {
             const definition = definitions.get(building.buildingId);
-            return (definition === undefined ||
-                definition.hubValue !== claimDefinition.hubValue ||
-                definition.minimumTier !== claimDefinition.tier ||
-                definition.constructionCost.length !== 0);
+            return (definition !== undefined && definition.constructionCost.length !== 0);
         });
         fail(hasPlayerFundedBuilding
             ? `Claim Stake ${stake.address} still contains a player-funded building. Remove and finalize every player-funded building so only its verified bundled hub remains before retrying deconstruction.`
-            : `Claim Stake ${stake.address} does not contain exactly one verified bundled hub. Refresh it and restore the definition-compatible bundled hub before retrying deconstruction.`, stake.address);
+            : bundledHub === undefined
+                ? `Claim Stake ${stake.address} does not contain exactly one verified bundled hub. Refresh it and restore the definition-compatible bundled hub before retrying deconstruction.`
+                : `Claim Stake ${stake.address} holds ${bundledHub.name} (${String(bundledHub.id)}), which is not the zero-cost ${claimDefinition.tier} bundled hub for Claim Stake definition ${String(claimDefinition.id)} (${claimDefinition.name}). Refresh the Claim Stake and Game definitions so the recorded hub matches its definition before retrying deconstruction.`, stake.address);
     }
-    const groups = currentBody.details.claimedPlots.filter(({ key }) => key === claimDefinition.id);
+    const groups = planet.details.claimedPlots.filter(({ key }) => key === claimDefinition.id);
     if (groups.length !== 1) {
         fail(`Claim Stake definition ${String(claimDefinition.id)} does not have exactly one coherent group in Planet ${stake.body.address}'s Claim Stake Body data. Refresh the Body before retrying deconstruction.`, stake.body.address);
     }
@@ -1132,7 +1095,7 @@ export async function planDeconstructClaimStake(ctx, stake, input) {
     }
     const claimStakeIndex = chronologyMatches[0].index;
     const tierIndex = TIER_INDEX[claimDefinition.tier];
-    const plotCapacities = currentBody.details.claimStakePlots.map((row) => row[tierIndex]);
+    const plotCapacities = planet.details.claimStakePlots.map((row) => row[tierIndex]);
     if (plotCapacities.some((capacity, index) => index > 0 && capacity < plotCapacities[index - 1])) {
         fail(`Planet ${stake.body.address} Claim Stake plot capacity is not coherent across Starbase levels for definition tier ${claimDefinition.tier}. Refresh the Body and verify the pinned binding version before retrying deconstruction.`, stake.body.address);
     }
@@ -1141,41 +1104,18 @@ export async function planDeconstructClaimStake(ctx, stake, input) {
     }
     const plotLevelIndex = plotCapacities.findIndex((capacity) => claimStakeIndex < capacity);
     const claimStakeLevel = CLAIM_STAKE_PLOT_LEVELS[plotLevelIndex];
-    const system = currentBody.system;
-    const player = await deriveStarbasePlayerAddress(system, character);
-    const [characterCandidate, systemCandidate, playerCandidate] = await readContextRawAccounts(ctx, [character, system, player]);
-    const characterAccount = requireAccount(characterCandidate, character, `Canonical Character ${character} is missing. Refresh the Profile Character and retry deconstruction.`);
-    const systemAccount = requireAccount(systemCandidate, system, `Star System ${system} is missing. Refresh the Claim Stake's System and retry deconstruction.`);
-    const playerAccount = requireAccount(playerCandidate, player, `Starbase Player ${player} is missing for authorization Profile ${options.authorization.profile}. Register or refresh it in the Claim Stake's System before retrying deconstruction.`);
-    const currentCharacter = characterAccountDefinition.decode(characterAccount);
-    const currentSystem = starSystemAccountDefinition.decode(systemAccount);
-    const currentPlayer = starbasePlayerAccountDefinition.decode(playerAccount);
-    if (currentCharacter.playerProfile !== options.authorization.profile ||
-        currentCharacter.game !== game) {
-        fail(`Character ${character} does not match authorization Profile ${options.authorization.profile} and configured Game ${game}. Refresh the Character and retry deconstruction.`, character);
-    }
-    if (currentSystem.game !== game ||
-        currentSystem.sequenceId !== stake.systemSeqId ||
-        currentSystem.starbase === undefined ||
-        !currentSystem.celestialBodyAddresses.includes(stake.body.address) ||
-        (await deriveStarSystemAddress(game, currentSystem.systemId)) !== system) {
-        fail(`Star System ${system} does not match the configured Game, canonical identity, Claim Stake generation, or an active nested Starbase. Refresh the System and retry deconstruction.`, system);
-    }
-    if (currentPlayer.playerProfile !== options.authorization.profile ||
-        currentPlayer.character !== character ||
-        currentPlayer.system !== system) {
-        fail(`Starbase Player ${player} does not match the authorization Profile, canonical Character, and Claim Stake System. Refresh it and retry deconstruction.`, player);
-    }
+    const { currentSystem, extraAccounts: [characterCandidate], player, playerAccount, systemAccount, } = await readStakeStarbase(ctx, stake, game, system, character, profile, action, [character]);
+    const { account: characterAccount } = requireProfileCharacter(characterCandidate, character, profile, game, action);
     const description = `Deconstruct Claim Stake ${stake.address} and discard its bundled hub ${bundledHub.name}; rent settlement, cargo return, account closure, and any refund remain chain-authoritative.`;
-    return createPlan({
+    return buildPlannerPlan({
         kind: 'claim-stakes.deconstruct',
         preconditions: await Promise.all([
-            precondition(freshGame.account, `The configured Game retains Claim Stake definition ${String(claimDefinition.id)}, bundled hub ${String(bundledHub.id)}, and their current generations.`),
-            precondition(stakeAccount, `Claim Stake ${stake.address} retains its ownership, active state, definitions, bundled hub, Body, and System generation.`),
-            precondition(bodyAccount, `The Planet retains Claim Stake ${stake.address} at chronology index ${String(claimStakeIndex)} in definition group ${String(claimDefinition.id)}.`),
-            precondition(characterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game.`),
-            precondition(systemAccount, `Star System ${currentSystem.name} retains its configured Game, sequence, nested Starbase, and Claim Stake Body relationship.`),
-            precondition(playerAccount, `Starbase Player ${player} retains its Profile, Character, and System.`),
+            accountStatePrecondition(freshGame.account, `The configured Game retains Claim Stake definition ${String(claimDefinition.id)}, bundled hub ${String(bundledHub.id)}, and their current generations.`),
+            accountStatePrecondition(stakeAccount, `Claim Stake ${stake.address} retains its ownership, active state, definitions, bundled hub, Body, and System generation.`),
+            accountStatePrecondition(bodyAccount, `The Planet retains Claim Stake ${stake.address} at chronology index ${String(claimStakeIndex)} in definition group ${String(claimDefinition.id)}.`),
+            characterPrecondition(characterAccount, profile),
+            systemPrecondition(systemAccount, currentSystem.name),
+            playerPrecondition(playerAccount, player),
         ]),
         steps: [
             {
@@ -1219,86 +1159,34 @@ export async function planDeconstructClaimStake(ctx, stake, input) {
 export async function planTopUpClaimStakeRent(ctx, stake, input) {
     const options = validateTopUpRentOptions(input);
     const game = requireGameAddress(ctx);
+    const { profile } = options.authorization;
     const loadedState = stake.state;
     if (loadedState.kind === 'deactivated') {
         fail(`Claim Stake ${stake.address} is not placed. Refresh it and choose an active Claim Stake or pending building design before topping up rent.`, stake.address);
     }
-    if (stake.game !== game) {
-        fail(`Claim Stake ${stake.address} does not match the configured Game ${game}. Refresh it through this context and retry.`, stake.address);
-    }
-    const character = await findCharacterPda(options.authorization.profile, game);
-    if (stake.ownerCharacter.address !== character) {
-        fail(`Claim Stake ${stake.address} does not belong to authorization Profile ${options.authorization.profile}'s canonical Character ${character}. Choose an owned Claim Stake, refresh it, and retry.`, stake.address);
-    }
-    const firstAccounts = await readContextRawAccounts(ctx, [
-        stake.address,
-        stake.body.address,
-        character,
-    ]);
-    const stakeAccount = requireAccount(firstAccounts[0], stake.address, `Claim Stake ${stake.address} is missing. Refresh it and retry the rent top-up.`);
-    const bodyAccount = requireAccount(firstAccounts[1], stake.body.address, `Celestial Body ${stake.body.address} is missing. Refresh the Claim Stake Body and retry the rent top-up.`);
-    const characterAccount = requireAccount(firstAccounts[2], character, `Canonical Character ${character} is missing. Refresh the Profile Character and retry the rent top-up.`);
-    const currentStake = claimStakeAccountDefinition.decode(stakeAccount);
-    const currentBody = celestialBodyAccountDefinition.decode(bodyAccount);
-    const currentCharacter = characterAccountDefinition.decode(characterAccount);
-    if (currentStake.game !== game ||
-        currentStake.body !== stake.body.address ||
-        currentStake.ownerCharacter !== character ||
-        currentStake.claimStakeDefinitionId !== stake.claimStakeDefinitionId ||
-        currentStake.claimStakeDefinitionSeqId !==
-            stake.claimStakeDefinitionSeqId ||
-        currentStake.buildingDefinitionSeqId !== stake.buildingDefinitionSeqId ||
-        currentStake.systemSeqId !== stake.systemSeqId ||
+    const character = await requireOwnedStake(stake, game, profile);
+    const action = 'the rent top-up';
+    const { bodyAccount, currentBody, currentStake, extraAccounts: [characterCandidate], stakeAccount, } = await readOwnedStake(ctx, stake, action, [character]);
+    if (!sameOwnedStake(currentStake, stake, game, character) ||
         currentStake.rentBalanceRaw !== stake.rentBalanceRaw ||
-        !sameQuantities(currentStake.buildings, stake.buildings) ||
         !sameStakeState(currentStake.state, loadedState)) {
         fail(`Claim Stake ${stake.address} changed or does not match its loaded ownership, Body, definitions, buildings, rent balance, placed state, or System generation. Refresh it and retry the rent top-up.`, stake.address);
     }
-    if (currentBody.kind !== 'planet' ||
-        currentBody.game !== game ||
-        currentBody.systemSequenceId !== stake.systemSeqId ||
-        (await deriveCelestialBodyAddress(game, currentBody.id)) !==
-            stake.body.address) {
-        fail(`Celestial Body ${stake.body.address} does not match the Claim Stake's configured Game, canonical Planet identity, or System generation. Refresh the Body and Claim Stake before retrying the rent top-up.`, stake.body.address);
-    }
-    if (currentCharacter.playerProfile !== options.authorization.profile ||
-        currentCharacter.game !== game) {
-        fail(`Character ${character} does not match authorization Profile ${options.authorization.profile} and configured Game ${game}. Refresh the Character and retry the rent top-up.`, character);
-    }
+    const { system } = await requireStakePlanet(currentBody, stake, game, action);
+    const { account: characterAccount, current: currentCharacter } = requireProfileCharacter(characterCandidate, character, profile, game, action);
     if (currentCharacter.atlasRaw < options.amount) {
         fail(`Character ${character} has only ${String(currentCharacter.atlasRaw)} known raw ATLAS, below the requested ${String(options.amount)} raw rent top-up. Reduce the amount or add ATLAS, refresh the Character, and retry.`, character);
     }
-    const system = currentBody.system;
-    const player = await deriveStarbasePlayerAddress(system, character);
-    const [systemCandidate, playerCandidate] = await readContextRawAccounts(ctx, [
-        system,
-        player,
-    ]);
-    const systemAccount = requireAccount(systemCandidate, system, `Star System ${system} is missing. Refresh the Claim Stake's System and retry the rent top-up.`);
-    const playerAccount = requireAccount(playerCandidate, player, `Starbase Player ${player} is missing for authorization Profile ${options.authorization.profile}. Register or refresh it in the Claim Stake's System before retrying the rent top-up.`);
-    const currentSystem = starSystemAccountDefinition.decode(systemAccount);
-    const currentPlayer = starbasePlayerAccountDefinition.decode(playerAccount);
-    if (currentSystem.game !== game ||
-        currentSystem.sequenceId !== stake.systemSeqId ||
-        currentSystem.starbase === undefined ||
-        !currentSystem.celestialBodyAddresses.includes(stake.body.address) ||
-        (await deriveStarSystemAddress(game, currentSystem.systemId)) !== system) {
-        fail(`Star System ${system} does not match the configured Game, canonical identity, Claim Stake generation, active nested Starbase, or Claim Stake Body relationship. Refresh the System and retry the rent top-up.`, system);
-    }
-    if (currentPlayer.playerProfile !== options.authorization.profile ||
-        currentPlayer.character !== character ||
-        currentPlayer.system !== system) {
-        fail(`Starbase Player ${player} does not match the authorization Profile, canonical Character, and Claim Stake System. Refresh it and retry the rent top-up.`, player);
-    }
+    const { currentSystem, player, playerAccount, systemAccount } = await readStakeStarbase(ctx, stake, game, system, character, profile, action);
     const description = `Top up Claim Stake ${stake.address} rent with ${String(options.amount)} raw rent units; rent arithmetic remains chain-authoritative.`;
-    return createPlan({
+    return buildPlannerPlan({
         kind: 'claim-stakes.top-up-rent',
         preconditions: await Promise.all([
-            precondition(stakeAccount, `Claim Stake ${stake.address} retains its ownership, rent balance, placed state, Body, and System generation.`),
-            precondition(bodyAccount, `The Claim Stake Planet remains assigned to System ${system} at the current generation.`),
-            precondition(characterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} with at least ${String(options.amount)} known raw ATLAS.`),
-            precondition(systemAccount, `Star System ${currentSystem.name} retains its configured Game, sequence, nested Starbase, and Claim Stake Body relationship.`),
-            precondition(playerAccount, `Starbase Player ${player} retains its Profile, Character, and System.`),
+            accountStatePrecondition(stakeAccount, `Claim Stake ${stake.address} retains its ownership, rent balance, placed state, Body, and System generation.`),
+            planetPrecondition(bodyAccount, system),
+            accountStatePrecondition(characterAccount, `The canonical Character remains assigned to Profile ${profile} with at least ${String(options.amount)} known raw ATLAS.`),
+            systemPrecondition(systemAccount, currentSystem.name),
+            playerPrecondition(playerAccount, player),
         ]),
         steps: [
             {
@@ -1357,6 +1245,9 @@ function describeCargoRequests(direction, requests) {
  * FleetCrewBinding. The chain remains authoritative for range, duration,
  * permission bits, concurrent state changes, and transfer arithmetic.
  *
+ * Requires Game 2 and its existing canonical Claim Stake XP ledger.
+ * Missing XP state must be repaired outside this Plan; no accounts are created.
+ *
  * @example
  * ```ts
  * declare const ctx: SageContext;
@@ -1374,119 +1265,53 @@ function describeCargoRequests(direction, requests) {
 export async function planStartClaimStakeFleetTransfer(ctx, fleet, stake, input) {
     const options = validateStartFleetTransferOptions(input);
     const game = requireGameAddress(ctx);
+    const { profile } = options.authorization;
     if (fleet.game !== game || stake.game !== game) {
         fail(`Fleet ${fleet.address} and Claim Stake ${stake.address} must both belong to configured Game ${game}. Refresh both snapshots through this context and retry.`, fleet.game !== game ? fleet.address : stake.address);
     }
-    if (fleet.ownerProfile.address !== options.authorization.profile) {
-        fail(`Fleet ${fleet.name} belongs to Profile ${fleet.ownerProfile.address}, not authorization Profile ${options.authorization.profile}. Use the owning Profile, refresh the Fleet, and retry.`, fleet.address);
+    if (fleet.ownerProfile.address !== profile) {
+        fail(`Fleet ${fleet.name} belongs to Profile ${fleet.ownerProfile.address}, not authorization Profile ${profile}. Use the owning Profile, refresh the Fleet, and retry.`, fleet.address);
     }
     if (fleet.state.kind !== 'idle') {
         fail(`Fleet ${fleet.name} is ${fleet.state.kind}, but starting a Claim Stake transfer requires an idle Fleet. Return it to idle state, refresh it, and retry.`, fleet.address);
     }
+    const crewFailure = `Fleet ${fleet.name} has no valid normalized crew and cannot start a Claim Stake transfer. Crew the Fleet, refresh it, and retry.`;
     if (!Number.isSafeInteger(fleet.crewCount) || fleet.crewCount <= 0) {
-        fail(`Fleet ${fleet.name} has no valid normalized crew and cannot start a Claim Stake transfer. Crew the Fleet, refresh it, and retry.`, fleet.address);
+        fail(crewFailure, fleet.address);
     }
     if (stake.state.kind !== 'active') {
         fail(`Claim Stake ${stake.address} is ${stake.state.kind}, but starting a Fleet transfer requires an active Claim Stake. Activate or restore it, refresh it, and retry.`, stake.address);
     }
-    const character = await findCharacterPda(options.authorization.profile, game);
-    if (stake.ownerCharacter.address !== character) {
-        fail(`Claim Stake ${stake.address} does not belong to authorization Profile ${options.authorization.profile}'s canonical Character ${character}. Choose an owned active Claim Stake, refresh it, and retry.`, stake.address);
-    }
-    const [fleetCandidate, stakeCandidate, bodyCandidate, characterCandidate] = await readContextRawAccounts(ctx, [
-        fleet.address,
-        stake.address,
-        stake.body.address,
-        character,
-    ]);
-    const fleetAccount = requireAccount(fleetCandidate, fleet.address, `Fleet ${fleet.name} is missing. Refresh it and retry the Claim Stake transfer.`);
-    const stakeAccount = requireAccount(stakeCandidate, stake.address, `Claim Stake ${stake.address} is missing. Refresh it and retry the Fleet transfer.`);
-    const bodyAccount = requireAccount(bodyCandidate, stake.body.address, `Celestial Body ${stake.body.address} is missing. Refresh the Claim Stake Body and retry the Fleet transfer.`);
-    const characterAccount = requireAccount(characterCandidate, character, `Canonical Character ${character} is missing. Refresh the Profile Character and retry the Claim Stake transfer.`);
+    const character = await requireOwnedStake(stake, game, profile);
+    const action = 'the Fleet transfer';
+    const { bodyAccount, currentBody, currentStake, extraAccounts: [fleetCandidate, characterCandidate], stakeAccount, } = await readOwnedStake(ctx, stake, action, [fleet.address, character]);
+    const fleetAccount = requireAccount(fleetCandidate, fleet.address, `Fleet ${fleet.name} is missing. Refresh it and retry the Fleet transfer.`);
     const currentFleet = fleetAccountDefinition.decode(fleetAccount);
-    const currentStake = claimStakeAccountDefinition.decode(stakeAccount);
-    const currentBody = celestialBodyAccountDefinition.decode(bodyAccount);
-    const currentCharacter = characterAccountDefinition.decode(characterAccount);
     if (!Number.isSafeInteger(currentFleet.crewCount) ||
         currentFleet.crewCount <= 0) {
-        fail(`Fleet ${fleet.name} has no valid normalized crew and cannot start a Claim Stake transfer. Crew the Fleet, refresh it, and retry.`, fleet.address);
+        fail(crewFailure, fleet.address);
     }
-    if (currentFleet.game !== game ||
-        currentFleet.ownerProfile !== options.authorization.profile ||
-        currentFleet.name !== fleet.name ||
+    if (!sameTransferFleet(currentFleet, fleet, game, profile) ||
         currentFleet.state.kind !== 'idle' ||
         currentFleet.crewCount !== fleet.crewCount ||
-        (await deriveFleetAddress(currentFleet)) !== fleet.address ||
-        currentFleet.ammoBank.cargoId !== fleet.ammo.id ||
-        currentFleet.ammoBank.amount !== fleet.ammo.amount ||
-        currentFleet.fuelTank.cargoId !== fleet.fuel.id ||
-        currentFleet.fuelTank.amount !== fleet.fuel.amount ||
-        currentFleet.cargoHold.storageCost !== fleet.cargoHold.storageCost ||
-        !sameCargoAmounts(currentFleet.cargoHold.amounts, fleet.cargoHold.items) ||
-        currentFleet.stats.cargo.ammoCapacity !== fleet.capacities.ammo.total ||
-        currentFleet.stats.cargo.fuelCapacity !== fleet.capacities.fuel.total ||
-        currentFleet.stats.cargo.cargoCapacity !== fleet.capacities.cargo.total) {
+        (await deriveFleetAddress(currentFleet)) !== fleet.address) {
         fail(`Fleet ${fleet.name} changed or no longer matches its loaded Game, owner, canonical address, name, idle state, normalized crew, cargo, or capacities. Refresh it and create a new Claim Stake transfer Plan.`, fleet.address);
     }
-    if (currentStake.game !== game ||
-        currentStake.ownerCharacter !== character ||
-        currentStake.body !== stake.body.address ||
-        currentStake.systemSeqId !== stake.systemSeqId ||
-        currentStake.state.kind !== 'active' ||
-        currentStake.production.cargoPod.storageCost !==
-            stake.resources.capacity.usedRaw ||
-        currentStake.production.resourceCapacityRaw !==
-            stake.resources.capacity.totalRaw ||
-        !sameCargoAmounts(currentStake.production.cargoPod.amounts, stake.resources.inventory.items.map(({ id, quantityRaw }) => ({
-            amount: quantityRaw,
-            id,
-        })))) {
+    if (!sameTransferStake(currentStake, stake, game, character)) {
         fail(`Claim Stake ${stake.address} changed or no longer matches its loaded Game, owner, Body, active state, resources, capacity, or System generation. Refresh it and create a new Fleet transfer Plan.`, stake.address);
     }
-    if (currentBody.kind !== 'planet' ||
-        currentBody.game !== game ||
-        currentBody.systemSequenceId !== stake.systemSeqId ||
-        (await deriveCelestialBodyAddress(game, currentBody.id)) !==
-            stake.body.address) {
-        fail(`Celestial Body ${stake.body.address} does not match the Claim Stake's configured Game, canonical Planet identity, or System generation. Refresh the Body and Claim Stake before retrying the Fleet transfer.`, stake.body.address);
-    }
-    if (currentCharacter.playerProfile !== options.authorization.profile ||
-        currentCharacter.game !== game) {
-        fail(`Character ${character} does not match authorization Profile ${options.authorization.profile} and configured Game ${game}. Refresh the Character and retry the Claim Stake transfer.`, character);
-    }
-    const system = currentBody.system;
-    const player = await deriveStarbasePlayerAddress(system, character);
-    const currencyCache = await deriveCurrencyCacheAddress(game);
-    const crewBinding = await deriveFleetCrewBindingAddress(fleet.address);
-    const [systemCandidate, playerCandidate, currencyCandidate, crewCandidate] = await readContextRawAccounts(ctx, [
-        system,
-        player,
-        currencyCache,
-        crewBinding,
+    const { system } = await requireStakePlanet(currentBody, stake, game, action);
+    const { account: characterAccount } = requireProfileCharacter(characterCandidate, character, profile, game, action);
+    const [currencyCache, crewBinding] = await Promise.all([
+        claimStakeCurrencyCache(game),
+        deriveFleetCrewBindingAddress(fleet.address),
     ]);
-    const systemAccount = requireAccount(systemCandidate, system, `Star System ${system} is missing. Refresh the Claim Stake System and retry the Fleet transfer.`);
-    const playerAccount = requireAccount(playerCandidate, player, `Starbase Player ${player} is missing for authorization Profile ${options.authorization.profile}. Register or refresh it in the Claim Stake System before retrying the Fleet transfer.`);
-    const currencyAccount = requireAccount(currencyCandidate, currencyCache, `Canonical CurrencyCache ${currencyCache} is missing for configured Game ${game}. Refresh the Game currency configuration and retry the Fleet transfer.`);
-    const currentSystem = starSystemAccountDefinition.decode(systemAccount);
-    const currentPlayer = starbasePlayerAccountDefinition.decode(playerAccount);
-    if (currentSystem.game !== game ||
-        currentSystem.sequenceId !== stake.systemSeqId ||
-        currentSystem.starbase === undefined ||
-        !currentSystem.celestialBodyAddresses.includes(stake.body.address) ||
-        (await deriveStarSystemAddress(game, currentSystem.systemId)) !== system) {
-        fail(`Star System ${system} does not match the configured Game, canonical identity, Claim Stake generation, nested Starbase, or Claim Stake Body relationship. Refresh the System and retry the Fleet transfer.`, system);
-    }
-    if (currentPlayer.playerProfile !== options.authorization.profile ||
-        currentPlayer.character !== character ||
-        currentPlayer.system !== system) {
-        fail(`Starbase Player ${player} does not match the authorization Profile, canonical Character, and Claim Stake System. Refresh it and retry the Fleet transfer.`, player);
-    }
-    validateCurrencyCache(currencyAccount, game, currencyCache, 'the Claim Stake Fleet transfer');
+    const { currentSystem, extraAccounts: [currencyCandidate, crewCandidate], player, playerAccount, systemAccount, } = await readStakeStarbase(ctx, stake, game, system, character, profile, action, [currencyCache, crewBinding]);
+    const currencyGuard = await requireCurrencyCache(currencyCandidate, currencyCache, game, action, 'Claim Stake Fleet transfer');
     if (crewCandidate !== undefined) {
         const currentCrewBinding = fleetCrewBindingAccountDefinition.decode(crewCandidate);
         if (crewCandidate.address !== crewBinding ||
-            currentCrewBinding.fleet !== fleet.address ||
-            currentCrewBinding.ownerProfile !== options.authorization.profile) {
+            !matchesFleetCrewBindingIdentity(currentCrewBinding, fleet.address, profile)) {
             fail(`FleetCrewBinding ${crewCandidate.address} does not match Fleet ${fleet.address}, its owner Profile, or its canonical PDA. Refresh the Fleet crew registration or remove the invalid binding before retrying.`, crewCandidate.address);
         }
     }
@@ -1509,37 +1334,43 @@ export async function planStartClaimStakeFleetTransfer(ctx, fleet, stake, input)
     const loadCargoStorage = options.load
         .filter(({ cargoId }) => cargoId !== currentFleet.ammoBank.cargoId &&
         cargoId !== currentFleet.fuelTank.cargoId)
-        .reduce((total, { amount, cargoId }) => total + amount * BigInt(definitions.get(cargoId).storageCost), 0n);
+        .reduce((total, { amount, cargoId }) => total +
+        cargoStorageUnits(amount, definitions.get(cargoId).storageCost), 0n);
     requireTransferCapacity(`Fleet ${fleet.name} ammo destination`, fleet.address, currentFleet.ammoBank.amount, loadAmmo, currentFleet.stats.cargo.ammoCapacity);
     requireTransferCapacity(`Fleet ${fleet.name} fuel destination`, fleet.address, currentFleet.fuelTank.amount, loadFuel, currentFleet.stats.cargo.fuelCapacity);
     requireTransferCapacity(`Fleet ${fleet.name} cargo destination`, fleet.address, currentFleet.cargoHold.storageCost, loadCargoStorage, currentFleet.stats.cargo.cargoCapacity);
-    const unloadStorage = options.unload.reduce((total, { amount, cargoId }) => total + amount * BigInt(definitions.get(cargoId).storageCost), 0n);
+    const unloadStorage = options.unload.reduce((total, { amount, cargoId }) => total + cargoStorageUnits(amount, definitions.get(cargoId).storageCost), 0n);
     requireTransferCapacity(`Claim Stake ${stake.address} resource destination`, stake.address, currentStake.production.cargoPod.storageCost, unloadStorage, currentStake.production.resourceCapacityRaw);
     const descriptions = [
         ...describeCargoRequests('load', options.load),
         ...describeCargoRequests('unload', options.unload),
     ];
     const description = `Start fleet ${fleet.name}'s transfer to Claim Stake ${stake.address}: ${descriptions.join('; ')}. Range and transfer duration remain chain-authoritative.`;
-    return createPlan({
+    const xp = await resolveClaimStakeXp(ctx, game, stake.address);
+    return buildPlannerPlan({
         kind: 'claim-stakes.start-fleet-transfer',
-        preconditions: await Promise.all([
-            precondition(fleetAccount, `Fleet ${fleet.name} retains its owner, name, idle state, normalized crew, cargo balances, and destination capacities.`),
-            precondition(stakeAccount, `Claim Stake ${stake.address} retains its owner, active state, cargo balances, destination capacity, Body, and System generation.`),
-            precondition(bodyAccount, `The Claim Stake Planet remains assigned to System ${system} at the current generation.`),
-            precondition(characterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game.`),
-            precondition(systemAccount, `Star System ${currentSystem.name} retains its configured Game, sequence, nested Starbase, and Claim Stake Body relationship.`),
-            precondition(playerAccount, `Starbase Player ${player} retains its Profile, Character, and System.`),
-            precondition(currencyAccount, 'The canonical CurrencyCache remains assigned to the configured Game.'),
-            ...(crewCandidate === undefined
-                ? []
-                : [
-                    precondition(crewCandidate, `Fleet ${fleet.name}'s optional FleetCrewBinding remains assigned to the Fleet and owner Profile.`),
-                ]),
-        ]),
+        preconditions: [
+            xp.guard,
+            ...(await Promise.all([
+                accountStatePrecondition(fleetAccount, `Fleet ${fleet.name} retains its owner, name, idle state, normalized crew, cargo balances, and destination capacities.`),
+                accountStatePrecondition(stakeAccount, `Claim Stake ${stake.address} retains its owner, active state, cargo balances, destination capacity, Body, and System generation.`),
+                planetPrecondition(bodyAccount, system),
+                characterPrecondition(characterAccount, profile),
+                systemPrecondition(systemAccount, currentSystem.name),
+                playerPrecondition(playerAccount, player),
+                ...(crewCandidate === undefined
+                    ? []
+                    : [
+                        accountStatePrecondition(crewCandidate, `Fleet ${fleet.name}'s optional FleetCrewBinding remains assigned to the Fleet and owner Profile.`),
+                    ]),
+            ])),
+            currencyGuard,
+        ],
         steps: [
             {
                 describes: description,
                 instruction: adaptStartClaimStakeFleetTransferInstruction({
+                    ...xp.accounts,
                     authorization: options.authorization,
                     celestialBody: stake.body.address,
                     character,
@@ -1606,10 +1437,7 @@ export async function planRecoverClaimStakeFleetTransfer(ctx, fleet, stake, inpu
     if (options.atUnixSeconds < fleet.state.endAtUnixSeconds) {
         fail(`Fleet ${fleet.name}'s Claim Stake transfer lock has not elapsed at Unix timestamp ${String(options.atUnixSeconds)}; it ends at ${String(fleet.state.endAtUnixSeconds)}. Wait until the lock elapses, provide a current timestamp, and retry recovery.`, fleet.address);
     }
-    const character = await findCharacterPda(options.authorization.profile, game);
-    if (stake.ownerCharacter.address !== character) {
-        fail(`Claim Stake ${stake.address} does not belong to authorization Profile ${options.authorization.profile}'s canonical Character ${character}. Supply the owned current Claim Stake and retry recovery.`, stake.address);
-    }
+    const character = await requireOwnedStake(stake, game, options.authorization.profile);
     const [fleetCandidate, stakeCandidate] = await readContextRawAccounts(ctx, [
         fleet.address,
         stake.address,
@@ -1618,40 +1446,17 @@ export async function planRecoverClaimStakeFleetTransfer(ctx, fleet, stake, inpu
     const stakeAccount = requireAccount(stakeCandidate, stake.address, `Claim Stake ${stake.address} is missing. Refresh it and retry Fleet transfer recovery.`);
     const currentFleet = fleetAccountDefinition.decode(fleetAccount);
     const currentStake = claimStakeAccountDefinition.decode(stakeAccount);
-    if (currentFleet.game !== game ||
-        currentFleet.ownerProfile !== options.authorization.profile ||
-        currentFleet.name !== fleet.name ||
+    if (!sameTransferFleet(currentFleet, fleet, game, options.authorization.profile) ||
         currentFleet.state.kind !== 'claimStakeTransfer' ||
         currentFleet.state.claimStake !== stake.address ||
         currentFleet.state.planet !== stake.body.address ||
         currentFleet.state.endAtUnixSeconds !== fleet.state.endAtUnixSeconds ||
         !sameCargoAmounts(currentFleet.state.load, fleet.state.load) ||
         !sameCargoAmounts(currentFleet.state.unload, fleet.state.unload) ||
-        (await deriveFleetAddress(currentFleet)) !== fleet.address ||
-        currentFleet.ammoBank.cargoId !== fleet.ammo.id ||
-        currentFleet.ammoBank.amount !== fleet.ammo.amount ||
-        currentFleet.fuelTank.cargoId !== fleet.fuel.id ||
-        currentFleet.fuelTank.amount !== fleet.fuel.amount ||
-        currentFleet.cargoHold.storageCost !== fleet.cargoHold.storageCost ||
-        !sameCargoAmounts(currentFleet.cargoHold.amounts, fleet.cargoHold.items) ||
-        currentFleet.stats.cargo.ammoCapacity !== fleet.capacities.ammo.total ||
-        currentFleet.stats.cargo.fuelCapacity !== fleet.capacities.fuel.total ||
-        currentFleet.stats.cargo.cargoCapacity !== fleet.capacities.cargo.total) {
+        (await deriveFleetAddress(currentFleet)) !== fleet.address) {
         fail(`Fleet ${fleet.name} changed or no longer matches its loaded owner, Game, canonical address, Claim Stake transfer snapshot, cargo, or capacities. Refresh it and retry recovery.`, fleet.address);
     }
-    if (currentStake.game !== game ||
-        currentStake.ownerCharacter !== character ||
-        currentStake.body !== stake.body.address ||
-        currentStake.systemSeqId !== stake.systemSeqId ||
-        currentStake.state.kind !== 'active' ||
-        currentStake.production.cargoPod.storageCost !==
-            stake.resources.capacity.usedRaw ||
-        currentStake.production.resourceCapacityRaw !==
-            stake.resources.capacity.totalRaw ||
-        !sameCargoAmounts(currentStake.production.cargoPod.amounts, stake.resources.inventory.items.map(({ id, quantityRaw }) => ({
-            amount: quantityRaw,
-            id,
-        })))) {
+    if (!sameTransferStake(currentStake, stake, game, character)) {
         fail(`Claim Stake ${stake.address} changed or no longer matches its loaded owner, Game, Body, active state, resources, capacity, or System generation. Refresh it and retry Fleet transfer recovery.`, stake.address);
     }
     let reason;
@@ -1695,8 +1500,10 @@ export async function planRecoverClaimStakeFleetTransfer(ctx, fleet, stake, inpu
         const loadCargoStorage = currentFleet.state.load
             .filter(({ cargoId }) => cargoId !== currentFleet.ammoBank.cargoId &&
             cargoId !== currentFleet.fuelTank.cargoId)
-            .reduce((total, { amount, cargoId }) => total + amount * BigInt(queuedDefinitions.get(cargoId).storageCost), 0n);
-        const unloadStorage = currentFleet.state.unload.reduce((total, { amount, cargoId }) => total + amount * BigInt(queuedDefinitions.get(cargoId).storageCost), 0n);
+            .reduce((total, { amount, cargoId }) => total +
+            cargoStorageUnits(amount, queuedDefinitions.get(cargoId).storageCost), 0n);
+        const unloadStorage = currentFleet.state.unload.reduce((total, { amount, cargoId }) => total +
+            cargoStorageUnits(amount, queuedDefinitions.get(cargoId).storageCost), 0n);
         if (currentFleet.ammoBank.amount + loadAmmo >
             currentFleet.stats.cargo.ammoCapacity) {
             reason = 'Fleet ammo destination overflow';
@@ -1718,15 +1525,15 @@ export async function planRecoverClaimStakeFleetTransfer(ctx, fleet, stake, inpu
         fail(`Fleet ${fleet.name}'s Claim Stake transfer is currently executable. Use the permissionless normal exit path; recovery is only for a locally proven non-executable transfer.`, fleet.address);
     }
     const description = `Recover fleet ${fleet.name} from its stuck Claim Stake transfer (${reason}); no cargo moves and the Fleet returns to idle.`;
-    return createPlan({
+    return buildPlannerPlan({
         kind: 'claim-stakes.recover-fleet-transfer',
         preconditions: await Promise.all([
-            precondition(fleetAccount, `Fleet ${fleet.name} retains its owner and exact elapsed, non-executable Claim Stake transfer snapshot.`),
-            precondition(stakeAccount, `Claim Stake ${stake.address} remains active with the current owner, cargo, and capacity used to prove non-executability.`),
+            accountStatePrecondition(fleetAccount, `Fleet ${fleet.name} retains its owner and exact elapsed, non-executable Claim Stake transfer snapshot.`),
+            accountStatePrecondition(stakeAccount, `Claim Stake ${stake.address} remains active with the current owner, cargo, and capacity used to prove non-executability.`),
             ...(gameAccount === undefined
                 ? []
                 : [
-                    precondition(gameAccount, `Game ${game} retains the cargo definitions used to prove the transfer is non-executable.`),
+                    accountStatePrecondition(gameAccount, `Game ${game} retains the cargo definitions used to prove the transfer is non-executable.`),
                 ]),
         ]),
         steps: [