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

package/dist/combat/actions/index.js

@@ -1,20 +1,25 @@
-import { getAddressEncoder, isAddress } from '@solana/kit';
+import { fleetAttackInstructionKey, validateFleetAttackActors, } from '../../internal/planning/fleet-attack-xp.js';
+import { resolveXpRuntime } from '../../internal/planning/xp-runtime.js';
+import { isAddress } from '@solana/kit';
+import { resolveActionRuntime } from '../../internal/planning/action-runtime.js';
 import { InvalidActionInputError, SageSdkError } from '../../client/errors.js';
 import { readContextRawAccounts } from '../../client/reconciliation.js';
-import { sage } from '../../internal/c4/bindings.js';
-import { lootAccountDefinition, } from '../../internal/c4/combat.js';
+import { getRetrieveLootInstructionDataEncoder } from '../../internal/c4/runtime-bindings.js';
+import { lootAccountDefinition, } from '../../internal/c4/loot.js';
 import { deriveFleetAddress, fleetAccountDefinition, } from '../../internal/c4/fleet.js';
-import { deriveFleetCrewBindingAddress, fleetCrewBindingAccountDefinition, } from '../../internal/c4/fleet-crew-binding.js';
+import { deriveFleetCrewBindingAddress, fleetCrewBindingAccountDefinition, matchesFleetCrewBindingIdentity, } from '../../internal/c4/fleet-crew-binding.js';
 import { deriveFactionAccountAddress, deriveFactionEconomicsConfigAddress, deriveFactionOwnershipAddress, deriveFactionRelationTrackerAddress, deriveFactionTreasuryAddress, deriveKingSystemTrackerAddress, deriveRegionTrackerAddress, factionAccountDefinition, factionEconomicsConfigAccountDefinition, factionOwnershipAccountDefinition, factionRelationTrackerAccountDefinition, factionTreasuryAccountDefinition, kingSystemTrackerAccountDefinition, regionTrackerAccountDefinition, } from '../../internal/c4/factions.js';
-import { characterAccountDefinition, findCharacterPda, } from '../../internal/c4/identity.js';
+import { factionValue } from '../../internal/c4/faction.js';
+import { characterAccountDefinition, findCharacterPda, } from '../../internal/c4/character.js';
 import { deriveLoyaltyContributionAddress, deriveLoyaltyEpochAddress, loyaltyContributionAccountDefinition, loyaltyEpochAccountDefinition, } from '../../internal/c4/loyalty.js';
 import { atlasRewardConfigAccountDefinition, atlasRewardRegistryAccountDefinition, deriveAtlasRewardConfigAddress, deriveAtlasRewardRegistryAddress, } from '../../internal/c4/rewards.js';
 import { deriveStarSystemAddress, starSystemAccountDefinition, } from '../../internal/c4/world.js';
 import { requireGameAddress } from '../../internal/game-context.js';
-import { adaptApplyCombatStimulantInstruction, adaptAttackFleetInstruction, adaptAttackStarbaseInstruction, adaptRetrieveLootInstruction, validatePlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
-import { createPlan, } from '../../planning/index.js';
+import { adaptApplyCombatStimulantInstruction, adaptAttackFleetInstruction, adaptAttackStarbaseInstruction, adaptRetrieveLootInstruction, readPlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
+import { buildPlannerPlan } from '../../planning/plan-construction.js';
 import { readGameCombatConfiguration } from '../../registry/combat.js';
 import { resolveCargo, } from '../../registry/index.js';
+import { accountAbsentPrecondition, accountStatePrecondition, } from '../../internal/planning/account-state.js';
 function invalid(field, value, acceptedRange, remedy) {
     throw new InvalidActionInputError(field, value, acceptedRange, remedy);
 }
@@ -35,19 +40,13 @@ function assertKeys(value, field, required, optional = []) {
 function validateOptions(value) {
     const options = readRecord(value, 'options');
     assertKeys(options, 'options', ['authorization']);
-    const authorizationRecord = readRecord(options.authorization, 'authorization');
-    assertKeys(authorizationRecord, 'authorization', ['profile', 'authority', 'keyIndex'], ['certificate']);
-    const authorization = authorizationRecord;
-    validatePlanAuthorization(authorization);
+    const authorization = readPlanAuthorization(options.authorization);
     return { authorization };
 }
 function validateAttackOptions(value) {
     const options = readRecord(value, 'options');
     assertKeys(options, 'options', ['authorization', 'loot']);
-    const authorizationRecord = readRecord(options.authorization, 'authorization');
-    assertKeys(authorizationRecord, 'authorization', ['profile', 'authority', 'keyIndex'], ['certificate']);
-    const authorization = authorizationRecord;
-    validatePlanAuthorization(authorization);
+    const authorization = readPlanAuthorization(options.authorization);
     if (typeof options.loot !== 'string' || !isAddress(options.loot)) {
         invalid('options.loot', options.loot, 'one valid new Loot account address', 'Generate a new address-only Loot signer and provide its public address before retrying.');
     }
@@ -66,10 +65,7 @@ function validateAttackStance(value) {
 function validateRetrieveOptions(value) {
     const options = readRecord(value, 'options');
     assertKeys(options, 'options', ['authorization', 'atUnixSeconds']);
-    const authorizationRecord = readRecord(options.authorization, 'authorization');
-    assertKeys(authorizationRecord, 'authorization', ['profile', 'authority', 'keyIndex'], ['certificate']);
-    const authorization = authorizationRecord;
-    validatePlanAuthorization(authorization);
+    const authorization = readPlanAuthorization(options.authorization);
     if (typeof options.atUnixSeconds !== 'bigint' || options.atUnixSeconds < 0n) {
         invalid('options.atUnixSeconds', options.atUnixSeconds, 'a non-negative bigint Unix timestamp', 'Provide the explicit current Unix timestamp used to evaluate Loot exclusivity before retrying.');
     }
@@ -162,9 +158,7 @@ function validateLootSelection(value, loot, fleet, retrievingProfile, atUnixSeco
         }
         generated.push([itemIndex, encoded]);
     }
-    const instructionDataLength = sage
-        .getRetrieveLootInstructionDataEncoder()
-        .encode({
+    const instructionDataLength = getRetrieveLootInstructionDataEncoder().encode({
         keyIndex: 0,
         want: generated.map(([itemIndex, cargo]) => [
             itemIndex,
@@ -209,29 +203,6 @@ function rawCargoFingerprint(fleet) {
         .join(',');
     return [fleet.cargoHold.seqId, fleet.cargoHold.storageCost, items].join('|');
 }
-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(address, describes) {
-    return Object.freeze({
-        address,
-        describes,
-        kind: 'account-absent',
-    });
-}
 /** Plans application of one configured combat stimulant without predicting its effects.
  *
  * The planner validates Fleet ownership and Game membership, current catalog
@@ -311,10 +282,10 @@ export async function planFleetApplyCombatStimulant(ctx, fleet, stimulant, input
         fail(`Fleet ${fleet.name} (${fleet.address}) has no crew and cannot apply a combat stimulant. Crew the Fleet, refresh it through this context, and retry.`, fleet.address);
     }
     const description = `Apply one ${catalogued.cargo.name} combat stimulant from Fleet ${fleet.name} (${fleet.address}); permission, stacking, charge application, and combat outcomes remain chain-authoritative.`;
-    return createPlan({
+    return buildPlannerPlan({
         kind: 'combat.apply-stimulant',
         preconditions: [
-            await precondition(account, `Fleet ${fleet.name} retains its configured Game, owning Profile, supported crewed state, and known ${catalogued.cargo.name} cargo balance.`),
+            await accountStatePrecondition(account, `Fleet ${fleet.name} retains its configured Game, owning Profile, supported crewed state, and known ${catalogued.cargo.name} cargo balance.`),
         ],
         steps: [
             {
@@ -331,20 +302,6 @@ export async function planFleetApplyCombatStimulant(ctx, fleet, stimulant, input
         summary: description,
     });
 }
-function factionId(fleet) {
-    if (fleet.npcFactionId > 0)
-        return fleet.npcFactionId;
-    switch (fleet.faction) {
-        case 'mud':
-            return 1;
-        case 'oni':
-            return 2;
-        case 'ustur':
-            return 3;
-        case 'unaligned':
-            return 0;
-    }
-}
 function shipFingerprint(fleet) {
     return fleet.ships
         .map(({ id, quantity }) => `${String(id)}:${String(quantity)}`)
@@ -404,14 +361,13 @@ async function optionalCrewBinding(ctx, fleet) {
     const address = await deriveFleetCrewBindingAddress(fleet.address);
     const [envelope] = await ctx.data.readMany(fleetCrewBindingAccountDefinition, [address]);
     if (envelope !== undefined &&
-        (envelope.data.fleet !== fleet.address ||
-            envelope.data.ownerProfile !== fleet.ownerProfile.address)) {
+        !matchesFleetCrewBindingIdentity(envelope.data, fleet.address, fleet.ownerProfile.address)) {
         fail(`FleetCrewBinding ${address} does not belong to Fleet ${fleet.address} and Profile ${fleet.ownerProfile.address}. Refresh the Fleet crew relationship and retry.`, address);
     }
     return envelope?.address;
 }
 async function resolveRewardAccounts(ctx, fleet, registry, config, epochIndex) {
-    const resolvedFaction = factionId(fleet);
+    const resolvedFaction = fleet.npcFactionId > 0 ? fleet.npcFactionId : factionValue(fleet.faction);
     if (resolvedFaction === 0)
         return { config, registry };
     const [epochAddress, contributionAddress] = await Promise.all([
@@ -446,33 +402,82 @@ async function resolveRewardAccounts(ctx, fleet, registry, config, epochIndex) {
         registry,
     };
 }
-async function resolveNpcAccounts(ctx, fleet, requireFactionAccount) {
+/** Reads and requires an NPC Fleet's canonical FactionOwnership and, when
+ * `withFaction`, its Faction account; a player Fleet has neither. */
+async function resolveNpcAccounts(ctx, fleet, withFaction) {
     if (fleet.npcFactionId === 0)
         return {};
-    const ownershipAddress = await deriveFactionOwnershipAddress(fleet.game, 'fleet', fleet.address);
-    const [ownership] = await ctx.data.readMany(factionOwnershipAccountDefinition, [ownershipAddress]);
+    const addresses = await Promise.all([
+        deriveFactionOwnershipAddress(fleet.game, 'fleet', fleet.address),
+        ...(withFaction
+            ? [deriveFactionAccountAddress(fleet.game, fleet.npcFactionId)]
+            : []),
+    ]);
+    const [ownership, faction] = await readContextRawAccounts(ctx, addresses);
+    const ownershipData = ownership && factionOwnershipAccountDefinition.decode(ownership);
     if (ownership === undefined ||
-        ownership.data.game !== fleet.game ||
-        ownership.data.asset.kind !== 'fleet' ||
-        ownership.data.asset.fleet !== fleet.address ||
-        ownership.data.controllingFactionId !== fleet.npcFactionId) {
-        fail(`NPC Fleet ${fleet.address} has no matching canonical FactionOwnership for faction ${String(fleet.npcFactionId)}. Refresh the Fleet and faction ownership relationship before retrying.`, ownershipAddress);
-    }
-    if (!requireFactionAccount)
-        return { ownership: ownership.address };
-    const factionAddress = await deriveFactionAccountAddress(fleet.game, fleet.npcFactionId);
-    const faction = await ctx.data.read(factionAccountDefinition, factionAddress);
-    if (faction.data.game !== fleet.game ||
-        faction.data.factionId !== fleet.npcFactionId) {
-        fail(`Faction ${factionAddress} does not match NPC Fleet ${fleet.address}'s Game and faction id. Refresh the faction registry relationship before retrying.`, factionAddress);
-    }
-    return { factionAccount: faction.address, ownership: ownership.address };
+        ownershipData?.game !== fleet.game ||
+        ownershipData.asset.kind !== 'fleet' ||
+        ownershipData.asset.fleet !== fleet.address ||
+        ownershipData.controllingFactionId !== fleet.npcFactionId) {
+        fail(`NPC Fleet ${fleet.address} has no matching canonical FactionOwnership for faction ${String(fleet.npcFactionId)}. Refresh the Fleet and faction ownership relationship before retrying.`, addresses[0]);
+    }
+    if (!withFaction)
+        return { ownership };
+    const factionData = faction && factionAccountDefinition.decode(faction);
+    if (faction === undefined ||
+        factionData?.game !== fleet.game ||
+        factionData.factionId !== fleet.npcFactionId) {
+        fail(`Faction ${addresses[1]} is missing or does not match NPC Fleet ${fleet.address}'s Game and faction id. Refresh the faction registry relationship before retrying.`, addresses[1]);
+    }
+    return { faction, ownership };
 }
 function generatedStance(stance) {
     return {
         ammoUsage: stance.ammoUsage === 'none' ? 0 : stance.ammoUsage === 'light' ? 1 : 2,
     };
 }
+/** Requires a live Fleet snapshot of the configured Game with known AP, crew
+ * and ship composition; an attacking Fleet also needs AP available. */
+function validateAttackFleet(fleet, role, game) {
+    const label = `The ${role} Fleet ${fleet.name} (${fleet.address})`;
+    if (fleet.game !== game) {
+        fail(`${label} belongs to Game ${fleet.game}, not configured Game ${game}. Refresh the Fleet through this context and retry.`, fleet.address);
+    }
+    if (fleet.state.kind === 'destroyed') {
+        fail(`${label} is destroyed and cannot participate in this attack. Refresh the Fleet after respawn and retry.`, fleet.address);
+    }
+    if (!Number.isSafeInteger(fleet.ap) ||
+        fleet.ap < 0 ||
+        !Number.isSafeInteger(fleet.crewCount) ||
+        fleet.crewCount <= 0) {
+        fail(`${label} has unknown or invalid AP or crew state. Refresh the Fleet through this context and retry.`, fleet.address);
+    }
+    if (fleet.ships.length === 0 ||
+        fleet.ships.some(({ quantity }) => quantity <= 0n)) {
+        fail(`${label} has no valid known ship composition. Refresh Fleet composition and retry.`, fleet.address);
+    }
+    if (role === 'attacking' && fleet.ap === 0) {
+        fail(`${label} has no known AP available. Wait for AP reload, refresh the Fleet, and retry.`, fleet.address);
+    }
+}
+/** Validates the inputs every attack shares: the stance, an attacking Fleet
+ * owned by the authorization Profile that can attack, and a new Loot address
+ * distinct from the authorization signers. */
+function validateAttack(ctx, attacker, inputStance, inputOptions) {
+    const options = validateAttackOptions(inputOptions);
+    const stance = validateAttackStance(inputStance);
+    const game = requireGameAddress(ctx);
+    if (attacker.ownerProfile.address !== options.authorization.profile) {
+        fail(`Attacking Fleet ${attacker.address} does not belong to authorization Profile ${options.authorization.profile}. Choose an owned Fleet and retry.`, attacker.address);
+    }
+    if (options.loot === options.authorization.authority ||
+        options.loot === options.authorization.profile) {
+        fail(`The new Loot address ${options.loot} must be distinct from the authorization authority and Profile. Generate a separate Loot signer address and retry.`, options.loot);
+    }
+    validateAttackFleet(attacker, 'attacking', game);
+    return { game, options, stance };
+}
 /** Plans one singleton Fleet-on-Fleet attack without predicting its outcome.
  *
  * Range, randomness, recent slot hashes, final combat arithmetic, and chain
@@ -497,43 +502,11 @@ function generatedStance(stance) {
  * ```
  */
 export async function planFleetAttackFleet(ctx, attacker, defender, inputStance, inputOptions) {
-    const options = validateAttackOptions(inputOptions);
-    const stance = validateAttackStance(inputStance);
-    const game = requireGameAddress(ctx);
+    const { game, options, stance } = validateAttack(ctx, attacker, inputStance, inputOptions);
     if (attacker.address === defender.address) {
         fail(`Fleet ${attacker.address} cannot attack itself. Choose a distinct defending Fleet and retry.`, attacker.address);
     }
-    if (attacker.ownerProfile.address !== options.authorization.profile) {
-        fail(`Attacking Fleet ${attacker.address} does not belong to authorization Profile ${options.authorization.profile}. Choose an owned Fleet and retry.`, attacker.address);
-    }
-    if (options.loot === options.authorization.authority ||
-        options.loot === options.authorization.profile) {
-        fail(`The new Loot address ${options.loot} must be distinct from the authorization authority and Profile. Generate a separate Loot signer address and retry.`, options.loot);
-    }
-    for (const [role, fleet] of [
-        ['attacking', attacker],
-        ['defending', defender],
-    ]) {
-        if (fleet.game !== game) {
-            fail(`The ${role} Fleet ${fleet.address} belongs to Game ${fleet.game}, not configured Game ${game}. Refresh both Fleets through this context and retry.`, fleet.address);
-        }
-        if (fleet.state.kind === 'destroyed') {
-            fail(`The ${role} Fleet ${fleet.name} (${fleet.address}) is destroyed and cannot participate in this attack. Refresh the Fleet after respawn and retry.`, fleet.address);
-        }
-        if (!Number.isSafeInteger(fleet.ap) ||
-            fleet.ap < 0 ||
-            !Number.isSafeInteger(fleet.crewCount) ||
-            fleet.crewCount <= 0) {
-            fail(`The ${role} Fleet ${fleet.name} (${fleet.address}) has unknown or invalid AP or crew state. Refresh the Fleet through this context and retry.`, fleet.address);
-        }
-        if (fleet.ships.length === 0 ||
-            fleet.ships.some(({ quantity }) => quantity <= 0n)) {
-            fail(`The ${role} Fleet ${fleet.name} (${fleet.address}) has no valid known ship composition. Refresh Fleet composition and retry.`, fleet.address);
-        }
-    }
-    if (attacker.ap === 0) {
-        fail(`Attacking Fleet ${attacker.name} (${attacker.address}) has no known AP available. Wait for AP reload, refresh the Fleet, and retry.`, attacker.address);
-    }
+    validateAttackFleet(defender, 'defending', game);
     const currentAccounts = await readContextRawAccounts(ctx, [
         attacker.address,
         defender.address,
@@ -565,58 +538,93 @@ export async function planFleetAttackFleet(ctx, attacker, defender, inputStance,
         deriveRegionTrackerAddress(game),
         deriveFactionRelationTrackerAddress(game),
     ]);
+    const actorIntent = {
+        address: attacker.address,
+        defender: defender.address,
+        game,
+        profile: attacker.ownerProfile.address,
+        defenderProfile: defender.ownerProfile.address,
+    };
+    await validateFleetAttackActors(ctx, actorIntent);
+    const versions = new Map();
+    const attackerXp = await resolveXpRuntime(ctx, { game, character, profile: attacker.ownerProfile.address }, versions);
+    const defenderXp = character === defenderCharacter
+        ? attackerXp
+        : await resolveXpRuntime(ctx, {
+            game,
+            character: defenderCharacter,
+            profile: defender.ownerProfile.address,
+        }, versions);
+    const xpGuards = [...new Set([attackerXp, defenderXp])].map((xp) => ({
+        kind: 'xp-runtime',
+        address: game,
+        intent: xp.intent,
+        accounts: xp.accounts,
+        describes: 'Both operator XP budgets remain canonical and reconciled; earned XP and bank balances may change.',
+    }));
+    const instruction = adaptAttackFleetInstruction({
+        ...(attackerNpc.faction === undefined
+            ? {}
+            : { attackerFactionAccount: attackerNpc.faction.address }),
+        ...(attackerNpc.ownership === undefined
+            ? {}
+            : { attackerFleetOwnership: attackerNpc.ownership.address }),
+        attackerRewardsConfig: attackerRewards.config,
+        ...(attackerRewards.contribution === undefined
+            ? {}
+            : { attackerRewardsContribution: attackerRewards.contribution }),
+        ...(attackerRewards.epoch === undefined
+            ? {}
+            : { attackerRewardsEpoch: attackerRewards.epoch }),
+        attackerRewardsRegistry: attackerRewards.registry,
+        ...(defender.state.kind === 'mining'
+            ? { asteroid: defender.state.asteroid.address }
+            : {}),
+        authorization: options.authorization,
+        attackerXpBudget: attackerXp.accounts.xpBudget,
+        defenderXpBudget: defenderXp.accounts.xpBudget,
+        xpBudgetConfig: attackerXp.accounts.xpBudgetConfig,
+        character,
+        ...(crewBinding === undefined ? {} : { crewBinding }),
+        defenderCharacter,
+        ...(defenderNpc.ownership === undefined
+            ? {}
+            : { defenderFleetOwnership: defenderNpc.ownership.address }),
+        defenderRewardsConfig: defenderRewards.config,
+        ...(defenderRewards.contribution === undefined
+            ? {}
+            : { defenderRewardsContribution: defenderRewards.contribution }),
+        ...(defenderRewards.epoch === undefined
+            ? {}
+            : { defenderRewardsEpoch: defenderRewards.epoch }),
+        defenderRewardsRegistry: defenderRewards.registry,
+        defendingFleet: defender.address,
+        factionRelationTracker,
+        fleet: attacker.address,
+        game,
+        loot: options.loot,
+        recentSlothashes: 'SysvarS1otHashes111111111111111111111111111',
+        regionTracker,
+        stance: generatedStance(stance),
+    });
     const description = `Attack Fleet ${defender.name} (${defender.address}) with Fleet ${attacker.name} (${attacker.address}) using ${stance.ammoUsage} ammunition; range, randomness, rewards, Loot, damage, and final combat arithmetic remain chain-authoritative.`;
-    return createPlan({
+    return buildPlannerPlan({
         kind: 'combat.attack-fleet',
         preconditions: [
-            await precondition(attackerAccount, `Attacking Fleet ${attacker.name} retains its owner, Game, live state, crew, AP, faction, and ship composition.`),
-            await precondition(defenderAccount, `Defending Fleet ${defender.name} retains its owner, Game, live state, crew, faction, and ship composition.`),
+            {
+                kind: 'fleet-attack',
+                ...actorIntent,
+                instructionKey: fleetAttackInstructionKey(instruction),
+                describes: 'The exact attack instruction and both canonical operators remain bound.',
+            },
+            ...xpGuards,
+            await accountStatePrecondition(attackerAccount, `Attacking Fleet ${attacker.name} retains its owner, Game, live state, crew, AP, faction, and ship composition.`),
+            await accountStatePrecondition(defenderAccount, `Defending Fleet ${defender.name} retains its owner, Game, live state, crew, faction, and ship composition.`),
         ],
         steps: [
             {
                 describes: description,
-                instruction: adaptAttackFleetInstruction({
-                    ...(attackerNpc.factionAccount === undefined
-                        ? {}
-                        : { attackerFactionAccount: attackerNpc.factionAccount }),
-                    ...(attackerNpc.ownership === undefined
-                        ? {}
-                        : { attackerFleetOwnership: attackerNpc.ownership }),
-                    attackerRewardsConfig: attackerRewards.config,
-                    ...(attackerRewards.contribution === undefined
-                        ? {}
-                        : { attackerRewardsContribution: attackerRewards.contribution }),
-                    ...(attackerRewards.epoch === undefined
-                        ? {}
-                        : { attackerRewardsEpoch: attackerRewards.epoch }),
-                    attackerRewardsRegistry: attackerRewards.registry,
-                    ...(defender.state.kind === 'mining'
-                        ? { asteroid: defender.state.asteroid.address }
-                        : {}),
-                    authorization: options.authorization,
-                    character,
-                    ...(crewBinding === undefined ? {} : { crewBinding }),
-                    defenderCharacter,
-                    ...(defenderNpc.ownership === undefined
-                        ? {}
-                        : { defenderFleetOwnership: defenderNpc.ownership }),
-                    defenderRewardsConfig: defenderRewards.config,
-                    ...(defenderRewards.contribution === undefined
-                        ? {}
-                        : { defenderRewardsContribution: defenderRewards.contribution }),
-                    ...(defenderRewards.epoch === undefined
-                        ? {}
-                        : { defenderRewardsEpoch: defenderRewards.epoch }),
-                    defenderRewardsRegistry: defenderRewards.registry,
-                    defendingFleet: defender.address,
-                    factionRelationTracker,
-                    fleet: attacker.address,
-                    game,
-                    loot: options.loot,
-                    recentSlothashes: 'SysvarS1otHashes111111111111111111111111111',
-                    regionTracker,
-                    stance: generatedStance(stance),
-                }),
+                instruction,
                 semantics: [{ kind: 'exclusive', scope: 'transaction' }],
                 signers: [options.authorization.authority, options.loot],
             },
@@ -639,18 +647,6 @@ function systemFingerprint(system) {
         version: system.version,
     }, (_key, value) => typeof value === 'bigint' ? value.toString() : value);
 }
-function starbaseFactionId(owner) {
-    switch (owner) {
-        case 'mud':
-            return 1;
-        case 'oni':
-            return 2;
-        case 'ustur':
-            return 3;
-        case 'unaligned':
-            return null;
-    }
-}
 /** Plans one singleton Fleet-on-Starbase attack without predicting its outcome.
  *
  * The planner validates the owned attacking Fleet, canonical target System and
@@ -676,32 +672,7 @@ function starbaseFactionId(owner) {
  * ```
  */
 export async function planFleetAttackStarbase(ctx, attacker, target, inputStance, inputOptions) {
-    const options = validateAttackOptions(inputOptions);
-    const stance = validateAttackStance(inputStance);
-    const game = requireGameAddress(ctx);
-    if (attacker.ownerProfile.address !== options.authorization.profile) {
-        fail(`Attacking Fleet ${attacker.address} does not belong to authorization Profile ${options.authorization.profile}. Choose an owned Fleet and retry.`, attacker.address);
-    }
-    if (options.loot === options.authorization.authority ||
-        options.loot === options.authorization.profile) {
-        fail(`The new Loot address ${options.loot} must be distinct from the authorization authority and Profile. Generate a separate Loot signer address and retry.`, options.loot);
-    }
-    if (attacker.game !== game) {
-        fail(`Attacking Fleet ${attacker.address} belongs to Game ${attacker.game}, not configured Game ${game}. Refresh the Fleet through this context and retry.`, attacker.address);
-    }
-    if (attacker.state.kind === 'destroyed') {
-        fail(`Attacking Fleet ${attacker.name} (${attacker.address}) is destroyed and cannot attack a Starbase. Refresh the Fleet after respawn and retry.`, attacker.address);
-    }
-    if (!Number.isSafeInteger(attacker.ap) ||
-        attacker.ap <= 0 ||
-        !Number.isSafeInteger(attacker.crewCount) ||
-        attacker.crewCount <= 0) {
-        fail(`Attacking Fleet ${attacker.name} (${attacker.address}) has no known positive AP or valid crew state. Wait for AP reload, refresh the Fleet, and retry.`, attacker.address);
-    }
-    if (attacker.ships.length === 0 ||
-        attacker.ships.some(({ quantity }) => quantity <= 0n)) {
-        fail(`Attacking Fleet ${attacker.name} (${attacker.address}) has no valid known ship composition. Refresh Fleet composition and retry.`, attacker.address);
-    }
+    const { game, options, stance } = validateAttack(ctx, attacker, inputStance, inputOptions);
     if (target.game !== game) {
         fail(`Target Star System ${target.address} belongs to Game ${target.game}, not configured Game ${game}. Refresh the target through this context and retry.`, target.address);
     }
@@ -720,9 +691,9 @@ export async function planFleetAttackStarbase(ctx, attacker, target, inputStance
         deriveRegionTrackerAddress(game),
         deriveFleetCrewBindingAddress(attacker.address),
     ]);
-    const [probeRelationsAccount, probeRegistryAccount] = await readContextRawAccounts(ctx, [
-        relationTrackerAddress,
-        registryAddress,
+    const [[probeRelationsAccount, probeRegistryAccount], attackerNpc] = await Promise.all([
+        readContextRawAccounts(ctx, [relationTrackerAddress, registryAddress]),
+        resolveNpcAccounts(ctx, attacker, true),
     ]);
     const probeRelations = factionRelationTrackerAccountDefinition.decode(requireAccount(probeRelationsAccount, relationTrackerAddress, `FactionRelationTracker ${relationTrackerAddress} is missing. Refresh faction relationships and retry.`));
     const probeRegistry = atlasRewardRegistryAccountDefinition.decode(requireAccount(probeRegistryAccount, registryAddress, `AtlasRewardRegistry ${registryAddress} is missing. Refresh reward configuration and retry.`));
@@ -733,12 +704,6 @@ export async function planFleetAttackStarbase(ctx, attacker, target, inputStance
         fail(`AtlasRewardRegistry ${registryAddress} belongs to another Game. Refresh the configured reward registry and retry.`, registryAddress);
     }
     const rewardConfigAddress = await deriveAtlasRewardConfigAddress(game, probeRegistry.activeConfigVersion);
-    const attackerOwnership = attacker.npcFactionId === 0
-        ? undefined
-        : await deriveFactionOwnershipAddress(game, 'fleet', attacker.address);
-    const attackerFaction = attacker.npcFactionId === 0
-        ? undefined
-        : await deriveFactionAccountAddress(game, attacker.npcFactionId);
     const requiresNpcEconomy = attacker.npcFactionId > 0 &&
         probeRelations.dynamicCaptureEnabled &&
         probeRelations.nemesisActive;
@@ -762,8 +727,6 @@ export async function planFleetAttackStarbase(ctx, attacker, target, inputStance
         character,
         regionTracker,
         crewBindingAddress,
-        ...(attackerOwnership === undefined ? [] : [attackerOwnership]),
-        ...(attackerFaction === undefined ? [] : [attackerFaction]),
         ...(factionEconomicsConfig === undefined ? [] : [factionEconomicsConfig]),
         ...(captorTreasury === undefined ? [] : [captorTreasury]),
     ];
@@ -799,7 +762,8 @@ export async function planFleetAttackStarbase(ctx, attacker, target, inputStance
     if (ownership === undefined && relations.dynamicCaptureEnabled) {
         fail(`Target Starbase ${target.address} requires canonical FactionOwnership while dynamic capture is enabled. Refresh Starbase ownership and retry.`, ownershipAddress);
     }
-    const legacyOwner = starbaseFactionId(target.starbase.owner);
+    // KingSystemTracker records an unaligned owner as null.
+    const legacyOwner = factionValue(target.starbase.owner) || null;
     if (ownership !== undefined &&
         (ownership.game !== game ||
             ownership.asset.kind !== 'starbase' ||
@@ -844,32 +808,10 @@ export async function planFleetAttackStarbase(ctx, attacker, target, inputStance
     const crewBinding = crewBindingAccount === undefined ? undefined : crewBindingAddress;
     if (crewBindingAccount !== undefined) {
         const data = fleetCrewBindingAccountDefinition.decode(crewBindingAccount);
-        if (data.fleet !== attacker.address ||
-            data.ownerProfile !== attacker.ownerProfile.address) {
+        if (!matchesFleetCrewBindingIdentity(data, attacker.address, attacker.ownerProfile.address)) {
             fail(`FleetCrewBinding ${crewBindingAddress} does not belong to Fleet ${attacker.address} and Profile ${attacker.ownerProfile.address}. Refresh the Fleet crew relationship and retry.`, crewBindingAddress);
         }
     }
-    const attackerNpc = {};
-    let attackerOwnershipAccount;
-    let attackerFactionAccount;
-    if (attackerOwnership !== undefined && attackerFaction !== undefined) {
-        attackerOwnershipAccount = requireAccount(current.get(attackerOwnership), attackerOwnership, `NPC Fleet ${attacker.address} has no canonical FactionOwnership. Refresh the Fleet faction relationship and retry.`);
-        const npcOwnership = factionOwnershipAccountDefinition.decode(attackerOwnershipAccount);
-        if (npcOwnership.game !== game ||
-            npcOwnership.asset.kind !== 'fleet' ||
-            npcOwnership.asset.fleet !== attacker.address ||
-            npcOwnership.controllingFactionId !== attacker.npcFactionId) {
-            fail(`NPC Fleet ${attacker.address} has no matching canonical FactionOwnership for faction ${String(attacker.npcFactionId)}. Refresh the Fleet and faction ownership relationship before retrying.`, attackerOwnership);
-        }
-        attackerFactionAccount = requireAccount(current.get(attackerFaction), attackerFaction, `Faction ${attackerFaction} is missing for NPC Fleet ${attacker.address}. Refresh the faction registry relationship and retry.`);
-        const npcFaction = factionAccountDefinition.decode(attackerFactionAccount);
-        if (npcFaction.game !== game ||
-            npcFaction.factionId !== attacker.npcFactionId) {
-            fail(`Faction ${attackerFaction} does not match NPC Fleet ${attacker.address}'s Game and faction id. Refresh the faction registry relationship before retrying.`, attackerFaction);
-        }
-        attackerNpc.ownership = attackerOwnership;
-        attackerNpc.factionAccount = attackerFaction;
-    }
     let economicsAccount;
     let treasuryAccount;
     if (factionEconomicsConfig !== undefined && captorTreasury !== undefined) {
@@ -928,21 +870,13 @@ export async function planFleetAttackStarbase(ctx, attacker, target, inputStance
                     'The optional Fleet crew binding remains unchanged.',
                 ],
             ]),
-        ...(attackerOwnershipAccount === undefined
+        ...(attackerNpc.ownership === undefined
             ? []
-            : [
-                [
-                    attackerOwnershipAccount,
-                    'NPC Fleet ownership remains unchanged.',
-                ],
-            ]),
-        ...(attackerFactionAccount === undefined
+            : [[attackerNpc.ownership, 'NPC Fleet ownership remains unchanged.']]),
+        ...(attackerNpc.faction === undefined
             ? []
             : [
-                [
-                    attackerFactionAccount,
-                    'The NPC faction account remains unchanged.',
-                ],
+                [attackerNpc.faction, 'The NPC faction account remains unchanged.'],
             ]),
         ...(economicsAccount === undefined
             ? []
@@ -960,29 +894,41 @@ export async function planFleetAttackStarbase(ctx, attacker, target, inputStance
                     'The dynamic-capture treasury remains unchanged.',
                 ],
             ]),
-    ].map(([account, describes]) => precondition(account, describes)));
+    ].map(([account, describes]) => accountStatePrecondition(account, describes)));
     const absencePreconditions = [
-        absentPrecondition(options.loot, `Loot account ${options.loot} remains absent until execution.`),
+        accountAbsentPrecondition(options.loot, `Loot account ${options.loot} remains absent until execution.`),
         ...(crewBindingAccount === undefined
             ? [
-                absentPrecondition(crewBindingAddress, 'Optional Fleet crew binding remains absent.'),
+                accountAbsentPrecondition(crewBindingAddress, 'Optional Fleet crew binding remains absent.'),
             ]
             : []),
     ];
+    const runtime = await resolveActionRuntime(ctx, {
+        mode: 'starbase-attack',
+        game,
+        system: target.address,
+        starbaseSeqId: starSystemAccountDefinition.decode(systemAccount).sequenceId,
+        character,
+    });
     const description = `Attack with Fleet ${attacker.name} (${attacker.address}) against the shared Starbase at ${target.name} (${target.address}) using ${stance.ammoUsage} ammunition; range, capture-cost debit outcome, randomness, rewards, Loot, damage, and final admissibility remain chain-authoritative.`;
-    return createPlan({
+    return buildPlannerPlan({
         kind: 'combat.attack-starbase',
-        preconditions: [...statePreconditions, ...absencePreconditions],
+        preconditions: [
+            ...statePreconditions,
+            ...absencePreconditions,
+            ...runtime.guards,
+        ],
         steps: [
             {
-                describes: description,
+                describes: `${description} ${runtime.description}`,
                 instruction: adaptAttackStarbaseInstruction({
-                    ...(attackerNpc.factionAccount === undefined
+                    ...runtime.accounts,
+                    ...(attackerNpc.faction === undefined
                         ? {}
-                        : { attackerFactionAccount: attackerNpc.factionAccount }),
+                        : { attackerFactionAccount: attackerNpc.faction.address }),
                     ...(attackerNpc.ownership === undefined
                         ? {}
-                        : { attackerFleetOwnership: attackerNpc.ownership }),
+                        : { attackerFleetOwnership: attackerNpc.ownership.address }),
                     authorization: options.authorization,
                     ...(captorTreasury === undefined ? {} : { captorTreasury }),
                     character,
@@ -1009,7 +955,7 @@ export async function planFleetAttackStarbase(ctx, attacker, target, inputStance
                 signers: [options.authorization.authority, options.loot],
             },
         ],
-        summary: description,
+        summary: `${description} ${runtime.description}`,
     });
 }
 function lootSnapshotFingerprint(loot) {
@@ -1025,7 +971,7 @@ function lootSnapshotFingerprint(loot) {
             item.exclusivityUnlockAtUnixSeconds,
             item.rewardReclaimAtUnixSeconds,
             item.inventory.sequenceId,
-            item.inventory.storageCostRaw,
+            item.inventory.usedStorageUnitsRaw,
             ...item.inventory.items
                 .map(({ cargo, quantityRaw }) => `${String(cargo.id)}:${String(quantityRaw)}`)
                 .sort(),
@@ -1045,7 +991,7 @@ function rawLootFingerprint(address, loot) {
             item.exclusivityUnlockAtUnixSeconds,
             item.rewardReclaimAtUnixSeconds,
             item.inventory.sequenceId,
-            item.inventory.storageCostRaw,
+            item.inventory.usedStorageUnitsRaw,
             ...item.inventory.amounts
                 .map(({ amount, cargoId }) => `${String(cargoId)}:${String(amount)}`)
                 .sort(),
@@ -1115,11 +1061,11 @@ export async function planFleetRetrieveLoot(ctx, fleet, loot, inputWant, inputOp
         ? undefined
         : loot.profile.address;
     const description = `Request ${selection.summary} from Loot ${loot.address} with Fleet ${fleet.name} (${fleet.address}); range, recent-slot randomness, cargo capacity, availability races, and final transfer quantities remain chain-authoritative.`;
-    return createPlan({
+    return buildPlannerPlan({
         kind: 'combat.retrieve-loot',
         preconditions: [
-            await precondition(fleetAccount, `Fleet ${fleet.name} retains its configured Game, owning Profile, idle state, and normalized crew.`),
-            await precondition(lootAccount, `Loot ${loot.address} retains its identity, creator, destroyer exclusivity, and requested known quantities.`),
+            await accountStatePrecondition(fleetAccount, `Fleet ${fleet.name} retains its configured Game, owning Profile, idle state, and normalized crew.`),
+            await accountStatePrecondition(lootAccount, `Loot ${loot.address} retains its identity, creator, destroyer exclusivity, and requested known quantities.`),
         ],
         steps: [
             {