@aephia/atlas-kit 0.6.0-next.8 → 0.6.0-next.80

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

@@ -6,16 +6,33 @@ import { readFreshGameClaimStakeConfiguration, } from '../../registry/claim-stak
 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 { deriveFleetCrewBindingAddress, fleetCrewBindingAccountDefinition, matchesFleetCrewBindingIdentity, } from '../../internal/c4/fleet-crew-binding.js';
 import { deriveFleetAddress, fleetAccountDefinition, } from '../../internal/c4/fleet.js';
 import { deriveProfileFactionAddress, profileFactionIdentityAccountDefinition, } from '../../internal/c4/profile-faction.js';
 import { deriveStarbasePlayerAddress, starbasePlayerAccountDefinition, } from '../../internal/c4/starbase.js';
-import { celestialBodyAccountDefinition, decodeIndexedCelestialBodyAccount, deriveCelestialBodyAddress, deriveStarSystemAddress, starSystemAccountDefinition, } from '../../internal/c4/world.js';
+import { celestialBodyAccountDefinition, deriveCelestialBodyAddress, deriveStarSystemAddress, starSystemAccountDefinition, } from '../../internal/c4/world.js';
+import { resolveXpRuntime } from '../../internal/planning/xp-runtime.js';
 import { requireGameAddress } from '../../internal/game-context.js';
+import { cargoStorageUnits } from '../../internal/cargo.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';
+async function resolveClaimStakeXp(ctx, game, structure, character) {
+    const xp = await resolveXpRuntime(ctx, {
+        game,
+        structure,
+        ...(character === undefined ? {} : { character }),
+    });
+    const guard = {
+        kind: 'xp-runtime',
+        address: game,
+        intent: xp.intent,
+        accounts: xp.accounts,
+        describes: 'The Game and canonical Claim Stake XP accounts remain supported; accrued XP may change. Initialize or repair missing XP state using the game client, then recreate the Plan.',
+    };
+    return { accounts: xp.accounts, guard };
+}
 const U64_MAX = (1n << 64n) - 1n;
 const U16_MAX = 65_535;
 const I32_MAX = 2_147_483_647;
@@ -509,6 +526,9 @@ function buildingDescription(change, name) {
  * construction cargo. Rent synchronization and the final concurrent sequence
  * race remain chain-authoritative.
  *
+ * Requires Game 2 and its existing canonical Claim Stake XP ledger.
+ * Missing XP state must be repaired outside this Plan; no accounts are created.
+ *
  * @example
  * ```ts
  * declare const ctx: SageContext;
@@ -746,6 +766,7 @@ export async function planClaimStakeBuildingChanges(ctx, stake, input) {
     }
     const currencyCache = await deriveCurrencyCacheAddress(game);
     const description = `Change buildings on Claim Stake ${stake.address}: ${descriptions.join('; ')}.`;
+    const xp = await resolveClaimStakeXp(ctx, game, stake.address);
     return createPlan({
         kind: 'claim-stakes.building-changes',
         preconditions: [
@@ -759,11 +780,13 @@ export async function planClaimStakeBuildingChanges(ctx, stake, input) {
                 precondition(profileFactionAccount, `ProfileFaction ${profileFaction} remains assigned to Profile ${options.authorization.profile} and aligned with the current Starbase controller.`),
             ])),
             ownershipPrecondition,
+            xp.guard,
         ],
         steps: [
             {
                 describes: description,
                 instruction: adaptClaimStakeBuildingChangesInstruction({
+                    ...xp.accounts,
                     authorization: options.authorization,
                     buildingChanges: options.buildingChanges.map(({ buildingId, kind, quantity }) => [buildingId, kind === 'add' ? quantity : -quantity]),
                     celestialBody: stake.body.address,
@@ -789,6 +812,10 @@ export async function planClaimStakeBuildingChanges(ctx, stake, input) {
  * CurrencyCache, and a known positive rent balance. Rent timing and the final
  * crew/building validation remain chain-authoritative.
  *
+ * Requires Game 2 and its existing canonical Claim Stake XP ledger.
+ * The Character XP budget and configuration must also be reconciled.
+ * Missing XP state must be repaired outside this Plan; no accounts are created.
+ *
  * @example
  * ```ts
  * declare const ctx: SageContext;
@@ -882,21 +909,26 @@ export async function planFinalizeClaimStakeBuildingChanges(ctx, stake, input) {
     }
     validateCurrencyCache(currencyAccount, game, currencyCache, 'finalization');
     const description = `Finalize building changes on Claim Stake ${stake.address}.`;
+    const xp = await resolveClaimStakeXp(ctx, game, stake.address, character);
     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.'),
-        ]),
+        preconditions: [
+            xp.guard,
+            ...(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({
+                    ...xp.accounts,
                     authorization: options.authorization,
                     celestialBody: stake.body.address,
                     character,
@@ -920,6 +952,9 @@ export async function planFinalizeClaimStakeBuildingChanges(ctx, stake, input) {
  * state; rent arithmetic and concurrent state transitions remain
  * chain-authoritative.
  *
+ * Requires Game 2 and its existing canonical Claim Stake XP ledger.
+ * Missing XP state must be repaired outside this Plan; no accounts are created.
+ *
  * @example
  * ```ts
  * declare const ctx: SageContext;
@@ -995,19 +1030,24 @@ export async function planCancelClaimStakeBuildingChanges(ctx, stake, input) {
     }
     validateCurrencyCache(currencyAccount, game, currencyCache, 'cancellation');
     const description = `Cancel the pending building design on Claim Stake ${stake.address} and return it to active state.`;
+    const xp = await resolveClaimStakeXp(ctx, game, stake.address);
     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.'),
-        ]),
+        preconditions: [
+            xp.guard,
+            ...(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({
+                    ...xp.accounts,
                     authorization: options.authorization,
                     celestialBody: stake.body.address,
                     claimStakeInstance: stake.address,
@@ -1063,7 +1103,7 @@ export async function planDeconstructClaimStake(ctx, stake, input) {
     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);
+    const currentBody = celestialBodyAccountDefinition.decode(bodyAccount);
     if (currentStake.game !== game ||
         currentStake.body !== stake.body.address ||
         currentStake.ownerCharacter !== character ||
@@ -1104,16 +1144,17 @@ export async function planDeconstructClaimStake(ctx, stake, input) {
         bundledHub.hubValue !== claimDefinition.hubValue ||
         bundledHub.minimumTier !== claimDefinition.tier ||
         bundledHub.constructionCost.length !== 0) {
+        // Only a building with a construction cost is player-funded; a zero-cost
+        // hub from another definition family is a foreign bundled hub.
         const hasPlayerFundedBuilding = stake.buildings.some((building) => {
             const definition = definitions.get(building.buildingId);
-            return (definition === undefined ||
-                definition.hubValue !== claimDefinition.hubValue ||
-                definition.minimumTier !== claimDefinition.tier ||
-                definition.constructionCost.length !== 0);
+            return (definition !== undefined && definition.constructionCost.length !== 0);
         });
         fail(hasPlayerFundedBuilding
             ? `Claim Stake ${stake.address} still contains a player-funded building. Remove and finalize every player-funded building so only its verified bundled hub remains before retrying deconstruction.`
-            : `Claim Stake ${stake.address} does not contain exactly one verified bundled hub. Refresh it and restore the definition-compatible bundled hub before retrying deconstruction.`, stake.address);
+            : bundledHub === undefined
+                ? `Claim Stake ${stake.address} does not contain exactly one verified bundled hub. Refresh it and restore the definition-compatible bundled hub before retrying deconstruction.`
+                : `Claim Stake ${stake.address} holds ${bundledHub.name} (${String(bundledHub.id)}), which is not the zero-cost ${claimDefinition.tier} bundled hub for Claim Stake definition ${String(claimDefinition.id)} (${claimDefinition.name}). Refresh the Claim Stake and Game definitions so the recorded hub matches its definition before retrying deconstruction.`, stake.address);
     }
     const groups = currentBody.details.claimedPlots.filter(({ key }) => key === claimDefinition.id);
     if (groups.length !== 1) {
@@ -1357,6 +1398,9 @@ function describeCargoRequests(direction, requests) {
  * FleetCrewBinding. The chain remains authoritative for range, duration,
  * permission bits, concurrent state changes, and transfer arithmetic.
  *
+ * Requires Game 2 and its existing canonical Claim Stake XP ledger.
+ * Missing XP state must be repaired outside this Plan; no accounts are created.
+ *
  * @example
  * ```ts
  * declare const ctx: SageContext;
@@ -1485,8 +1529,7 @@ export async function planStartClaimStakeFleetTransfer(ctx, fleet, stake, input)
     if (crewCandidate !== undefined) {
         const currentCrewBinding = fleetCrewBindingAccountDefinition.decode(crewCandidate);
         if (crewCandidate.address !== crewBinding ||
-            currentCrewBinding.fleet !== fleet.address ||
-            currentCrewBinding.ownerProfile !== options.authorization.profile) {
+            !matchesFleetCrewBindingIdentity(currentCrewBinding, fleet.address, 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);
         }
     }
@@ -1509,37 +1552,43 @@ export async function planStartClaimStakeFleetTransfer(ctx, fleet, stake, input)
     const loadCargoStorage = options.load
         .filter(({ cargoId }) => cargoId !== currentFleet.ammoBank.cargoId &&
         cargoId !== currentFleet.fuelTank.cargoId)
-        .reduce((total, { amount, cargoId }) => total + amount * BigInt(definitions.get(cargoId).storageCost), 0n);
+        .reduce((total, { amount, cargoId }) => total +
+        cargoStorageUnits(amount, definitions.get(cargoId).storageCost), 0n);
     requireTransferCapacity(`Fleet ${fleet.name} ammo destination`, fleet.address, currentFleet.ammoBank.amount, loadAmmo, currentFleet.stats.cargo.ammoCapacity);
     requireTransferCapacity(`Fleet ${fleet.name} fuel destination`, fleet.address, currentFleet.fuelTank.amount, loadFuel, currentFleet.stats.cargo.fuelCapacity);
     requireTransferCapacity(`Fleet ${fleet.name} cargo destination`, fleet.address, currentFleet.cargoHold.storageCost, loadCargoStorage, currentFleet.stats.cargo.cargoCapacity);
-    const unloadStorage = options.unload.reduce((total, { amount, cargoId }) => total + amount * BigInt(definitions.get(cargoId).storageCost), 0n);
+    const unloadStorage = options.unload.reduce((total, { amount, cargoId }) => total + cargoStorageUnits(amount, definitions.get(cargoId).storageCost), 0n);
     requireTransferCapacity(`Claim Stake ${stake.address} resource destination`, stake.address, currentStake.production.cargoPod.storageCost, unloadStorage, currentStake.production.resourceCapacityRaw);
     const descriptions = [
         ...describeCargoRequests('load', options.load),
         ...describeCargoRequests('unload', options.unload),
     ];
     const description = `Start fleet ${fleet.name}'s transfer to Claim Stake ${stake.address}: ${descriptions.join('; ')}. Range and transfer duration remain chain-authoritative.`;
+    const xp = await resolveClaimStakeXp(ctx, game, stake.address);
     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.`),
-                ]),
-        ]),
+        preconditions: [
+            xp.guard,
+            ...(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({
+                    ...xp.accounts,
                     authorization: options.authorization,
                     celestialBody: stake.body.address,
                     character,
@@ -1695,8 +1744,10 @@ export async function planRecoverClaimStakeFleetTransfer(ctx, fleet, stake, inpu
         const loadCargoStorage = currentFleet.state.load
             .filter(({ cargoId }) => cargoId !== currentFleet.ammoBank.cargoId &&
             cargoId !== currentFleet.fuelTank.cargoId)
-            .reduce((total, { amount, cargoId }) => total + amount * BigInt(queuedDefinitions.get(cargoId).storageCost), 0n);
-        const unloadStorage = currentFleet.state.unload.reduce((total, { amount, cargoId }) => total + amount * BigInt(queuedDefinitions.get(cargoId).storageCost), 0n);
+            .reduce((total, { amount, cargoId }) => total +
+            cargoStorageUnits(amount, queuedDefinitions.get(cargoId).storageCost), 0n);
+        const unloadStorage = currentFleet.state.unload.reduce((total, { amount, cargoId }) => total +
+            cargoStorageUnits(amount, queuedDefinitions.get(cargoId).storageCost), 0n);
         if (currentFleet.ammoBank.amount + loadAmmo >
             currentFleet.stats.cargo.ammoCapacity) {
             reason = 'Fleet ammo destination overflow';