@aephia/atlas-kit 0.5.0 → 0.6.0-next.2

package/dist/combat/actions/index.js

@@ -0,0 +1,1146 @@
+import { getAddressEncoder, 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 { lootAccountDefinition, } from '../../internal/c4/combat.js';
+import { deriveFleetAddress, fleetAccountDefinition, } from '../../internal/c4/fleet.js';
+import { deriveFleetCrewBindingAddress, fleetCrewBindingAccountDefinition, } 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 { 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 { readGameCombatConfiguration } from '../../registry/combat.js';
+import { resolveCargo, } from '../../registry/index.js';
+function invalid(field, value, acceptedRange, remedy) {
+    throw new InvalidActionInputError(field, value, acceptedRange, remedy);
+}
+function readRecord(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 assertKeys(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 === undefined ? unexpected : `missing ${missing}`, `exactly the fields ${[...required, ...optional].join(', ')}`, `Remove unknown fields and provide every required ${field} field before retrying.`);
+    }
+}
+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);
+    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);
+    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.');
+    }
+    return { authorization, loot: options.loot };
+}
+function validateAttackStance(value) {
+    const stance = readRecord(value, 'stance');
+    assertKeys(stance, 'stance', ['ammoUsage']);
+    if (stance.ammoUsage !== 'none' &&
+        stance.ammoUsage !== 'light' &&
+        stance.ammoUsage !== 'heavy') {
+        invalid('stance.ammoUsage', stance.ammoUsage, 'one of none, light, or heavy', 'Choose a documented Fleet attack ammunition stance before retrying.');
+    }
+    return { ammoUsage: stance.ammoUsage };
+}
+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);
+    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.');
+    }
+    return { atUnixSeconds: options.atUnixSeconds, authorization };
+}
+function denseArray(value, field) {
+    if (!Array.isArray(value)) {
+        return invalid(field, value, 'a dense ordered array', `Provide ${field} as a dense ordered array before retrying.`);
+    }
+    for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index)) {
+            invalid(field, value, 'a dense ordered array without holes', `Remove array holes from ${field} before retrying.`);
+        }
+    }
+    return value;
+}
+const U64_MAX = (1n << 64n) - 1n;
+// Measured by the boundary test using a distinct external fee payer, optional
+// certificate and Loot creator, and the exact generated instruction in the v0
+// message shape used by assembly.
+const RETRIEVE_LOOT_FIXED_TRANSACTION_BYTES = 599;
+const V0_TRANSACTION_SIZE_LIMIT_BYTES = 1_232;
+const MAX_RETRIEVE_LOOT_INSTRUCTION_DATA_BYTES = V0_TRANSACTION_SIZE_LIMIT_BYTES - RETRIEVE_LOOT_FIXED_TRANSACTION_BYTES;
+function validateLootSelection(value, loot, fleet, retrievingProfile, atUnixSeconds) {
+    const targets = denseArray(value, 'want');
+    if (targets.length === 0 || targets.length > 256) {
+        invalid('want', targets.length, 'between 1 and 256 requested Loot items', 'Request at least one available Loot item and no more than 256 before retrying.');
+    }
+    const seenTargets = new Set();
+    const generated = [];
+    const summary = [];
+    for (let targetPosition = 0; targetPosition < targets.length; targetPosition += 1) {
+        const field = `want[${String(targetPosition)}]`;
+        const target = readRecord(targets[targetPosition], field);
+        assertKeys(target, field, ['itemIndex', 'cargo']);
+        if (!Number.isSafeInteger(target.itemIndex) ||
+            target.itemIndex < 0 ||
+            target.itemIndex > 255) {
+            invalid(`${field}.itemIndex`, target.itemIndex, 'an integer from 0 through 255', 'Choose an existing Loot item index before retrying.');
+        }
+        const itemIndex = target.itemIndex;
+        if (seenTargets.has(itemIndex)) {
+            invalid(`${field}.itemIndex`, itemIndex, 'one unique Loot item index', 'Combine cargo for each Loot item into one target before retrying.');
+        }
+        seenTargets.add(itemIndex);
+        const item = loot.items[itemIndex];
+        if (item === undefined) {
+            invalid(`${field}.itemIndex`, itemIndex, `an available Loot item index below ${String(loot.items.length)}`, 'Refresh the Loot snapshot and select an existing item before retrying.');
+        }
+        if (item.destroyer.address !== fleet.address &&
+            atUnixSeconds < item.exclusivityUnlockAtUnixSeconds) {
+            fail(`Loot item ${String(itemIndex)} is exclusive to Fleet ${item.destroyer.address}, not Fleet ${fleet.address}. Use the destroying Fleet or wait for chain-authoritative exclusivity resolution before retrying.`, loot.address);
+        }
+        if (loot.profile.address !== retrievingProfile &&
+            atUnixSeconds < item.rewardReclaimAtUnixSeconds) {
+            fail(`Loot item ${String(itemIndex)} reward cargo is exclusive to Profile ${loot.profile.address}, not Profile ${retrievingProfile}, until ${String(item.rewardReclaimAtUnixSeconds)} Unix seconds. Use the reward-owning Profile or wait for chain-authoritative reward reclaim resolution before retrying.`, loot.address);
+        }
+        const cargoRequests = denseArray(target.cargo, `${field}.cargo`);
+        if (cargoRequests.length === 0 || cargoRequests.length > 65_536) {
+            invalid(`${field}.cargo`, cargoRequests.length, 'between 1 and 65536 requested cargo quantities', 'Request at least one known cargo quantity before retrying.');
+        }
+        const seenCargo = new Set();
+        const encoded = [];
+        for (let cargoPosition = 0; cargoPosition < cargoRequests.length; cargoPosition += 1) {
+            const cargoField = `${field}.cargo[${String(cargoPosition)}]`;
+            const request = readRecord(cargoRequests[cargoPosition], cargoField);
+            assertKeys(request, cargoField, ['cargoId', 'quantityRaw']);
+            if (!Number.isSafeInteger(request.cargoId) ||
+                request.cargoId < 0 ||
+                request.cargoId > 65_535) {
+                invalid(`${cargoField}.cargoId`, request.cargoId, 'an integer CargoId from 0 through 65535', 'Choose a cargo id present in the selected Loot item before retrying.');
+            }
+            const cargoId = request.cargoId;
+            if (seenCargo.has(cargoId)) {
+                invalid(`${cargoField}.cargoId`, cargoId, 'one unique CargoId per Loot item', 'Combine duplicate cargo quantities before retrying.');
+            }
+            seenCargo.add(cargoId);
+            if (typeof request.quantityRaw !== 'bigint' ||
+                request.quantityRaw <= 0n ||
+                request.quantityRaw > U64_MAX) {
+                invalid(`${cargoField}.quantityRaw`, request.quantityRaw, 'a positive raw-unit bigint fitting u64', 'Provide a positive raw cargo quantity no larger than u64 before retrying.');
+            }
+            const available = item.inventory.items.find(({ cargo }) => cargo.id === cargoId);
+            if (available === undefined ||
+                request.quantityRaw > available.quantityRaw) {
+                invalid(cargoField, { cargoId, quantityRaw: request.quantityRaw }, 'a known cargo id and quantity no greater than the selected Loot balance', 'Refresh the Loot snapshot and request no more than its known cargo quantity.');
+            }
+            encoded.push([cargoId, request.quantityRaw]);
+            summary.push(`${String(request.quantityRaw)} raw ${available.cargo.name}`);
+        }
+        generated.push([itemIndex, encoded]);
+    }
+    const instructionDataLength = sage
+        .getRetrieveLootInstructionDataEncoder()
+        .encode({
+        keyIndex: 0,
+        want: generated.map(([itemIndex, cargo]) => [
+            itemIndex,
+            cargo.map(([cargoId, quantity]) => [cargoId, quantity]),
+        ]),
+    }).length;
+    if (instructionDataLength > MAX_RETRIEVE_LOOT_INSTRUCTION_DATA_BYTES) {
+        invalid('want', instructionDataLength, `a selection encoding to at most ${String(MAX_RETRIEVE_LOOT_INSTRUCTION_DATA_BYTES)} instruction-data bytes`, 'Reduce the requested Loot items or cargo quantities so the singleton instruction fits one z.ink/Solana transaction.');
+    }
+    return { generated, summary: summary.join(', ') };
+}
+function fail(message, address) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', message, { address });
+}
+function requireAccount(account, address, message) {
+    return account ?? fail(message, address);
+}
+function stimulantFingerprint(stimulant) {
+    const effects = stimulant.effects
+        .map(({ charges, deltaBps, stackRuleId, statId }) => `${String(charges)}:${String(deltaBps)}:${String(stackRuleId)}:${String(statId)}`)
+        .join(',');
+    return [
+        stimulant.cargo.id,
+        stimulant.cargo.categoryId,
+        stimulant.cargo.mint,
+        stimulant.cargo.name,
+        stimulant.cargo.storageCost,
+        effects,
+    ].join('|');
+}
+function snapshotCargoFingerprint(fleet) {
+    const items = fleet.cargoHold.items
+        .map(({ amount, id }) => `${String(id)}:${String(amount)}`)
+        .sort()
+        .join(',');
+    return [fleet.cargoHold.seqId, fleet.cargoHold.storageCost, items].join('|');
+}
+function rawCargoFingerprint(fleet) {
+    const items = fleet.cargoHold.amounts
+        .map(({ amount, cargoId }) => `${String(cargoId)}:${String(amount)}`)
+        .sort()
+        .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
+ * membership, known cargo balance, crewed non-destroyed state, and fresh
+ * whole-account Fleet state. Permission, stacking, charge application, and
+ * combat arithmetic remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const fleet: FleetSnapshot;
+ * declare const stimulant: CombatStimulantDefinition;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planFleetApplyCombatStimulant(
+ *   ctx,
+ *   fleet,
+ *   stimulant,
+ *   { authorization },
+ * );
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planFleetApplyCombatStimulant(ctx, fleet, stimulant, input) {
+    const options = validateOptions(input);
+    const game = requireGameAddress(ctx);
+    if (fleet.ownerProfile.address !== options.authorization.profile) {
+        fail(`Fleet ${fleet.address} does not belong to authorization Profile ${options.authorization.profile}. Choose a Fleet owned by that Profile and retry.`, fleet.address);
+    }
+    if (fleet.game !== game) {
+        fail(`Fleet ${fleet.address} 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(`Fleet ${fleet.name} (${fleet.address}) is destroyed and cannot apply a combat stimulant. Respawn the Fleet, refresh it, and retry.`, fleet.address);
+    }
+    const combat = await readGameCombatConfiguration(ctx);
+    const definitions = await Promise.all(combat.data.stimulantDefinitions.definitions.map(async (definition) => ({
+        cargo: await resolveCargo(ctx, definition.cargoId),
+        effects: definition.effects,
+    })));
+    const requestedStimulant = stimulantFingerprint(stimulant);
+    const catalogued = definitions.find((candidate) => stimulantFingerprint(candidate) === requestedStimulant);
+    if (catalogued === undefined) {
+        fail(`Cargo ${String(stimulant.cargo.id)} (${stimulant.cargo.name}) is not an exact member of the configured Game's combat stimulant catalog. Select a stimulant from getCombatConfiguration(ctx), refresh it, and retry.`, game);
+    }
+    const knownBalance = fleet.cargoHold.items
+        .filter(({ id }) => id === catalogued.cargo.id)
+        .reduce((total, { amount }) => total + amount, 0n);
+    if (knownBalance <= 0n) {
+        fail(`Fleet ${fleet.name} (${fleet.address}) has ${String(knownBalance)} raw ${catalogued.cargo.name} in its cargo hold. Add at least one, refresh the Fleet, and retry.`, fleet.address);
+    }
+    const [currentAccount] = await readContextRawAccounts(ctx, [fleet.address]);
+    const account = requireAccount(currentAccount, fleet.address, `Fleet ${fleet.name} (${fleet.address}) is missing. Refresh Fleet discovery and retry applying ${catalogued.cargo.name}.`);
+    const current = fleetAccountDefinition.decode(account);
+    const snapshotFingerprint = [
+        fleet.address,
+        fleet.game,
+        fleet.ownerProfile.address,
+        fleet.name,
+        fleet.state.kind,
+        fleet.crewCount,
+        snapshotCargoFingerprint(fleet),
+    ].join('|');
+    const currentFingerprint = [
+        account.address,
+        current.game,
+        current.ownerProfile,
+        current.name,
+        current.state.kind,
+        current.crewCount,
+        rawCargoFingerprint(current),
+    ].join('|');
+    if ((await deriveFleetAddress(current)) !== fleet.address ||
+        currentFingerprint !== snapshotFingerprint) {
+        fail(`Fleet ${fleet.name} (${fleet.address}) changed or does not match its canonical Game, owner, label, state, crew count, or cargo hold. Refresh the Fleet through this context and retry.`, fleet.address);
+    }
+    if (current.crewCount <= 0) {
+        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({
+        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.`),
+        ],
+        steps: [
+            {
+                describes: description,
+                instruction: adaptApplyCombatStimulantInstruction({
+                    authorization: options.authorization,
+                    fleet: fleet.address,
+                    game,
+                    stimCargoId: catalogued.cargo.id,
+                }),
+                signers: [options.authorization.authority],
+            },
+        ],
+        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)}`)
+        .sort()
+        .join(',');
+}
+function rawShipFingerprint(fleet) {
+    return fleet.fleetShips
+        .map(({ quantity, shipId }) => `${String(shipId)}:${String(quantity)}`)
+        .sort()
+        .join(',');
+}
+function attackStateFingerprint(state) {
+    if (state.kind !== 'mining')
+        return state.kind;
+    return `${state.kind}:${typeof state.asteroid === 'string' ? state.asteroid : state.asteroid.address}`;
+}
+function attackFleetFingerprint(address, fleet, ships) {
+    return [
+        address,
+        fleet.address,
+        fleet.game,
+        fleet.ownerProfile.address,
+        fleet.name,
+        attackStateFingerprint(fleet.state),
+        fleet.crewCount,
+        fleet.ap,
+        fleet.faction,
+        fleet.npcFactionId,
+        ships,
+    ].join('|');
+}
+async function validateCurrentAttackFleet(fleet, account) {
+    const currentAccount = requireAccount(account, fleet.address, `Fleet ${fleet.name} (${fleet.address}) is missing. Refresh Fleet discovery and retry the attack.`);
+    const current = fleetAccountDefinition.decode(currentAccount);
+    const currentFingerprint = [
+        currentAccount.address,
+        currentAccount.address,
+        current.game,
+        current.ownerProfile,
+        current.name,
+        attackStateFingerprint(current.state),
+        current.crewCount,
+        current.ap,
+        current.faction,
+        current.npcFactionId,
+        rawShipFingerprint(current),
+    ].join('|');
+    if ((await deriveFleetAddress(current)) !== fleet.address ||
+        currentFingerprint !==
+            attackFleetFingerprint(fleet.address, fleet, shipFingerprint(fleet))) {
+        fail(`Fleet ${fleet.name} (${fleet.address}) changed or does not match its canonical Game, owner, label, state, crew, AP, faction, or ship composition. Refresh both Fleets and retry.`, fleet.address);
+    }
+    return currentAccount;
+}
+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)) {
+        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);
+    if (resolvedFaction === 0)
+        return { config, registry };
+    const [epochAddress, contributionAddress] = await Promise.all([
+        deriveLoyaltyEpochAddress(fleet.game, resolvedFaction, epochIndex),
+        deriveLoyaltyContributionAddress(fleet.game, fleet.ownerProfile.address, resolvedFaction, epochIndex),
+    ]);
+    const [[epoch], [contribution]] = await Promise.all([
+        ctx.data.readMany(loyaltyEpochAccountDefinition, [epochAddress]),
+        ctx.data.readMany(loyaltyContributionAccountDefinition, [
+            contributionAddress,
+        ]),
+    ]);
+    if (epoch !== undefined &&
+        (epoch.data.game !== fleet.game ||
+            epoch.data.factionId !== resolvedFaction ||
+            epoch.data.epochIndex !== epochIndex)) {
+        fail(`LoyaltyEpoch ${epochAddress} does not match Fleet ${fleet.address}'s Game, faction, and active reward epoch. Refresh reward relationships and retry.`, epochAddress);
+    }
+    if (contribution !== undefined &&
+        (contribution.data.game !== fleet.game ||
+            contribution.data.profile !== fleet.ownerProfile.address ||
+            contribution.data.factionId !== resolvedFaction ||
+            contribution.data.epochIndex !== epochIndex)) {
+        fail(`LoyaltyContribution ${contributionAddress} does not match Fleet ${fleet.address}'s Profile, Game, faction, and active reward epoch. Refresh reward relationships and retry.`, contributionAddress);
+    }
+    return {
+        config,
+        ...(contribution === undefined
+            ? {}
+            : { contribution: contribution.address }),
+        ...(epoch === undefined ? {} : { epoch: epoch.address }),
+        registry,
+    };
+}
+async function resolveNpcAccounts(ctx, fleet, requireFactionAccount) {
+    if (fleet.npcFactionId === 0)
+        return {};
+    const ownershipAddress = await deriveFactionOwnershipAddress(fleet.game, 'fleet', fleet.address);
+    const [ownership] = await ctx.data.readMany(factionOwnershipAccountDefinition, [ownershipAddress]);
+    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 };
+}
+function generatedStance(stance) {
+    return {
+        ammoUsage: stance.ammoUsage === 'none' ? 0 : stance.ammoUsage === 'light' ? 1 : 2,
+    };
+}
+/** Plans one singleton Fleet-on-Fleet attack without predicting its outcome.
+ *
+ * Range, randomness, recent slot hashes, final combat arithmetic, and chain
+ * races remain authoritative. This Plan cannot be combined with another
+ * gameplay instruction because the generated program contract requires a
+ * singleton transaction.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const attacker: FleetSnapshot;
+ * declare const defender: FleetSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * declare const loot: Address;
+ * const plan = await planFleetAttackFleet(
+ *   ctx,
+ *   attacker,
+ *   defender,
+ *   { ammoUsage: 'light' },
+ *   { authorization, loot },
+ * );
+ * ```
+ */
+export async function planFleetAttackFleet(ctx, attacker, defender, inputStance, inputOptions) {
+    const options = validateAttackOptions(inputOptions);
+    const stance = validateAttackStance(inputStance);
+    const game = requireGameAddress(ctx);
+    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);
+    }
+    const currentAccounts = await readContextRawAccounts(ctx, [
+        attacker.address,
+        defender.address,
+        options.loot,
+    ]);
+    if (currentAccounts[2] !== undefined) {
+        fail(`Loot account ${options.loot} already exists. Generate a new unused Loot signer address and retry.`, options.loot);
+    }
+    const [attackerAccount, defenderAccount] = await Promise.all([
+        validateCurrentAttackFleet(attacker, currentAccounts[0]),
+        validateCurrentAttackFleet(defender, currentAccounts[1]),
+    ]);
+    const registryAddress = await deriveAtlasRewardRegistryAddress(game);
+    const registry = await ctx.data.read(atlasRewardRegistryAccountDefinition, registryAddress);
+    if (registry.data.game !== game) {
+        fail(`AtlasRewardRegistry ${registryAddress} belongs to another Game. Refresh the configured reward registry and retry.`, registryAddress);
+    }
+    const rewardConfig = await deriveAtlasRewardConfigAddress(game, registry.data.activeConfigVersion);
+    const [attackerRewards, defenderRewards, crewBinding, attackerNpc, defenderNpc,] = await Promise.all([
+        resolveRewardAccounts(ctx, attacker, registryAddress, rewardConfig, registry.data.currentEpoch),
+        resolveRewardAccounts(ctx, defender, registryAddress, rewardConfig, registry.data.currentEpoch),
+        optionalCrewBinding(ctx, attacker),
+        resolveNpcAccounts(ctx, attacker, true),
+        resolveNpcAccounts(ctx, defender, false),
+    ]);
+    const [character, defenderCharacter, regionTracker, factionRelationTracker] = await Promise.all([
+        findCharacterPda(attacker.ownerProfile.address, game),
+        findCharacterPda(defender.ownerProfile.address, game),
+        deriveRegionTrackerAddress(game),
+        deriveFactionRelationTrackerAddress(game),
+    ]);
+    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({
+        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.`),
+        ],
+        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),
+                }),
+                semantics: [{ kind: 'exclusive', scope: 'transaction' }],
+                signers: [options.authorization.authority, options.loot],
+            },
+        ],
+        summary: description,
+    });
+}
+function systemFingerprint(system) {
+    return JSON.stringify({
+        address: system.address,
+        celestialBodyAddresses: system.celestialBodyAddresses,
+        connections: system.connections,
+        coordinates: system.coordinates,
+        game: system.game,
+        name: system.name,
+        regionId: system.regionId,
+        sequenceId: system.sequenceId,
+        starbase: system.starbase,
+        systemId: system.systemId,
+        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
+ * nested shared Starbase, configured faction ownership mode, reward
+ * configuration, and the optional dynamic-NPC capture economy. Range,
+ * capture-cost debit outcome, randomness, damage, rewards, and final
+ * admissibility remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const attacker: FleetSnapshot;
+ * declare const target: StarSystemSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * declare const loot: Address;
+ * const plan = await planFleetAttackStarbase(
+ *   ctx,
+ *   attacker,
+ *   target,
+ *   { ammoUsage: 'light' },
+ *   { authorization, loot },
+ * );
+ * ```
+ */
+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);
+    }
+    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);
+    }
+    if ((await deriveStarSystemAddress(game, target.systemId)) !== target.address) {
+        fail(`Target Star System ${target.address} is not the canonical member for Game ${game} and system id ${String(target.systemId)}. Refresh the target through this context and retry.`, target.address);
+    }
+    if (target.starbase === undefined) {
+        fail(`Target Star System ${target.name} (${target.address}) has no shared Starbase. Choose a System with a shared Starbase and retry.`, target.address);
+    }
+    const [relationTrackerAddress, ownershipAddress, registryAddress, kingTracker, character, regionTracker, crewBindingAddress,] = await Promise.all([
+        deriveFactionRelationTrackerAddress(game),
+        deriveFactionOwnershipAddress(game, 'starbase', target.address),
+        deriveAtlasRewardRegistryAddress(game),
+        deriveKingSystemTrackerAddress(game),
+        findCharacterPda(attacker.ownerProfile.address, game),
+        deriveRegionTrackerAddress(game),
+        deriveFleetCrewBindingAddress(attacker.address),
+    ]);
+    const [probeRelationsAccount, probeRegistryAccount] = await readContextRawAccounts(ctx, [
+        relationTrackerAddress,
+        registryAddress,
+    ]);
+    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.`));
+    if (probeRelations.game !== game) {
+        fail(`FactionRelationTracker ${relationTrackerAddress} belongs to another Game. Refresh faction relationships and retry.`, relationTrackerAddress);
+    }
+    if (probeRegistry.game !== game) {
+        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;
+    let factionEconomicsConfig;
+    let captorTreasury;
+    if (requiresNpcEconomy) {
+        [factionEconomicsConfig, captorTreasury] = await Promise.all([
+            deriveFactionEconomicsConfigAddress(game),
+            deriveFactionTreasuryAddress(game, attacker.npcFactionId),
+        ]);
+    }
+    const dependencyAddresses = [
+        attacker.address,
+        target.address,
+        options.loot,
+        relationTrackerAddress,
+        ...(probeRelations.dynamicCaptureEnabled ? [ownershipAddress] : []),
+        registryAddress,
+        rewardConfigAddress,
+        kingTracker,
+        character,
+        regionTracker,
+        crewBindingAddress,
+        ...(attackerOwnership === undefined ? [] : [attackerOwnership]),
+        ...(attackerFaction === undefined ? [] : [attackerFaction]),
+        ...(factionEconomicsConfig === undefined ? [] : [factionEconomicsConfig]),
+        ...(captorTreasury === undefined ? [] : [captorTreasury]),
+    ];
+    const dependencyAccounts = await readContextRawAccounts(ctx, dependencyAddresses);
+    const current = new Map(dependencyAddresses.map((address, index) => [
+        address,
+        dependencyAccounts[index],
+    ]));
+    if (current.get(options.loot) !== undefined) {
+        fail(`Loot account ${options.loot} already exists. Generate a new unused Loot signer address and retry.`, options.loot);
+    }
+    const attackerAccount = await validateCurrentAttackFleet(attacker, current.get(attacker.address));
+    const systemAccount = requireAccount(current.get(target.address), target.address, `Target Star System ${target.name} (${target.address}) is missing. Refresh world state and retry the attack.`);
+    const currentSystem = starSystemAccountDefinition.decode(systemAccount);
+    if ((await deriveStarSystemAddress(currentSystem.game, currentSystem.systemId)) !== target.address ||
+        systemFingerprint({ ...currentSystem, address: systemAccount.address }) !==
+            systemFingerprint(target)) {
+        fail(`Target Star System ${target.name} (${target.address}) changed or does not match its canonical Game, identity, sequence, or shared Starbase state. Refresh the target and retry.`, target.address);
+    }
+    const relationsAccount = requireAccount(current.get(relationTrackerAddress), relationTrackerAddress, `FactionRelationTracker ${relationTrackerAddress} is missing. Refresh faction relationships and retry.`);
+    const relations = factionRelationTrackerAccountDefinition.decode(relationsAccount);
+    if (relations.game !== game ||
+        relations.dynamicCaptureEnabled !== probeRelations.dynamicCaptureEnabled ||
+        relations.nemesisActive !== probeRelations.nemesisActive) {
+        fail(`FactionRelationTracker ${relationTrackerAddress} changed or belongs to another Game. Refresh faction relationships and retry.`, relationTrackerAddress);
+    }
+    const ownershipAccount = relations.dynamicCaptureEnabled
+        ? current.get(ownershipAddress)
+        : undefined;
+    const ownership = ownershipAccount === undefined
+        ? undefined
+        : factionOwnershipAccountDefinition.decode(ownershipAccount);
+    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);
+    if (ownership !== undefined &&
+        (ownership.game !== game ||
+            ownership.asset.kind !== 'starbase' ||
+            ownership.asset.system !== target.address ||
+            ownership.capturedSystemSequenceId !== currentSystem.sequenceId)) {
+        fail(`FactionOwnership ${ownershipAddress} does not match target Starbase ${target.address}'s Game, System, or current System generation sequence. Refresh Starbase ownership and retry.`, ownershipAddress);
+    }
+    const effectiveOwner = ownership?.controllingFactionId ?? legacyOwner;
+    const registryAccount = requireAccount(current.get(registryAddress), registryAddress, `AtlasRewardRegistry ${registryAddress} is missing. Refresh reward configuration and retry.`);
+    const registry = atlasRewardRegistryAccountDefinition.decode(registryAccount);
+    if (registry.game !== game ||
+        registry.activeConfigVersion !== probeRegistry.activeConfigVersion) {
+        fail(`AtlasRewardRegistry ${registryAddress} changed or belongs to another Game. Refresh the configured reward registry and retry.`, registryAddress);
+    }
+    const rewardConfigAccount = requireAccount(current.get(rewardConfigAddress), rewardConfigAddress, `AtlasRewardConfig ${rewardConfigAddress} is missing. Refresh reward configuration and retry.`);
+    const rewardConfig = atlasRewardConfigAccountDefinition.decode(rewardConfigAccount);
+    if (rewardConfig.game !== game ||
+        rewardConfig.configVersion !== registry.activeConfigVersion ||
+        rewardConfig.effectiveEpoch > registry.currentEpoch) {
+        fail(`AtlasRewardConfig ${rewardConfigAddress} does not match the configured Game and active registry version or is not yet effective for the current epoch. Refresh reward configuration and retry.`, rewardConfigAddress);
+    }
+    const kingAccount = requireAccount(current.get(kingTracker), kingTracker, `KingSystemTracker ${kingTracker} is missing. Refresh King-system ownership and retry.`);
+    const king = kingSystemTrackerAccountDefinition.decode(kingAccount);
+    const kingTarget = king.systems.find(({ systemId }) => systemId === currentSystem.systemId);
+    if (king.game !== game ||
+        kingTarget === undefined ||
+        kingTarget.factionId !== effectiveOwner) {
+        fail(`KingSystemTracker ${kingTracker} does not contain target System ${String(currentSystem.systemId)} with its current effective owner ${String(effectiveOwner)}. Refresh King-system ownership and retry.`, kingTracker);
+    }
+    const characterAccount = requireAccount(current.get(character), character, `Character ${character} is missing for Profile ${attacker.ownerProfile.address}. Refresh the Profile Character registration and retry.`);
+    const characterData = characterAccountDefinition.decode(characterAccount);
+    if (characterData.game !== game ||
+        characterData.playerProfile !== attacker.ownerProfile.address) {
+        fail(`Character ${character} does not match Profile ${attacker.ownerProfile.address} and configured Game ${game}. Refresh the Profile Character registration and retry.`, character);
+    }
+    const regionTrackerAccount = requireAccount(current.get(regionTracker), regionTracker, `RegionTracker ${regionTracker} is missing for configured Game ${game}. Refresh world region data and retry.`);
+    const regionTrackerData = regionTrackerAccountDefinition.decode(regionTrackerAccount);
+    if (regionTrackerData.game !== game) {
+        fail(`RegionTracker ${regionTracker} does not match configured Game ${game}. Refresh world region data and retry.`, regionTracker);
+    }
+    const crewBindingAccount = current.get(crewBindingAddress);
+    const crewBinding = crewBindingAccount === undefined ? undefined : crewBindingAddress;
+    if (crewBindingAccount !== undefined) {
+        const data = fleetCrewBindingAccountDefinition.decode(crewBindingAccount);
+        if (data.fleet !== attacker.address ||
+            data.ownerProfile !== 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) {
+        economicsAccount = requireAccount(current.get(factionEconomicsConfig), factionEconomicsConfig, `FactionEconomicsConfig ${factionEconomicsConfig} is missing. Refresh faction economics and retry.`);
+        treasuryAccount = requireAccount(current.get(captorTreasury), captorTreasury, `FactionTreasury ${captorTreasury} is missing. Refresh the captor treasury and retry.`);
+        const economics = factionEconomicsConfigAccountDefinition.decode(economicsAccount);
+        const treasury = factionTreasuryAccountDefinition.decode(treasuryAccount);
+        if (economics.game !== game) {
+            fail(`FactionEconomicsConfig ${factionEconomicsConfig} belongs to another Game. Refresh faction economics and retry.`, factionEconomicsConfig);
+        }
+        if (treasury.game !== game ||
+            treasury.factionId !== attacker.npcFactionId) {
+            fail(`FactionTreasury ${captorTreasury} does not match NPC attacker faction ${String(attacker.npcFactionId)} and the configured Game. Refresh the captor treasury and retry.`, captorTreasury);
+        }
+    }
+    const statePreconditions = await Promise.all([
+        [
+            attackerAccount,
+            `Attacking Fleet ${attacker.name} retains its owner, Game, live state, crew, AP, faction, and ship composition.`,
+        ],
+        [
+            systemAccount,
+            `Target Star System ${target.name} retains its canonical identity, sequence, and shared Starbase state.`,
+        ],
+        [relationsAccount, 'Faction combat gates remain unchanged.'],
+        ...(ownershipAccount === undefined
+            ? []
+            : [
+                [
+                    ownershipAccount,
+                    'Target Starbase ownership and generation remain unchanged.',
+                ],
+            ]),
+        [
+            registryAccount,
+            'The active reward registry version and epoch remain unchanged.',
+        ],
+        [
+            rewardConfigAccount,
+            'The active reward configuration remains unchanged.',
+        ],
+        [
+            kingAccount,
+            'King-system target membership and ownership remain unchanged.',
+        ],
+        [characterAccount, 'The attacking Profile Character remains canonical.'],
+        [
+            regionTrackerAccount,
+            'The configured Game RegionTracker remains canonical.',
+        ],
+        ...(crewBindingAccount === undefined
+            ? []
+            : [
+                [
+                    crewBindingAccount,
+                    'The optional Fleet crew binding remains unchanged.',
+                ],
+            ]),
+        ...(attackerOwnershipAccount === undefined
+            ? []
+            : [
+                [
+                    attackerOwnershipAccount,
+                    'NPC Fleet ownership remains unchanged.',
+                ],
+            ]),
+        ...(attackerFactionAccount === undefined
+            ? []
+            : [
+                [
+                    attackerFactionAccount,
+                    'The NPC faction account remains unchanged.',
+                ],
+            ]),
+        ...(economicsAccount === undefined
+            ? []
+            : [
+                [
+                    economicsAccount,
+                    'Dynamic-capture faction economics remain unchanged.',
+                ],
+            ]),
+        ...(treasuryAccount === undefined
+            ? []
+            : [
+                [
+                    treasuryAccount,
+                    'The dynamic-capture treasury remains unchanged.',
+                ],
+            ]),
+    ].map(([account, describes]) => precondition(account, describes)));
+    const absencePreconditions = [
+        absentPrecondition(options.loot, `Loot account ${options.loot} remains absent until execution.`),
+        ...(crewBindingAccount === undefined
+            ? [
+                absentPrecondition(crewBindingAddress, 'Optional Fleet crew binding remains absent.'),
+            ]
+            : []),
+    ];
+    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({
+        kind: 'combat.attack-starbase',
+        preconditions: [...statePreconditions, ...absencePreconditions],
+        steps: [
+            {
+                describes: description,
+                instruction: adaptAttackStarbaseInstruction({
+                    ...(attackerNpc.factionAccount === undefined
+                        ? {}
+                        : { attackerFactionAccount: attackerNpc.factionAccount }),
+                    ...(attackerNpc.ownership === undefined
+                        ? {}
+                        : { attackerFleetOwnership: attackerNpc.ownership }),
+                    authorization: options.authorization,
+                    ...(captorTreasury === undefined ? {} : { captorTreasury }),
+                    character,
+                    ...(crewBinding === undefined ? {} : { crewBinding }),
+                    ...(factionEconomicsConfig === undefined
+                        ? {}
+                        : { factionEconomicsConfig }),
+                    ...(ownershipAccount === undefined
+                        ? {}
+                        : { factionOwnership: ownershipAddress }),
+                    factionRelationTracker: relationTrackerAddress,
+                    fleet: attacker.address,
+                    game,
+                    kingTracker,
+                    loot: options.loot,
+                    recentSlothashes: 'SysvarS1otHashes111111111111111111111111111',
+                    regionTracker,
+                    rewardConfig: rewardConfigAddress,
+                    rewardRegistry: registryAddress,
+                    stance: generatedStance(stance),
+                    system: target.address,
+                }),
+                semantics: [{ kind: 'exclusive', scope: 'transaction' }],
+                signers: [options.authorization.authority, options.loot],
+            },
+        ],
+        summary: description,
+    });
+}
+function lootSnapshotFingerprint(loot) {
+    return [
+        loot.address,
+        loot.version,
+        loot.game.address,
+        loot.profile.address,
+        loot.coordinates.x,
+        loot.coordinates.y,
+        ...loot.items.map((item) => [
+            item.destroyer.address,
+            item.exclusivityUnlockAtUnixSeconds,
+            item.rewardReclaimAtUnixSeconds,
+            item.inventory.sequenceId,
+            item.inventory.storageCostRaw,
+            ...item.inventory.items
+                .map(({ cargo, quantityRaw }) => `${String(cargo.id)}:${String(quantityRaw)}`)
+                .sort(),
+        ].join(':')),
+    ].join('|');
+}
+function rawLootFingerprint(address, loot) {
+    return [
+        address,
+        loot.version,
+        loot.game,
+        loot.profile,
+        loot.coordinates.x,
+        loot.coordinates.y,
+        ...loot.items.map((item) => [
+            item.destroyer,
+            item.exclusivityUnlockAtUnixSeconds,
+            item.rewardReclaimAtUnixSeconds,
+            item.inventory.sequenceId,
+            item.inventory.storageCostRaw,
+            ...item.inventory.amounts
+                .map(({ amount, cargoId }) => `${String(cargoId)}:${String(amount)}`)
+                .sort(),
+        ].join(':')),
+    ].join('|');
+}
+/** Plans one transaction-exclusive retrieval from a loaded Loot snapshot.
+ *
+ * The planner validates the owned idle Fleet, Loot identity, destroyer
+ * exclusivity, and every requested known quantity. Range, recent-slot inputs,
+ * destination capacity, intervening races, and final acquired quantities
+ * remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const fleet: FleetSnapshot;
+ * declare const loot: LootSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planFleetRetrieveLoot(
+ *   ctx,
+ *   fleet,
+ *   loot,
+ *   [{ itemIndex: 0, cargo: [{ cargoId: 1, quantityRaw: 5n }] }],
+ *   { atUnixSeconds: 1_700_000_000n, authorization },
+ * );
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planFleetRetrieveLoot(ctx, fleet, loot, inputWant, inputOptions) {
+    const options = validateRetrieveOptions(inputOptions);
+    const game = requireGameAddress(ctx);
+    if (fleet.ownerProfile.address !== options.authorization.profile) {
+        fail(`Fleet ${fleet.address} does not belong to authorization Profile ${options.authorization.profile}. Choose an owned Fleet and retry.`, fleet.address);
+    }
+    if (fleet.game !== game) {
+        fail(`Fleet ${fleet.address} belongs to Game ${fleet.game}, not configured Game ${game}. Refresh the Fleet through this context and retry.`, fleet.address);
+    }
+    if (fleet.state.kind !== 'idle') {
+        fail(`Fleet ${fleet.name} (${fleet.address}) must be idle to retrieve Loot, but its loaded state is ${fleet.state.kind}. Settle or finish the current Fleet action, refresh it, and retry.`, fleet.address);
+    }
+    if (!Number.isSafeInteger(fleet.crewCount) || fleet.crewCount <= 0) {
+        fail(`Fleet ${fleet.name} (${fleet.address}) has no valid normalized crew and cannot retrieve Loot. Crew the Fleet, refresh it, and retry.`, fleet.address);
+    }
+    if (loot.game.address !== game) {
+        fail(`Loot ${loot.address} belongs to Game ${loot.game.address}, not configured Game ${game}. Refresh the Loot through this context and retry.`, loot.address);
+    }
+    const selection = validateLootSelection(inputWant, loot, fleet, options.authorization.profile, options.atUnixSeconds);
+    const [fleetAccountValue, lootAccountValue] = await readContextRawAccounts(ctx, [fleet.address, loot.address]);
+    const fleetAccount = requireAccount(fleetAccountValue, fleet.address, `Fleet ${fleet.name} (${fleet.address}) is missing. Refresh Fleet discovery and retry retrieving Loot.`);
+    const currentFleet = fleetAccountDefinition.decode(fleetAccount);
+    if ((await deriveFleetAddress(currentFleet)) !== fleet.address ||
+        currentFleet.game !== fleet.game ||
+        currentFleet.ownerProfile !== fleet.ownerProfile.address ||
+        currentFleet.name !== fleet.name ||
+        currentFleet.state.kind !== fleet.state.kind ||
+        currentFleet.crewCount !== fleet.crewCount) {
+        fail(`Fleet ${fleet.name} (${fleet.address}) changed or no longer matches its canonical Game, owner, label, idle state, or crew. Refresh the Fleet and retry.`, fleet.address);
+    }
+    const lootAccount = requireAccount(lootAccountValue, loot.address, `Loot ${loot.address} is no longer available. Refresh Loot discovery and choose an available account before retrying.`);
+    const currentLoot = lootAccountDefinition.decode(lootAccount);
+    if (rawLootFingerprint(lootAccount.address, currentLoot) !==
+        lootSnapshotFingerprint(loot)) {
+        fail(`Loot ${loot.address} changed or no longer matches its loaded identity, Profile, coordinates, exclusivity, or known inventory. Refresh the Loot snapshot and retry.`, loot.address);
+    }
+    const lootCreator = loot.profile.address === options.authorization.profile
+        ? 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({
+        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.`),
+        ],
+        steps: [
+            {
+                describes: description,
+                instruction: adaptRetrieveLootInstruction({
+                    authorization: options.authorization,
+                    fleet: fleet.address,
+                    game,
+                    loot: loot.address,
+                    ...(lootCreator === undefined ? {} : { lootCreator }),
+                    recentSlothashes: 'SysvarS1otHashes111111111111111111111111111',
+                    want: selection.generated.map(([itemIndex, cargo]) => [
+                        itemIndex,
+                        cargo.map(([cargoId, quantity]) => [cargoId, quantity]),
+                    ]),
+                }),
+                semantics: [{ kind: 'exclusive', scope: 'transaction' }],
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: description,
+    });
+}
+//# sourceMappingURL=index.js.map