@aephia/atlas-kit 0.4.0 → 0.6.0-next.1

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

@@ -0,0 +1,1747 @@
+import { getAddressEncoder, getBytesEncoder, getProgramDerivedAddress, 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 { readFreshGameClaimStakeConfiguration, } from '../../registry/claim-stakes.js';
+import { characterAccountDefinition, findCharacterPda, } from '../../internal/c4/identity.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 { 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 { 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 { readFreshGameCargoDefinitions } from '../../registry/cargo.js';
+import { resolveCargo } from '../../registry/index.js';
+const U64_MAX = (1n << 64n) - 1n;
+const U16_MAX = 65_535;
+const I32_MAX = 2_147_483_647;
+const I32_MIN_MAGNITUDE = 2_147_483_648;
+const U32_MAX = 4_294_967_295;
+const LEVEL_INDEX = Object.freeze({
+    'level-0': 0,
+    'level-1': 1,
+    'level-2': 2,
+    'level-3': 3,
+    'level-4': 4,
+    'level-5': 5,
+    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,
+]);
+const TIER_INDEX = Object.freeze({
+    one: 0,
+    two: 1,
+    three: 2,
+    four: 3,
+    five: 4,
+});
+function invalid(field, value, acceptedRange, remedy) {
+    throw new InvalidActionInputError(field, value, acceptedRange, remedy);
+}
+function fail(message, address) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', message, { address });
+}
+function record(value, field) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return invalid(field, value, 'a plain object', `Provide ${field} as the documented object before retrying.`);
+    }
+    return value;
+}
+function exactKeys(value, field, required, optional = []) {
+    const accepted = new Set([...required, ...optional]);
+    const missing = required.find((key) => !Object.hasOwn(value, key));
+    const unexpected = Object.keys(value).find((key) => !accepted.has(key));
+    if (missing !== undefined || unexpected !== undefined) {
+        invalid(field, missing ?? unexpected, `exactly the fields ${[...required, ...optional].join(', ')}`, `Remove unknown fields and provide every required ${field} field before retrying.`);
+    }
+}
+function address(value, field) {
+    if (typeof value !== 'string' || !isAddress(value)) {
+        return invalid(field, value, 'one valid z.ink/Solana account address', `Set ${field} to the documented public account address before retrying.`);
+    }
+    return value;
+}
+function u16(value, field) {
+    if (typeof value !== 'number' ||
+        !Number.isInteger(value) ||
+        value < 0 ||
+        value > U16_MAX) {
+        return invalid(field, value, `an integer from 0 through ${String(U16_MAX)} (unsigned u16)`, `Set ${field} to an exact id from the configured Game catalog before retrying.`);
+    }
+    return value;
+}
+function validateOptions(value) {
+    const options = record(value, 'options');
+    exactKeys(options, 'options', [
+        'authorization',
+        'claimStake',
+        'claimStakeDefinitionId',
+        '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);
+    if (typeof options.initialRentAmount !== 'bigint' ||
+        options.initialRentAmount <= 0n ||
+        options.initialRentAmount > U64_MAX) {
+        invalid('initialRentAmount', options.initialRentAmount, `a positive raw bigint from 1 through ${String(U64_MAX)} (unsigned u64)`, 'Set initialRentAmount to the exact positive raw rent deposit within the instruction codec range.');
+    }
+    return {
+        authorization,
+        claimStake: address(options.claimStake, 'claimStake'),
+        claimStakeDefinitionId: u16(options.claimStakeDefinitionId, 'claimStakeDefinitionId'),
+        hubBuildingId: u16(options.hubBuildingId, 'hubBuildingId'),
+        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 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.');
+    }
+    const changes = [];
+    const seen = new Set();
+    for (let index = 0; index < values.length; index += 1) {
+        if (!Object.hasOwn(values, index)) {
+            invalid('buildingChanges', index, 'a dense array without missing elements', 'Remove array holes and provide each building change explicitly before retrying.');
+        }
+        const field = `buildingChanges[${String(index)}]`;
+        const change = record(values[index], field);
+        exactKeys(change, field, ['buildingId', 'kind', 'quantity']);
+        const buildingId = u16(change.buildingId, `${field}.buildingId`);
+        if (change.kind !== 'add' && change.kind !== 'remove') {
+            invalid(`${field}.kind`, change.kind, 'add or remove', `Set ${field}.kind to the intended building operation before retrying.`);
+        }
+        const maximumQuantity = change.kind === 'remove' ? I32_MIN_MAGNITUDE : I32_MAX;
+        if (typeof change.quantity !== 'number' ||
+            !Number.isInteger(change.quantity) ||
+            !Number.isFinite(change.quantity) ||
+            change.quantity < 1 ||
+            change.quantity > maximumQuantity) {
+            invalid(`${field}.quantity`, change.quantity, `a positive integer from 1 through ${String(maximumQuantity)}`, `Set ${field}.quantity to an exact positive instruction quantity before retrying.`);
+        }
+        if (seen.has(buildingId)) {
+            invalid(`${field}.buildingId`, buildingId, 'one unique building id per change list', 'Combine duplicate building changes into one add or remove entry before retrying.');
+        }
+        seen.add(buildingId);
+        changes.push({
+            buildingId,
+            kind: change.kind,
+            quantity: change.quantity,
+        });
+    }
+    return { authorization, buildingChanges: changes };
+}
+function validateFinalizeBuildingChangeOptions(value) {
+    const options = record(value, 'options');
+    exactKeys(options, 'options', ['authorization']);
+    return { authorization: validateAuthorization(options.authorization) };
+}
+function validateCancelBuildingChangeOptions(value) {
+    const options = record(value, 'options');
+    exactKeys(options, 'options', ['authorization']);
+    return { authorization: validateAuthorization(options.authorization) };
+}
+function validateDeconstructOptions(value) {
+    const options = record(value, 'options');
+    exactKeys(options, 'options', ['authorization']);
+    return { authorization: validateAuthorization(options.authorization) };
+}
+function validateTopUpRentOptions(value) {
+    const options = record(value, 'options');
+    exactKeys(options, 'options', ['amount', 'authorization']);
+    const authorization = validateAuthorization(options.authorization);
+    if (typeof options.amount !== 'bigint' ||
+        options.amount <= 0n ||
+        options.amount > U64_MAX) {
+        invalid('amount', options.amount, `a positive raw bigint from 1 through ${String(U64_MAX)} (unsigned u64)`, 'Set amount to the exact positive raw rent top-up within the instruction codec range.');
+    }
+    return { amount: options.amount, authorization };
+}
+function validateCargoRequests(value, field, seen) {
+    if (!Array.isArray(value)) {
+        invalid(field, value, 'a dense array of exact raw cargo requests', `Provide ${field} as an array, using an empty array when that direction has no cargo.`);
+    }
+    const requests = [];
+    for (let index = 0; index < value.length; index += 1) {
+        const itemField = `${field}[${String(index)}]`;
+        if (!Object.hasOwn(value, index)) {
+            invalid(itemField, undefined, 'a present cargo request', `Remove sparse entries from ${field} before retrying.`);
+        }
+        const item = record(value[index], itemField);
+        exactKeys(item, itemField, ['cargoId', 'amount']);
+        const cargoId = u16(item.cargoId, `${itemField}.cargoId`);
+        if (seen.has(cargoId)) {
+            invalid(`${itemField}.cargoId`, cargoId, 'one unique cargo id across load and unload', 'Combine duplicate quantities into one direction or remove the cancelling request before retrying.');
+        }
+        if (typeof item.amount !== 'bigint' ||
+            item.amount <= 0n ||
+            item.amount > U64_MAX) {
+            invalid(`${itemField}.amount`, item.amount, `a positive raw bigint from 1 through ${String(U64_MAX)} (unsigned u64)`, `Set ${itemField}.amount to an exact positive raw-unit quantity within the instruction codec range.`);
+        }
+        seen.add(cargoId);
+        requests.push({ amount: item.amount, cargoId });
+    }
+    return Object.freeze(requests);
+}
+function validateStartFleetTransferOptions(value) {
+    const options = record(value, 'options');
+    exactKeys(options, 'options', ['authorization', 'load', 'unload']);
+    const authorization = validateAuthorization(options.authorization);
+    const seen = new Set();
+    const load = validateCargoRequests(options.load, 'load', seen);
+    const unload = validateCargoRequests(options.unload, 'unload', seen);
+    if (load.length === 0 && unload.length === 0) {
+        invalid('load/unload', 'both empty', 'at least one exact load or unload request', 'Add cargo to load from the Claim Stake or unload from the Fleet before retrying.');
+    }
+    return { authorization, load, unload };
+}
+function validateRecoverFleetTransferOptions(value) {
+    const options = record(value, 'options');
+    exactKeys(options, 'options', ['atUnixSeconds', 'authorization']);
+    const authorization = validateAuthorization(options.authorization);
+    if (typeof options.atUnixSeconds !== 'bigint' ||
+        options.atUnixSeconds < 0n ||
+        options.atUnixSeconds > U64_MAX) {
+        invalid('atUnixSeconds', options.atUnixSeconds, `a non-negative bigint through ${String(U64_MAX)} (unsigned u64 Unix seconds)`, 'Set atUnixSeconds to the explicit current Unix timestamp before retrying recovery.');
+    }
+    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 ??
+        fail(`Claim Stake definition ${String(id)} is not a member of the configured Game catalog. Choose an exact current definition id, refresh the Game definitions, and retry.`, game));
+}
+function findHub(configuration, id, game) {
+    const hub = configuration.buildings.definitions.find((candidate) => candidate.id === id);
+    return (hub ??
+        fail(`Hub building ${String(id)} is not a member of the configured Game building catalog. Choose an exact current bundled hub id, refresh the Game definitions, and retry.`, game));
+}
+function claimedCount(details, definitionId) {
+    return (details.claimedPlots.find(({ key }) => key === definitionId)?.structures
+        .length ?? 0);
+}
+/** Plans placement of one Claim Stake with its exact bundled hub.
+ *
+ * The planner validates the configured Game/Profile/Character/System/Body
+ * graph, current catalog membership, known plot/cargo/crew availability, and
+ * absence of the caller-created Claim Stake account. It returns one inert Plan;
+ * permissions, placement races, rent arithmetic, and program capacity remain
+ * chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const body: CelestialBodySnapshot;
+ * declare const player: StarbasePlayerSnapshot;
+ * declare const options: PlanPlaceClaimStakeOptions;
+ * const plan = await planPlaceClaimStake(ctx, body, player, options);
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planPlaceClaimStake(ctx, body, player, input) {
+    const options = validateOptions(input);
+    const game = requireGameAddress(ctx);
+    if (body.kind !== 'planet') {
+        fail(`Celestial Body ${body.name} (${body.address}) is an Asteroid, but Claim Stakes require Planet plots. Choose a Planet, refresh it, and retry.`, body.address);
+    }
+    if (body.game !== game) {
+        fail(`Celestial Body ${body.address} does not match the configured Game ${game}. Refresh the Body through this context and retry.`, body.address);
+    }
+    const canonicalBody = await deriveCelestialBodyAddress(game, body.id);
+    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);
+    }
+    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);
+    }
+    const [freshGame, currentAccounts] = await Promise.all([
+        readFreshGameClaimStakeConfiguration(ctx),
+        readContextRawAccounts(ctx, [
+            body.address,
+            player.address,
+            character,
+            body.system.address,
+            options.claimStake,
+        ]),
+    ]);
+    if (freshGame === undefined) {
+        fail(`Configured Game ${game} is missing. Refresh the Game catalog and retry placement.`, game);
+    }
+    const definition = findDefinition(freshGame.data, options.claimStakeDefinitionId, game);
+    const hub = findHub(freshGame.data, options.hubBuildingId, game);
+    if (hub.hubValue !== definition.hubValue ||
+        hub.minimumTier !== definition.tier ||
+        hub.constructionCost.length !== 0) {
+        fail(`Hub building ${hub.id} (${hub.name}) is not the exact zero-cost ${definition.tier} bundled hub for Claim Stake definition ${definition.id} (${definition.name}). Choose the matching bundled hub from the current Game catalog and retry.`, game);
+    }
+    const missingTag = definition.requiredTagIds.find((tag) => !body.details.providedTags.includes(tag));
+    if (missingTag !== undefined) {
+        fail(`Planet ${body.name} (${body.address}) does not provide required Claim Stake tag ${String(missingTag)} for ${definition.name}. Choose an eligible Planet, refresh it, and retry.`, body.address);
+    }
+    const cargo = player.cargo.items.find(({ id }) => id === definition.cargoId);
+    const cargoQuantity = cargo?.quantityRaw ?? 0n;
+    const cargoName = cargo?.name ?? `cargo ${String(definition.cargoId)}`;
+    if (cargoQuantity < 1n) {
+        fail(`Starbase Player ${player.address} has ${String(cargoQuantity)} raw ${cargoName}, but placing ${definition.name} requires one known unit. Add it, refresh the Starbase Player, and retry.`, player.address);
+    }
+    if (player.availableCrew < hub.neededCrew) {
+        fail(`Starbase Player ${player.address} has only ${String(player.availableCrew)} crew available, but bundled hub ${hub.name} requires ${String(hub.neededCrew)}. Free crew, refresh the Starbase Player, and retry.`, player.address);
+    }
+    const [bodyAccount, playerAccount, characterAccount, systemAccount, newStake,] = currentAccounts;
+    if (newStake !== undefined) {
+        fail(`Claim Stake signer address ${options.claimStake} already exists. Generate a fresh address-only Claim Stake signer and retry.`, options.claimStake);
+    }
+    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 currentSystem = starSystemAccountDefinition.decode(currentSystemAccount);
+    const canonicalSystem = await deriveStarSystemAddress(game, currentSystem.systemId);
+    if (canonicalSystem !== body.system.address ||
+        currentSystem.game !== game ||
+        currentSystem.starbase === undefined) {
+        fail(`Star System ${body.system.address} does not match the configured Game, canonical System address, or an active nested Starbase. Refresh the System and retry.`, body.system.address);
+    }
+    if (currentBody.kind !== 'planet' ||
+        currentBody.game !== game ||
+        currentBody.system !== body.system.address ||
+        currentBody.id !== body.id ||
+        currentBody.systemSequenceId !== body.systemSequenceId ||
+        currentBody.systemSequenceId !== currentSystem.sequenceId) {
+        fail(`Celestial Body ${body.address} changed or does not match its configured Game, System, id, Planet kind, or System sequence. Refresh the Body and System and retry.`, body.address);
+    }
+    if (currentPlayer.playerProfile !== options.authorization.profile ||
+        currentPlayer.character !== character ||
+        currentPlayer.system !== body.system.address ||
+        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);
+    }
+    const currentDetails = currentBody.details;
+    const currentMissingTag = definition.requiredTagIds.find((tag) => !currentDetails.providedTags.includes(tag));
+    if (currentMissingTag !== undefined) {
+        fail(`Planet ${body.name} (${body.address}) no longer provides required Claim Stake tag ${String(currentMissingTag)} for ${definition.name}. Refresh it and retry.`, body.address);
+    }
+    const level = LEVEL_INDEX[currentSystem.starbase.level];
+    const tier = TIER_INDEX[definition.tier];
+    const plotLimit = currentDetails.claimStakePlots[level][tier];
+    const usedPlots = claimedCount(currentDetails, definition.id);
+    if (usedPlots >= plotLimit) {
+        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 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({
+        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.`),
+            ])),
+            absentPrecondition(options.claimStake, 'The caller-supplied Claim Stake signer address remains unallocated.'),
+        ],
+        steps: [
+            {
+                describes: description,
+                instruction: adaptPlaceClaimStakeInstruction({
+                    authorization: options.authorization,
+                    celestialBody: body.address,
+                    character,
+                    claimStakeDefinitionId: definition.id,
+                    claimStakeInstance: options.claimStake,
+                    currencyCache,
+                    game,
+                    hubBuildingId: hub.id,
+                    initialRentAmount: options.initialRentAmount,
+                    profileFaction,
+                    systemAndStarbasePlayerStarbasePlayer: player.address,
+                    systemAndStarbasePlayerSystem: body.system.address,
+                }),
+                signers: [options.authorization.authority, options.claimStake],
+            },
+        ],
+        summary: description,
+    });
+}
+function quantities(buildings) {
+    return new Map(buildings.map(({ buildingId, quantity }) => [buildingId, quantity]));
+}
+function sameQuantities(left, right) {
+    const leftById = quantities(left);
+    const rightById = quantities(right);
+    return (leftById.size === left.length &&
+        rightById.size === right.length &&
+        leftById.size === rightById.size &&
+        [...leftById].every(([buildingId, quantity]) => rightById.get(buildingId) === quantity));
+}
+function sameStakeState(left, right) {
+    if (left.kind === 'deactivated')
+        return false;
+    switch (left.kind) {
+        case 'active':
+            return right.kind === 'active';
+        case 'design':
+            return (right.kind === 'design' &&
+                left.sequenceId === right.sequenceId &&
+                sameQuantities(left.buildings, right.buildings));
+    }
+}
+const LEGACY_CONTROLLER_ID = Object.freeze({
+    unaligned: 0,
+    mud: 1,
+    oni: 2,
+    ustur: 3,
+});
+function buildingDescription(change, name) {
+    return `${change.kind} ${String(change.quantity)} ${name}`;
+}
+/** Plans one exact set of additions/removals for an owned active/design Claim Stake.
+ *
+ * The planner verifies the fresh Claim Stake, definition sequences, canonical
+ * Profile/Character/Body/System/Starbase Player graph, optional
+ * FactionOwnership sidecar, building quantities, slots, crew, and known
+ * construction cargo. Rent synchronization and the final concurrent sequence
+ * race remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const stake: ClaimStakeSnapshot;
+ * declare const options: PlanClaimStakeBuildingChangesOptions;
+ * const plan = await planClaimStakeBuildingChanges(ctx, stake, options);
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planClaimStakeBuildingChanges(ctx, stake, input) {
+    const options = validateBuildingChangeOptions(input);
+    const game = requireGameAddress(ctx);
+    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([
+        readFreshGameClaimStakeConfiguration(ctx),
+        readContextRawAccounts(ctx, [stake.address, stake.body.address, 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) ||
+        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),
+        deriveFactionOwnershipAddress(game, 'starbase', system),
+        deriveProfileFactionAddress(options.authorization.profile),
+    ]);
+    const [systemAccountCandidate, playerAccountCandidate, ownershipAccount, profileFactionAccountCandidate,] = await readContextRawAccounts(ctx, [
+        system,
+        player,
+        ownership,
+        profileFaction,
+    ]);
+    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 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 !== 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 ownershipPrecondition;
+    if (ownershipAccount === undefined) {
+        ownershipPrecondition = absentPrecondition(ownership, `The canonical Starbase FactionOwnership ${ownership} remains unallocated so the chain applies its legacy controller gate.`);
+    }
+    else {
+        const currentOwnership = factionOwnershipAccountDefinition.decode(ownershipAccount);
+        if (currentOwnership.game !== game ||
+            currentOwnership.asset.kind !== 'starbase' ||
+            currentOwnership.asset.system !== system ||
+            currentOwnership.capturedSystemSequenceId !== currentSystem.sequenceId) {
+            fail(`FactionOwnership ${ownership} does not match the configured Game, Claim Stake System, or current System generation. Refresh the faction relationship and retry building changes.`, ownership);
+        }
+        controllerFactionId =
+            currentOwnership.controllingFactionId ?? controllerFactionId;
+        ownershipPrecondition = await precondition(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);
+    }
+    if (freshGame.data.claimStakes.sequenceId !== stake.claimStakeDefinitionSeqId ||
+        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 building changes.`, stake.address);
+    }
+    const claimDefinition = freshGame.data.claimStakes.definitions.find(({ id }) => id === stake.claimStakeDefinitionId);
+    if (claimDefinition === undefined) {
+        fail(`Claim Stake definition ${String(stake.claimStakeDefinitionId)} is absent from the current Game catalog. Refresh the Claim Stake and definitions before retrying.`, game);
+    }
+    const sourceBuildings = stake.state.kind === 'design' ? stake.state.buildings : stake.buildings;
+    if (currentStake.state.kind !== stake.state.kind ||
+        (stake.state.kind === 'design' &&
+            (currentStake.state.kind !== 'design' ||
+                currentStake.state.sequenceId !== stake.state.sequenceId ||
+                !sameQuantities(currentStake.state.buildings, stake.state.buildings)))) {
+        fail(`Claim Stake ${stake.address} lifecycle state or exact design sequence changed. Refresh it and retry building changes.`, stake.address);
+    }
+    const sequenceId = stake.state.kind === 'design' ? stake.state.sequenceId : 0;
+    const result = quantities(sourceBuildings);
+    const definitions = new Map(freshGame.data.buildings.definitions.map((definition) => [
+        definition.id,
+        definition,
+    ]));
+    const descriptions = [];
+    for (const change of options.buildingChanges) {
+        const definition = definitions.get(change.buildingId);
+        if (definition === undefined) {
+            fail(`Building ${String(change.buildingId)} has no definition in the current Game catalog. Refresh the definitions and choose a valid building before retrying.`, game);
+        }
+        const current = result.get(change.buildingId) ?? 0;
+        const next = change.kind === 'add'
+            ? current + change.quantity
+            : current - change.quantity;
+        if (next < 0) {
+            fail(`Cannot remove ${String(change.quantity)} ${definition.name} from Claim Stake ${stake.address}; the resulting quantity would underflow from ${String(current)}. Reduce the removal and retry.`, stake.address);
+        }
+        if (next > U32_MAX) {
+            fail(`Building ${definition.name} quantity would overflow unsigned u32 after this addition. Reduce the quantity and retry.`, stake.address);
+        }
+        if (next === 0)
+            result.delete(change.buildingId);
+        else
+            result.set(change.buildingId, next);
+        descriptions.push(buildingDescription(change, definition.name));
+    }
+    let usedSlots = 0;
+    let crewSlots = 0;
+    let neededCrew = 0;
+    let resourceStorageRaw = 0n;
+    const providedTags = new Set(claimDefinition.providedTagIds);
+    for (const [buildingId, quantity] of result) {
+        const definition = definitions.get(buildingId);
+        if (definition === undefined) {
+            fail(`Existing building ${String(buildingId)} has no definition in the current Game catalog. Refresh the Claim Stake and definitions before retrying.`, game);
+        }
+        if (TIER_INDEX[definition.minimumTier] > TIER_INDEX[claimDefinition.tier]) {
+            fail(`Building ${definition.name} requires ${definition.minimumTier}, above Claim Stake ${claimDefinition.name}'s ${claimDefinition.tier} tier. Remove that building from the design before retrying.`, stake.address);
+        }
+        if (definition.hubValue !== 0 &&
+            definition.hubValue !== claimDefinition.hubValue) {
+            fail(`Hub building ${definition.name} does not match Claim Stake ${claimDefinition.name}'s hub value. Choose the matching hub before retrying.`, stake.address);
+        }
+        usedSlots += definition.slots * quantity;
+        crewSlots += definition.crewSlots * quantity;
+        neededCrew += definition.neededCrew * quantity;
+        resourceStorageRaw += definition.resourceStorageRaw * BigInt(quantity);
+        if (neededCrew > U16_MAX) {
+            fail(`The resulting Claim Stake design has ${String(neededCrew)} needed crew, exceeding the ${String(U16_MAX)} maximum representable by its unsigned u16 needed-crew field. Remove crew-requiring buildings and retry.`, stake.address);
+        }
+        if (resourceStorageRaw > U64_MAX) {
+            fail(`The resulting Claim Stake design provides ${String(resourceStorageRaw)} raw resource storage, exceeding the ${String(U64_MAX)} maximum representable by its unsigned u64 resource-storage field. Reduce storage-building quantities and retry.`, stake.address);
+        }
+        definition.providedTagIds.forEach((tag) => providedTags.add(tag));
+    }
+    if (usedSlots > claimDefinition.slots) {
+        fail(`Building changes require ${String(usedSlots)} slots, exceeding Claim Stake ${claimDefinition.name}'s ${String(claimDefinition.slots)} slot capacity. Remove buildings and retry.`, stake.address);
+    }
+    if (neededCrew > crewSlots) {
+        fail(`Building changes require ${String(neededCrew)} crew, exceeding the resulting ${String(crewSlots)} crew capacity. Add crew-slot capacity or remove crew-requiring buildings before retrying.`, stake.address);
+    }
+    for (const [buildingId] of result) {
+        const definition = definitions.get(buildingId);
+        const missingTag = definition.requiredTagIds.find((tag) => !providedTags.has(tag));
+        if (missingTag !== undefined) {
+            fail(`Building ${definition.name} requires tag ${String(missingTag)}, which the resulting Claim Stake design does not provide. Add a compatible building or remove it before retrying.`, stake.address);
+        }
+    }
+    const availableCrew = currentPlayer.totalCrew - currentPlayer.busyCrew;
+    const addedCrew = options.buildingChanges.reduce((total, change) => {
+        const definition = definitions.get(change.buildingId);
+        return (total +
+            (change.kind === 'add' ? definition.neededCrew * change.quantity : 0));
+    }, 0);
+    if (addedCrew > availableCrew) {
+        fail(`Building additions require ${String(addedCrew)} crew, but Starbase Player ${player} has only ${String(availableCrew)} known crew capacity available. Free crew, refresh the Starbase Player, and retry.`, player);
+    }
+    const cargo = new Map(currentStake.production.cargoPod.amounts.map(({ cargoId, amount }) => [
+        cargoId,
+        amount,
+    ]));
+    const constructionCosts = new Map();
+    for (const change of options.buildingChanges) {
+        if (change.kind !== 'add')
+            continue;
+        const definition = definitions.get(change.buildingId);
+        for (const cost of definition.constructionCost) {
+            const required = cost.quantityRaw * BigInt(change.quantity);
+            constructionCosts.set(cost.cargoId, (constructionCosts.get(cost.cargoId) ?? 0n) + required);
+        }
+    }
+    for (const [cargoId, required] of constructionCosts) {
+        const available = cargo.get(cargoId) ?? 0n;
+        if (required > available) {
+            const snapshotItem = stake.resources.inventory.items.find(({ id }) => id === cargoId);
+            fail(`Building construction requires ${String(required)} raw ${snapshotItem?.name ?? `cargo ${String(cargoId)}`}, but Claim Stake ${stake.address} has only ${String(available)} known. Add construction cargo, refresh the Claim Stake, and retry.`, stake.address);
+        }
+    }
+    if (currentStake.production.resourceCapacityRaw !==
+        stake.resources.capacity.totalRaw ||
+        currentStake.production.cargoPod.storageCost !==
+            stake.resources.inventory.usedStorageUnitsRaw) {
+        fail(`Claim Stake ${stake.address} cargo capacity changed from the loaded snapshot. Refresh its resources and retry building changes.`, stake.address);
+    }
+    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 description = `Change buildings on Claim Stake ${stake.address}: ${descriptions.join('; ')}.`;
+    return createPlan({
+        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.`),
+            ])),
+            ownershipPrecondition,
+        ],
+        steps: [
+            {
+                describes: description,
+                instruction: adaptClaimStakeBuildingChangesInstruction({
+                    authorization: options.authorization,
+                    buildingChanges: options.buildingChanges.map(({ buildingId, kind, quantity }) => [buildingId, kind === 'add' ? quantity : -quantity]),
+                    celestialBody: stake.body.address,
+                    claimStakeInstance: stake.address,
+                    currencyCache,
+                    factionOwnership: ownership,
+                    game,
+                    profileFaction,
+                    sequenceId,
+                    starbasePlayer: player,
+                    system,
+                }),
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: description,
+    });
+}
+/** Plans finalization of one owned Claim Stake building design.
+ *
+ * The planner requires a fresh design state, a coherent configured
+ * Game/Character/Planet/System/Starbase Player graph, the canonical
+ * CurrencyCache, and a known positive rent balance. Rent timing and the final
+ * crew/building validation remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const stake: ClaimStakeSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planFinalizeClaimStakeBuildingChanges(ctx, stake, {
+ *   authorization,
+ * });
+ * // The program re-synchronizes rent at execution.
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planFinalizeClaimStakeBuildingChanges(ctx, stake, input) {
+    const options = validateFinalizeBuildingChangeOptions(input);
+    const game = requireGameAddress(ctx);
+    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);
+    }
+    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([
+        readFreshGameClaimStakeConfiguration(ctx),
+        readContextRawAccounts(ctx, [stake.address, stake.body.address, character]),
+    ]);
+    if (freshGame === undefined) {
+        fail(`Configured Game ${game} is missing. Refresh the Game catalog and retry finalization.`, game);
+    }
+    if (freshGame.data.claimStakes.sequenceId !== stake.claimStakeDefinitionSeqId ||
+        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 ||
+        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 description = `Finalize building changes on Claim Stake ${stake.address}.`;
+    return createPlan({
+        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.'),
+        ]),
+        steps: [
+            {
+                describes: description,
+                instruction: adaptFinalizeClaimStakeBuildingChangesInstruction({
+                    authorization: options.authorization,
+                    celestialBody: stake.body.address,
+                    character,
+                    claimStakeInstance: stake.address,
+                    currencyCache,
+                    game,
+                    systemAndStarbasePlayerStarbasePlayer: player,
+                    systemAndStarbasePlayerSystem: system,
+                }),
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: description,
+    });
+}
+/** Plans cancellation of one owned Claim Stake building design.
+ *
+ * The planner requires a fresh design state and a coherent configured
+ * Game/Claim Stake/Planet/System/Starbase Player graph. The program
+ * re-synchronizes rent at execution and returns the Claim Stake to active
+ * state; rent arithmetic and concurrent state transitions remain
+ * chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const stake: ClaimStakeSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planCancelClaimStakeBuildingChanges(ctx, stake, {
+ *   authorization,
+ * });
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planCancelClaimStakeBuildingChanges(ctx, stake, input) {
+    const options = validateCancelBuildingChangeOptions(input);
+    const game = requireGameAddress(ctx);
+    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) ||
+        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 description = `Cancel the pending building design on Claim Stake ${stake.address} and return it to active state.`;
+    return createPlan({
+        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.'),
+        ]),
+        steps: [
+            {
+                describes: description,
+                instruction: adaptCancelClaimStakeBuildingChangesInstruction({
+                    authorization: options.authorization,
+                    celestialBody: stake.body.address,
+                    claimStakeInstance: stake.address,
+                    currencyCache,
+                    game,
+                    starbasePlayer: player,
+                    system,
+                }),
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: description,
+    });
+}
+/** Plans deconstruction of one owned active Claim Stake.
+ *
+ * The planner derives the current Planet chronology index and exact plot bucket
+ * from the Claim Stake definition tier and fresh Body plot matrix. The only
+ * remaining building must be the definition-compatible zero-cost bundled hub,
+ * which deconstruction discards.
+ * Rent settlement, cargo return, account closure, and concurrent races remain
+ * chain-authoritative; the Plan does not estimate a refund.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const stake: ClaimStakeSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planDeconstructClaimStake(ctx, stake, { authorization });
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planDeconstructClaimStake(ctx, stake, input) {
+    const options = validateDeconstructOptions(input);
+    const game = requireGameAddress(ctx);
+    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([
+        readFreshGameClaimStakeConfiguration(ctx),
+        readContextRawAccounts(ctx, [stake.address, stake.body.address]),
+    ]);
+    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) ||
+        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);
+    }
+    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);
+    }
+    if (freshGame.data.buildings.sequenceId !== stake.buildingDefinitionSeqId) {
+        fail(`Claim Stake ${stake.address} building 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);
+    }
+    const claimDefinition = freshGame.data.claimStakes.definitions.find(({ id }) => id === stake.claimStakeDefinitionId);
+    if (claimDefinition === undefined) {
+        fail(`Claim Stake definition ${String(stake.claimStakeDefinitionId)} is absent from the current Game catalog. Refresh the Claim Stake and definitions before retrying deconstruction.`, game);
+    }
+    const definitions = new Map(freshGame.data.buildings.definitions.map((definition) => [
+        definition.id,
+        definition,
+    ]));
+    const bundledHub = stake.buildings.length === 1 && stake.buildings[0]?.quantity === 1
+        ? definitions.get(stake.buildings[0].buildingId)
+        : undefined;
+    if (bundledHub === undefined ||
+        bundledHub.hubValue !== claimDefinition.hubValue ||
+        bundledHub.minimumTier !== claimDefinition.tier ||
+        bundledHub.constructionCost.length !== 0) {
+        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);
+        });
+        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);
+    }
+    const groups = currentBody.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);
+    }
+    const group = groups[0];
+    const chronologyMatches = group.chronoAddresses
+        .map((address, index) => ({ address, index }))
+        .filter(({ address }) => address === stake.address);
+    if (chronologyMatches.length !== 1) {
+        fail(`Claim Stake ${stake.address} must appear exactly once in the Planet chronology before its deconstruction index can be derived. Refresh the Body and retry.`, stake.body.address);
+    }
+    const activeStructures = group.structures.filter(({ address, deactivationTimeUnixSeconds }) => address === stake.address && deactivationTimeUnixSeconds === 0n);
+    if (activeStructures.length !== 1) {
+        fail(`Claim Stake ${stake.address} is not represented exactly once as an active structure in the Planet Body data. Refresh the Body and retry deconstruction.`, stake.body.address);
+    }
+    const claimStakeIndex = chronologyMatches[0].index;
+    const tierIndex = TIER_INDEX[claimDefinition.tier];
+    const plotCapacities = currentBody.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);
+    }
+    if (group.chronoAddresses.length > plotCapacities[plotCapacities.length - 1]) {
+        fail(`Planet ${stake.body.address} Claim Stake plot capacity does not cover its definition-group chronology. Refresh the Body before retrying deconstruction.`, stake.body.address);
+    }
+    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 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({
+        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.`),
+        ]),
+        steps: [
+            {
+                describes: description,
+                instruction: adaptDeconstructClaimStakeInstruction({
+                    authorization: options.authorization,
+                    celestialBody: stake.body.address,
+                    character,
+                    claimStakeIndex,
+                    claimStakeInstance: stake.address,
+                    claimStakeLevel,
+                    game,
+                    systemAndStarbasePlayerStarbasePlayer: player,
+                    systemAndStarbasePlayerSystem: system,
+                }),
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: description,
+    });
+}
+/** Plans one exact raw rent top-up for an owned placed Claim Stake.
+ *
+ * The planner validates the fresh Claim Stake and its canonical
+ * Profile/Character/Planet/System/Starbase Player graph, plus the Character's
+ * known raw ATLAS balance. Permission checks, concurrent balance changes, rent
+ * arithmetic, and duration purchased remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const stake: ClaimStakeSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planTopUpClaimStakeRent(ctx, stake, {
+ *   amount: 500_000_000n,
+ *   authorization,
+ * });
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planTopUpClaimStakeRent(ctx, stake, input) {
+    const options = validateTopUpRentOptions(input);
+    const game = requireGameAddress(ctx);
+    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 ||
+        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);
+    }
+    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 description = `Top up Claim Stake ${stake.address} rent with ${String(options.amount)} raw rent units; rent arithmetic remains chain-authoritative.`;
+    return createPlan({
+        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.`),
+        ]),
+        steps: [
+            {
+                describes: description,
+                instruction: adaptTopUpClaimStakeRentInstruction({
+                    amount: options.amount,
+                    authorization: options.authorization,
+                    celestialBody: stake.body.address,
+                    character,
+                    claimStakeInstance: stake.address,
+                    game,
+                    systemAndStarbasePlayerStarbasePlayer: player,
+                    systemAndStarbasePlayerSystem: system,
+                }),
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: description,
+    });
+}
+function cargoAmount(values, cargoId) {
+    return values.find((item) => item.cargoId === cargoId)?.amount ?? 0n;
+}
+function sameCargoAmounts(left, right) {
+    const leftById = new Map(left.map(({ amount, cargoId }) => [cargoId, amount]));
+    const rightById = new Map(right.map(({ amount, id }) => [id, amount]));
+    return (leftById.size === left.length &&
+        rightById.size === right.length &&
+        leftById.size === rightById.size &&
+        [...leftById].every(([id, amount]) => rightById.get(id) === amount));
+}
+function requireCargoBalance(source, address, cargoId, available, requested) {
+    if (available < requested) {
+        fail(`${source} has ${String(available)} raw units of cargo id ${String(cargoId)}, but this transfer requests ${String(requested)}. Reduce the request, add cargo, refresh both snapshots, and retry.`, address);
+    }
+}
+function requireTransferCapacity(destination, address, used, requested, total) {
+    if (used + requested > total) {
+        const remaining = used < total ? total - used : 0n;
+        fail(`${destination} has ${String(remaining)} raw capacity units remaining, but this transfer requires ${String(requested)}. Reduce the request or free capacity, refresh both snapshots, and retry.`, address);
+    }
+}
+function fleetCargoAmount(fleet, cargoId) {
+    return ((fleet.ammoBank.cargoId === cargoId ? fleet.ammoBank.amount : 0n) +
+        (fleet.fuelTank.cargoId === cargoId ? fleet.fuelTank.amount : 0n) +
+        cargoAmount(fleet.cargoHold.amounts, cargoId));
+}
+function describeCargoRequests(direction, requests) {
+    return requests.map(({ amount, cargoId }) => `${direction} cargo id ${String(cargoId)} = ${String(amount)} raw ${amount === 1n ? 'unit' : 'units'}`);
+}
+/** Plans the start of one Fleet transfer to an owned active Claim Stake.
+ *
+ * The planner validates the shared Profile/Game, idle Fleet with normalized
+ * crew, active Claim Stake, canonical Planet/System/Starbase Player graph,
+ * exact source balances, exact destination capacities, and an optional present
+ * FleetCrewBinding. The chain remains authoritative for range, duration,
+ * permission bits, concurrent state changes, and transfer arithmetic.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const fleet: FleetSnapshot;
+ * declare const stake: ClaimStakeSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planStartClaimStakeFleetTransfer(ctx, fleet, stake, {
+ *   authorization,
+ *   load: [{ cargoId: 3, amount: 25n }],
+ *   unload: [{ cargoId: 1, amount: 10n }],
+ * });
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planStartClaimStakeFleetTransfer(ctx, fleet, stake, input) {
+    const options = validateStartFleetTransferOptions(input);
+    const game = requireGameAddress(ctx);
+    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.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);
+    }
+    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);
+    }
+    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 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);
+    }
+    if (currentFleet.game !== game ||
+        currentFleet.ownerProfile !== options.authorization.profile ||
+        currentFleet.name !== fleet.name ||
+        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) {
+        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,
+        })))) {
+        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 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');
+    if (crewCandidate !== undefined) {
+        const currentCrewBinding = fleetCrewBindingAccountDefinition.decode(crewCandidate);
+        if (crewCandidate.address !== crewBinding ||
+            currentCrewBinding.fleet !== fleet.address ||
+            currentCrewBinding.ownerProfile !== options.authorization.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);
+        }
+    }
+    const definitions = new Map(await Promise.all([...options.load, ...options.unload].map(async (request) => {
+        const definition = await resolveCargo(ctx, request.cargoId);
+        return [request.cargoId, definition];
+    })));
+    for (const request of options.load) {
+        requireCargoBalance(`Claim Stake ${stake.address}`, stake.address, request.cargoId, cargoAmount(currentStake.production.cargoPod.amounts, request.cargoId), request.amount);
+    }
+    for (const request of options.unload) {
+        requireCargoBalance(`Fleet ${fleet.name}`, fleet.address, request.cargoId, fleetCargoAmount(currentFleet, request.cargoId), request.amount);
+    }
+    const loadAmmo = options.load
+        .filter(({ cargoId }) => cargoId === currentFleet.ammoBank.cargoId)
+        .reduce((total, { amount }) => total + amount, 0n);
+    const loadFuel = options.load
+        .filter(({ cargoId }) => cargoId === currentFleet.fuelTank.cargoId)
+        .reduce((total, { amount }) => total + amount, 0n);
+    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);
+    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);
+    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({
+        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.`),
+                ]),
+        ]),
+        steps: [
+            {
+                describes: description,
+                instruction: adaptStartClaimStakeFleetTransferInstruction({
+                    authorization: options.authorization,
+                    celestialBody: stake.body.address,
+                    character,
+                    claimStakeInstance: stake.address,
+                    ...(crewCandidate === undefined ? {} : { crewBinding }),
+                    currencyCache,
+                    fleet: fleet.address,
+                    game,
+                    systemAndStarbasePlayerStarbasePlayer: player,
+                    systemAndStarbasePlayerSystem: system,
+                    toLoad: options.load.map(({ amount, cargoId }) => [cargoId, amount]),
+                    toUnload: options.unload.map(({ amount, cargoId }) => [
+                        cargoId,
+                        amount,
+                    ]),
+                }),
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: description,
+    });
+}
+/** Plans owner-authorized recovery of one provably non-executable Claim Stake transfer.
+ *
+ * Recovery is available only after the explicit transfer lock time and only
+ * when fresh Fleet/Claim Stake cargo and Game definition state proves a source
+ * shortfall, invalid queued cargo id, or destination overflow. An executable
+ * transfer is rejected so callers use the permissionless normal exit instead.
+ * Recovery returns the Fleet to idle without moving cargo or changing the
+ * Claim Stake.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const fleet: FleetSnapshot;
+ * declare const stake: ClaimStakeSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planRecoverClaimStakeFleetTransfer(ctx, fleet, stake, {
+ *   atUnixSeconds: 1_700_000_100n,
+ *   authorization,
+ * });
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planRecoverClaimStakeFleetTransfer(ctx, fleet, stake, input) {
+    const options = validateRecoverFleetTransferOptions(input);
+    const game = requireGameAddress(ctx);
+    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 recovery.`, 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 recovery.`, fleet.address);
+    }
+    if (fleet.state.kind !== 'claimStakeTransfer') {
+        fail(`Fleet ${fleet.name} is ${fleet.state.kind}, not in a Claim Stake transfer. Refresh it and recover only a stuck Claim Stake transfer.`, fleet.address);
+    }
+    if (fleet.state.claimStake.address !== stake.address ||
+        fleet.state.planet.address !== stake.body.address) {
+        fail(`Fleet ${fleet.name}'s Claim Stake transfer does not reference Claim Stake ${stake.address} and its Body ${stake.body.address}. Supply the transfer's current Claim Stake snapshot and retry recovery.`, fleet.address);
+    }
+    if (stake.state.kind !== 'active') {
+        fail(`Claim Stake ${stake.address} is ${stake.state.kind}, but recovery requires the referenced Claim Stake to remain active. Refresh it and use force-exit only for a program-closed stake.`, stake.address);
+    }
+    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 [fleetCandidate, stakeCandidate] = await readContextRawAccounts(ctx, [
+        fleet.address,
+        stake.address,
+    ]);
+    const fleetAccount = requireAccount(fleetCandidate, fleet.address, `Fleet ${fleet.name} is missing. Refresh it and retry Claim Stake transfer recovery.`);
+    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 ||
+        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) {
+        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,
+        })))) {
+        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;
+    for (const request of currentFleet.state.load) {
+        const available = cargoAmount(currentStake.production.cargoPod.amounts, request.cargoId);
+        if (available < request.amount) {
+            reason = `Claim Stake source shortfall for cargo id ${String(request.cargoId)}`;
+            break;
+        }
+    }
+    if (reason === undefined) {
+        for (const request of currentFleet.state.unload) {
+            const available = fleetCargoAmount(currentFleet, request.cargoId);
+            if (available < request.amount) {
+                reason = `Fleet source shortfall for cargo id ${String(request.cargoId)}`;
+                break;
+            }
+        }
+    }
+    let gameAccount;
+    let queuedDefinitions = new Map();
+    if (reason === undefined) {
+        const cargoIds = [
+            ...new Set([...currentFleet.state.load, ...currentFleet.state.unload].map(({ cargoId }) => cargoId)),
+        ];
+        const freshGame = (await readFreshGameCargoDefinitions(ctx)) ??
+            fail(`Game ${game} is missing. Refresh the configured Game and retry Claim Stake transfer recovery.`, game);
+        gameAccount = freshGame.account;
+        queuedDefinitions = new Map(freshGame.data.definitions.map((definition) => [
+            definition.id,
+            definition,
+        ]));
+        const invalidCargoId = cargoIds.find((cargoId) => !queuedDefinitions.has(cargoId));
+        if (invalidCargoId !== undefined) {
+            reason = `invalid queued cargo id ${String(invalidCargoId)}`;
+        }
+    }
+    if (reason === undefined) {
+        const loadAmmo = cargoAmount(currentFleet.state.load, currentFleet.ammoBank.cargoId);
+        const loadFuel = cargoAmount(currentFleet.state.load, currentFleet.fuelTank.cargoId);
+        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);
+        if (currentFleet.ammoBank.amount + loadAmmo >
+            currentFleet.stats.cargo.ammoCapacity) {
+            reason = 'Fleet ammo destination overflow';
+        }
+        else if (currentFleet.fuelTank.amount + loadFuel >
+            currentFleet.stats.cargo.fuelCapacity) {
+            reason = 'Fleet fuel destination overflow';
+        }
+        else if (currentFleet.cargoHold.storageCost + loadCargoStorage >
+            currentFleet.stats.cargo.cargoCapacity) {
+            reason = 'Fleet cargo destination overflow';
+        }
+        else if (currentStake.production.cargoPod.storageCost + unloadStorage >
+            currentStake.production.resourceCapacityRaw) {
+            reason = 'Claim Stake resource destination overflow';
+        }
+    }
+    if (reason === undefined) {
+        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({
+        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.`),
+            ...(gameAccount === undefined
+                ? []
+                : [
+                    precondition(gameAccount, `Game ${game} retains the cargo definitions used to prove the transfer is non-executable.`),
+                ]),
+        ]),
+        steps: [
+            {
+                describes: description,
+                instruction: adaptRecoverClaimStakeFleetTransferInstruction({
+                    authorization: options.authorization,
+                    claimStakeInstance: stake.address,
+                    fleet: fleet.address,
+                    game,
+                }),
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: description,
+    });
+}
+//# sourceMappingURL=index.js.map