@aephia/atlas-kit 0.0.0

package/dist/fleets/actions/index.js

@@ -0,0 +1,854 @@
+import { getAddressEncoder, getBytesEncoder, getProgramDerivedAddress, isAddress, } from '@solana/kit';
+import { InvalidActionInputError, SageSdkError } from '../../client/errors.js';
+import { readContextRawAccounts } from '../../client/reconciliation.js';
+import { deriveFleetAddress, fleetAccountDefinition, } from '../../internal/c4/fleet.js';
+import { deriveFleetCrewBindingAddress, fleetCrewBindingAccountDefinition, } from '../../internal/c4/fleet-crew-binding.js';
+import { deriveFactionRelationTrackerAddress, deriveRegionTrackerAddress, factionRelationTrackerAccountDefinition, regionTrackerAccountDefinition, } from '../../internal/c4/factions.js';
+import { sage } from '../../internal/c4/bindings.js';
+import { characterAccountDefinition, findCharacterPda, } from '../../internal/c4/identity.js';
+import { deriveStarbasePlayerAddress, starbasePlayerAccountDefinition, } from '../../internal/c4/starbase.js';
+import { buildStarSystemDiscoveryFilters, deriveStarSystemAddress, starSystemAccountDefinition, } from '../../internal/c4/world.js';
+import { requireGameAddress } from '../../internal/game-context.js';
+import { adaptDockedToIdleInstruction, adaptFleetSettleArrivalInstruction, adaptIdleToDockedInstruction, adaptStartSubwarpInstruction, adaptStopSubwarpInstruction, adaptWarpLaneInstruction, adaptWarpToCoordinateInstruction, validatePlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
+import { createPlan, } from '../../planning/index.js';
+const FLEET_STATE_IDLE = 'fleet.state.idle';
+const FLEET_STATE_MOVEMENT_STARTED = 'fleet.state.movement-started';
+function movementStartSemantics(fleet) {
+    return [
+        {
+            fact: FLEET_STATE_IDLE,
+            kind: 'requires',
+            resource: fleet,
+        },
+        {
+            from: FLEET_STATE_IDLE,
+            kind: 'transition',
+            resource: fleet,
+            to: FLEET_STATE_MOVEMENT_STARTED,
+        },
+    ];
+}
+function fail(message, address) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', message, { address });
+}
+function validateSettleArrivalOptions(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new InvalidActionInputError('options', value, 'an object containing only funder', 'Pass { funder } with one valid z.ink/Solana address before retrying.');
+    }
+    const record = value;
+    if (Object.keys(record).length !== 1 ||
+        !Object.hasOwn(record, 'funder') ||
+        typeof record.funder !== 'string' ||
+        !isAddress(record.funder)) {
+        throw new InvalidActionInputError('options.funder', record.funder, 'one valid z.ink/Solana account address and no other option fields', 'Set options.funder to the address that will fund Fleet arrival settlement before retrying.');
+    }
+    return { funder: record.funder };
+}
+function requireSettleArrivalState(fleet) {
+    switch (fleet.state.kind) {
+        case 'subwarp':
+        case 'warp':
+            return fleet.state.kind;
+        case 'idle':
+            return fail(`Fleet ${fleet.name} is idle and has no movement arrival to settle. Start a warp or subwarp movement, refresh the Fleet, and retry after or during that movement.`, fleet.address);
+        case 'docked':
+            return fail(`Fleet ${fleet.name} is docked and has no movement arrival to settle. Undock the Fleet, start a warp or subwarp movement, refresh it, and retry.`, fleet.address);
+        case 'mining':
+            return fail(`Fleet ${fleet.name} is mining, not moving toward an arrival. Stop mining through an appropriate game client, refresh the Fleet, and retry only after starting warp or subwarp movement.`, fleet.address);
+        case 'respawn':
+            return fail(`Fleet ${fleet.name} is in respawn, not warp or subwarp movement. Wait for the Fleet to finish respawning or advance it through an appropriate game client, refresh it, and retry only after starting movement.`, fleet.address);
+        case 'destroyed':
+            return fail(`Fleet ${fleet.name} is destroyed and cannot have a movement arrival settled. Respawn the Fleet through an appropriate game client, refresh it, and retry only after starting warp or subwarp movement.`, fleet.address);
+        case 'claimStakeTransfer':
+            return fail(`Fleet ${fleet.name} is in a claimStakeTransfer state, not movement. Finish the Claim Stake transfer, refresh the Fleet, and retry only after starting warp or subwarp movement.`, fleet.address);
+    }
+}
+const STOP_SUBWARP_REMEDIES = {
+    claimStakeTransfer: 'Finish the Claim Stake transfer',
+    destroyed: 'Respawn it',
+    docked: 'Undock it',
+    mining: 'Stop mining',
+    respawn: 'Wait for it to finish respawning',
+    warp: 'Let warp finish and settle its arrival',
+};
+function requireStopSubwarpState(fleet) {
+    const state = fleet.state.kind;
+    if (state === 'subwarp' || state === 'idle')
+        return;
+    fail(`Fleet ${fleet.name} is ${state} and cannot stop subwarp. ${STOP_SUBWARP_REMEDIES[state]}, start subwarp, refresh it, and retry.`, fleet.address);
+}
+function assertFleetOwner(fleet, authorization) {
+    if (fleet.ownerProfile.address !== authorization.profile) {
+        fail(`Fleet ${fleet.name} belongs to Profile ${fleet.ownerProfile.address}, not authorized Profile ${authorization.profile}. Use the owning Profile in PlanAuthorization, refresh the Fleet, and retry.`, fleet.address);
+    }
+}
+function requireDockedState(fleet) {
+    if (fleet.state.kind !== 'docked') {
+        fail(`Fleet ${fleet.name} is ${fleet.state.kind}, so it cannot undock; the Fleet must be docked at a Starbase. Dock the Fleet at a Starbase, refresh it, and retry.`, fleet.address);
+    }
+    return fleet.state;
+}
+function requireDockIdleState(fleet) {
+    if (fleet.state.kind !== 'idle') {
+        fail(`Fleet ${fleet.name} is ${fleet.state.kind}, so it cannot dock; the Fleet must be idle at a Starbase System coordinate. Finish or cancel the current Fleet action, refresh the Fleet, and retry docking.`, fleet.address);
+    }
+}
+function requireRawAccount(account, message, address) {
+    return account ?? fail(message, address);
+}
+function validateFleetRead(account, fleet, game, system, systemSequenceId) {
+    const data = fleetAccountDefinition.decode(account);
+    if (account.address !== fleet.address ||
+        data.game !== game ||
+        data.ownerProfile !== fleet.ownerProfile.address ||
+        data.state.kind !== 'docked' ||
+        data.state.system !== system ||
+        data.state.systemSeqId !== systemSequenceId) {
+        fail(`Fleet ${fleet.name} changed or no longer matches its configured Game, owner, address, or docked Star System. Refresh the Fleet and create a new undock Plan before retrying.`, fleet.address);
+    }
+    return data;
+}
+function validateCharacterRead(account, fleet, profile, game) {
+    const data = characterAccountDefinition.decode(account);
+    if (data.playerProfile !== profile || data.game !== game) {
+        fail(`Fleet ${fleet.name} cannot undock because the canonical Character does not match Profile ${profile} and the configured Game ${game}. Refresh or repair the Character registration for this Profile and Game before retrying.`, account.address);
+    }
+    return data;
+}
+async function validateSystemRead(account, fleet, game, systemSequenceId) {
+    const data = starSystemAccountDefinition.decode(account);
+    const canonicalAddress = await deriveStarSystemAddress(game, data.systemId);
+    if (data.game !== game ||
+        canonicalAddress !== account.address ||
+        data.sequenceId !== systemSequenceId) {
+        fail(`Fleet ${fleet.name} cannot undock because Star System ${account.address} does not match its configured Game, PDA, or docked sequence. Refresh the Fleet and System state before retrying.`, account.address);
+    }
+    return data;
+}
+function validateStarbasePlayerRead(account, fleet, profile, character, system, canonicalAddress, action = 'undock') {
+    const data = starbasePlayerAccountDefinition.decode(account);
+    if (account.address !== canonicalAddress ||
+        data.playerProfile !== profile ||
+        data.character !== character ||
+        data.system !== system) {
+        fail(`Fleet ${fleet.name} cannot ${action} because its Starbase Player does not match the Profile, Character, System, or canonical PDA. Refresh or repair the Starbase registration before retrying.`, account.address);
+    }
+    return data;
+}
+async function validateDockSystemRead(account, fleet, game, canonicalAddress, exactLocation) {
+    const data = starSystemAccountDefinition.decode(account);
+    const derivedAddress = await deriveStarSystemAddress(game, data.systemId);
+    if (account.address !== canonicalAddress ||
+        account.address !== derivedAddress ||
+        data.game !== game ||
+        !hasExactSystemLocation(account, exactLocation)) {
+        fail(`Fleet ${fleet.name} cannot dock because Star System ${canonicalAddress} does not match the configured Game, Fleet coordinate, or canonical PDA. Refresh the Fleet and galaxy before retrying.`, canonicalAddress);
+    }
+    return data;
+}
+function failNoDockableStarbase(fleet) {
+    return fail(`Fleet ${fleet.name} coordinate (${String(fleet.location.x)}, ${String(fleet.location.y)}) has no Starbase to dock at. Move the Fleet to a Starbase system first, refresh the Fleet and galaxy, and retry.`, fleet.address);
+}
+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 requireIdleState(fleet) {
+    if (fleet.state.kind !== 'idle') {
+        fail(`Fleet ${fleet.name} is ${fleet.state.kind}, so it cannot start coordinate movement; the Fleet must be idle at a coordinate. Finish or cancel the current Fleet action, refresh the Fleet, and retry.`, fleet.address);
+    }
+}
+function requireIdleLaneState(fleet) {
+    if (fleet.state.kind !== 'idle') {
+        fail(`Fleet ${fleet.name} is ${fleet.state.kind}, so it cannot warp through a lane; the Fleet must be idle at a Star System coordinate. Finish or cancel the current Fleet action, refresh the Fleet, and retry.`, fleet.address);
+    }
+}
+function validateCoordinateComponent(field, value) {
+    if (!Number.isFinite(value)) {
+        throw new InvalidActionInputError(field, value, 'a finite SAGE coordinate', `Set ${field} to a finite number before planning coordinate movement.`);
+    }
+    if (value < -128 || value >= 128) {
+        throw new InvalidActionInputError(field, value, 'an I8F56-encodable SAGE coordinate from -128 inclusive to 128 exclusive', `Set ${field} within the pinned movement instruction codec range before retrying.`);
+    }
+}
+function validateDestination(fleet, destination) {
+    validateCoordinateComponent('destination.x', destination.x);
+    validateCoordinateComponent('destination.y', destination.y);
+    if (destination.x === fleet.location.x &&
+        destination.y === fleet.location.y) {
+        failSameCoordinate(fleet, destination);
+    }
+}
+function failSameCoordinate(fleet, destination) {
+    return fail(`Fleet ${fleet.name} destination (${String(destination.x)}, ${String(destination.y)}) is its current coordinate. Choose a different coordinate and retry.`, fleet.address);
+}
+function validateCharacterForCoordinateMovement(account, fleet, profile, game, canonicalAddress, action = 'move') {
+    const data = characterAccountDefinition.decode(account);
+    if (account.address !== canonicalAddress ||
+        data.playerProfile !== profile ||
+        data.game !== game) {
+        fail(`Fleet ${fleet.name} cannot ${action} because the canonical Character does not match Profile ${profile} and the configured Game ${game}. Refresh or repair the Character registration for this Profile and Game before retrying.`, account.address);
+    }
+    return data;
+}
+async function validateIdleFleetRead(account, fleet, game, planName = 'coordinate movement') {
+    const data = fleetAccountDefinition.decode(account);
+    const canonicalAddress = await deriveFleetAddress(data);
+    if (account.address !== fleet.address ||
+        canonicalAddress !== fleet.address ||
+        data.game !== game ||
+        data.ownerProfile !== fleet.ownerProfile.address ||
+        data.state.kind !== 'idle' ||
+        data.location.x !== fleet.location.x ||
+        data.location.y !== fleet.location.y) {
+        fail(`Fleet ${fleet.name} changed or no longer matches its configured Game, owner, address, PDA, or idle coordinate. Refresh the Fleet and create a new ${planName} Plan before retrying.`, fleet.address);
+    }
+    const exact = sage.getFleetDecoder().decode(account.data);
+    return {
+        location: {
+            x: exact.location[0].raw,
+            y: exact.location[1].raw,
+        },
+    };
+}
+function validateRegionTrackerRead(account, fleet, game, canonicalAddress, action = 'move') {
+    const data = regionTrackerAccountDefinition.decode(account);
+    if (account.address !== canonicalAddress || data.game !== game) {
+        fail(`Fleet ${fleet.name} cannot ${action} because RegionTracker does not match the configured Game or canonical PDA: ${account.address}; refresh the world region data for the configured Game and retry.`, account.address);
+    }
+    return sage.getRegionTrackerDecoder().decode(account.data);
+}
+function validateCrewBindingRead(account, fleet, canonicalAddress) {
+    const data = fleetCrewBindingAccountDefinition.decode(account);
+    if (account.address !== canonicalAddress ||
+        data.fleet !== fleet.address ||
+        data.ownerProfile !== fleet.ownerProfile.address) {
+        fail(`FleetCrewBinding does not match Fleet ${fleet.address}, its owner Profile, or its canonical PDA: ${account.address}. Refresh the Fleet crew registration or remove the invalid binding before retrying.`, account.address);
+    }
+    return data;
+}
+function pointIsOnSegment(point, start, end) {
+    const cross = (point.y - start.y) * (end.x - start.x) -
+        (point.x - start.x) * (end.y - start.y);
+    return (cross === 0n &&
+        point.x >= (start.x < end.x ? start.x : end.x) &&
+        point.x <= (start.x > end.x ? start.x : end.x) &&
+        point.y >= (start.y < end.y ? start.y : end.y) &&
+        point.y <= (start.y > end.y ? start.y : end.y));
+}
+function regionContainsCoordinate(region, coordinate) {
+    const boundingBox = {
+        maxX: region.boundingBox.maxX.raw,
+        maxY: region.boundingBox.maxY.raw,
+        minX: region.boundingBox.minX.raw,
+        minY: region.boundingBox.minY.raw,
+    };
+    const border = region.border.map(([x, y]) => ({ x: x.raw, y: y.raw }));
+    if (border.length < 3 ||
+        coordinate.x < boundingBox.minX ||
+        coordinate.x > boundingBox.maxX ||
+        coordinate.y < boundingBox.minY ||
+        coordinate.y > boundingBox.maxY) {
+        return false;
+    }
+    let inside = false;
+    for (let index = 0; index < border.length; index += 1) {
+        const start = border[index];
+        const end = border[(index + 1) % border.length];
+        if (pointIsOnSegment(coordinate, start, end))
+            return true;
+        if (start.y > coordinate.y !== end.y > coordinate.y) {
+            const deltaY = end.y - start.y;
+            const pointSide = (coordinate.x - start.x) * deltaY;
+            const edgeSide = (coordinate.y - start.y) * (end.x - start.x);
+            if ((deltaY > 0n && pointSide < edgeSide) ||
+                (deltaY < 0n && pointSide > edgeSide)) {
+                inside = !inside;
+            }
+        }
+    }
+    return inside;
+}
+function resolveRegionId(tracker, coordinate, displayCoordinate, label, fleet, trackerAddress) {
+    const region = tracker.regions.unsizedList.find((candidate) => regionContainsCoordinate(candidate, coordinate));
+    if (region === undefined) {
+        fail(`Fleet ${fleet.name} ${label} coordinate (${String(displayCoordinate.x)}, ${String(displayCoordinate.y)}) cannot be mapped by RegionTracker ${trackerAddress}. Refresh the world region data or choose a coordinate inside a configured Region before retrying.`, trackerAddress);
+    }
+    return region.id;
+}
+function exactCoordinate(coordinate) {
+    const spec = { fractionalBits: 56, signed: true, totalBits: 64 };
+    return {
+        x: sage.FixedPoint.fromNumber(coordinate.x, spec).raw,
+        y: sage.FixedPoint.fromNumber(coordinate.y, spec).raw,
+    };
+}
+async function resolveCoordinateMovement(ctx, fleet, authorization, destination) {
+    const game = requireGameAddress(ctx);
+    const [character, regionTracker, crewBinding] = await Promise.all([
+        findCharacterPda(authorization.profile, game),
+        deriveRegionTrackerAddress(game),
+        deriveFleetCrewBindingAddress(fleet.address),
+    ]);
+    const [fleetCandidate, characterCandidate, regionCandidate, crewCandidate] = await readContextRawAccounts(ctx, [
+        fleet.address,
+        character,
+        regionTracker,
+        crewBinding,
+    ]);
+    const fleetAccount = requireRawAccount(fleetCandidate, `Fleet ${fleet.name} is no longer available at ${fleet.address}. Refresh the Fleet and retry planning coordinate movement.`, fleet.address);
+    const characterAccount = requireRawAccount(characterCandidate, `Fleet ${fleet.name} cannot move because its Profile has no canonical Character at ${character}. Create the Character for Profile ${authorization.profile} in the configured Game, refresh the Fleet, and retry.`, character);
+    const regionTrackerAccount = requireRawAccount(regionCandidate, `Fleet ${fleet.name} cannot move because the canonical RegionTracker ${regionTracker} is missing. Verify the configured Game and cluster, refresh the world region data, and retry.`, regionTracker);
+    const validatedFleet = await validateIdleFleetRead(fleetAccount, fleet, game);
+    const exactDestination = exactCoordinate(destination);
+    if (exactDestination.x === validatedFleet.location.x &&
+        exactDestination.y === validatedFleet.location.y) {
+        failSameCoordinate(fleet, destination);
+    }
+    validateCharacterForCoordinateMovement(characterAccount, fleet, authorization.profile, game, character);
+    const tracker = validateRegionTrackerRead(regionTrackerAccount, fleet, game, regionTracker);
+    if (crewCandidate !== undefined) {
+        validateCrewBindingRead(crewCandidate, fleet, crewBinding);
+    }
+    return {
+        character,
+        characterAccount,
+        ...(crewCandidate === undefined
+            ? {}
+            : { crewBinding, crewBindingAccount: crewCandidate }),
+        destinationRegionId: resolveRegionId(tracker, exactDestination, destination, 'destination', fleet, regionTracker),
+        fleetAccount,
+        regionTracker,
+        regionTrackerAccount,
+        startRegionId: resolveRegionId(tracker, validatedFleet.location, fleet.location, 'current', fleet, regionTracker),
+    };
+}
+async function planCoordinateMovement(mode, ctx, fleet, options) {
+    validatePlanAuthorization(options.authorization);
+    assertFleetOwner(fleet, options.authorization);
+    requireIdleState(fleet);
+    validateDestination(fleet, options.destination);
+    const game = requireGameAddress(ctx);
+    const resolved = await resolveCoordinateMovement(ctx, fleet, options.authorization, options.destination);
+    const common = {
+        authorization: options.authorization,
+        character: resolved.character,
+        ...(resolved.crewBinding === undefined
+            ? {}
+            : { crewBinding: resolved.crewBinding }),
+        destRegionId: resolved.destinationRegionId,
+        fleet: fleet.address,
+        game,
+        regionTracker: resolved.regionTracker,
+        startRegionId: resolved.startRegionId,
+    };
+    const instruction = mode === 'subwarp'
+        ? adaptStartSubwarpInstruction({
+            ...common,
+            toCoordinate: [options.destination.x, options.destination.y],
+        })
+        : adaptWarpToCoordinateInstruction({
+            ...common,
+            destination: [options.destination.x, options.destination.y],
+        });
+    const verb = mode === 'subwarp' ? 'Subwarp' : 'Warp';
+    const description = `${verb} fleet ${fleet.name} to coordinate (${String(options.destination.x)}, ${String(options.destination.y)}).`;
+    const accounts = [
+        await precondition(resolved.fleetAccount, `Fleet ${fleet.name} remains idle at coordinate (${String(fleet.location.x)}, ${String(fleet.location.y)}).`),
+        await precondition(resolved.characterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game.`),
+        await precondition(resolved.regionTrackerAccount, `The configured RegionTracker continues to map Fleet ${fleet.name}'s current and destination coordinates.`),
+        ...(resolved.crewBindingAccount === undefined
+            ? []
+            : [
+                await precondition(resolved.crewBindingAccount, `Fleet ${fleet.name}'s optional FleetCrewBinding remains assigned to the Fleet and owner Profile.`),
+            ]),
+    ];
+    return createPlan({
+        kind: mode === 'subwarp' ? 'fleet.subwarp' : 'fleet.warp-to-coordinate',
+        preconditions: accounts,
+        steps: [
+            {
+                describes: description,
+                instruction,
+                semantics: movementStartSemantics(fleet.address),
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: description,
+    });
+}
+async function deriveCurrencyCacheAddress(game) {
+    const [address] = await getProgramDerivedAddress({
+        programAddress: sage.SAGE_PROGRAM_ADDRESS,
+        seeds: [
+            getBytesEncoder().encode(new TextEncoder().encode('CurrencyConfig')),
+            getAddressEncoder().encode(game),
+        ],
+    });
+    return address;
+}
+function validateCurrencyCacheRead(account, fleet, game, canonicalAddress) {
+    const decoder = sage.getCurrencyConfigCacheDecoder();
+    const discriminator = sage.CURRENCY_CONFIG_CACHE_DISCRIMINATOR;
+    const validDiscriminator = discriminator.every((byte, index) => account.data[index] === byte);
+    if (account.address !== canonicalAddress ||
+        account.owner !== sage.SAGE_PROGRAM_ADDRESS ||
+        account.data.length !== decoder.fixedSize ||
+        !validDiscriminator) {
+        fail(`Fleet ${fleet.name} cannot use a warp lane because CurrencyCache ${account.address} does not match the configured Game, canonical PDA, owner, or pinned account layout. Refresh the Game currency configuration and retry.`, account.address);
+    }
+    const decoded = decoder.decode(account.data);
+    if (decoded.gameId !== game) {
+        fail(`Fleet ${fleet.name} cannot use a warp lane because CurrencyCache ${account.address} does not match the configured Game or canonical PDA. Refresh the Game currency configuration and retry.`, account.address);
+    }
+}
+async function validateLaneSystemRead(account, fleet, game, label) {
+    const data = starSystemAccountDefinition.decode(account);
+    const canonicalAddress = await deriveStarSystemAddress(game, data.systemId);
+    if (data.game !== game || account.address !== canonicalAddress) {
+        fail(`Fleet ${fleet.name} cannot use a warp lane because the ${label} Star System ${account.address} does not match the configured Game or canonical PDA. Refresh the galaxy and retry with a Star System from the configured Game.`, account.address);
+    }
+    return data;
+}
+function hasExactSystemLocation(account, location) {
+    starSystemAccountDefinition.decode(account);
+    const exact = sage.getStarSystemDecoder().decode(account.data);
+    return (exact.coordinates[0].raw === location.x &&
+        exact.coordinates[1].raw === location.y);
+}
+function validateFactionRelationTrackerRead(account, fleet, game, canonicalAddress) {
+    const data = factionRelationTrackerAccountDefinition.decode(account);
+    if (account.address !== canonicalAddress || data.game !== game) {
+        fail(`Fleet ${fleet.name} cannot use a warp lane because FactionRelationTracker ${account.address} does not match the configured Game or canonical PDA. Refresh the faction relation data and retry.`, account.address);
+    }
+}
+async function resolveWarpLane(ctx, fleet, options) {
+    const game = requireGameAddress(ctx);
+    const systems = await ctx.data.discover(starSystemAccountDefinition, {
+        filters: buildStarSystemDiscoveryFilters(game),
+        strategy: 'targeted-program-accounts',
+    });
+    const sourceCandidates = systems.filter((system) => system.data.coordinates.x === fleet.location.x &&
+        system.data.coordinates.y === fleet.location.y);
+    if (sourceCandidates.length === 0) {
+        fail(`Fleet ${fleet.name} idle coordinate (${String(fleet.location.x)}, ${String(fleet.location.y)}) does not match a Star System in the configured Game. Refresh the galaxy or move the Fleet to a Star System before retrying.`, fleet.address);
+    }
+    const [character, currencyCache, factionRelationTracker, regionTracker] = await Promise.all([
+        findCharacterPda(options.authorization.profile, game),
+        deriveCurrencyCacheAddress(game),
+        deriveFactionRelationTrackerAddress(game),
+        deriveRegionTrackerAddress(game),
+    ]);
+    const sourceOffset = 2;
+    const destinationOffset = sourceOffset + sourceCandidates.length;
+    const reads = await readContextRawAccounts(ctx, [
+        fleet.address,
+        character,
+        ...sourceCandidates.map((candidate) => candidate.address),
+        options.destinationSystem,
+        currencyCache,
+        factionRelationTracker,
+        regionTracker,
+    ]);
+    const fleetCandidate = reads[0];
+    const characterCandidate = reads[1];
+    const destinationCandidate = reads[destinationOffset];
+    const currencyCandidate = reads[destinationOffset + 1];
+    const factionCandidate = reads[destinationOffset + 2];
+    const regionCandidate = reads[destinationOffset + 3];
+    const fleetAccount = requireRawAccount(fleetCandidate, `Fleet ${fleet.name} is no longer available at ${fleet.address}. Refresh the Fleet and retry planning the warp lane.`, fleet.address);
+    const validatedFleet = await validateIdleFleetRead(fleetAccount, fleet, game);
+    const exactSourceCandidates = sourceCandidates.flatMap((candidate, index) => {
+        const account = reads[sourceOffset + index];
+        return account !== undefined &&
+            hasExactSystemLocation(account, validatedFleet.location)
+            ? [{ account, address: candidate.address }]
+            : [];
+    });
+    if (exactSourceCandidates.length !== 1) {
+        if (sourceCandidates.length === 1) {
+            const sourceSystem = sourceCandidates[0].address;
+            const sourceAccount = requireRawAccount(reads[sourceOffset], `Fleet ${fleet.name} cannot use a warp lane because source Star System ${sourceSystem} is missing. Refresh the Fleet and galaxy, then retry.`, sourceSystem);
+            const source = starSystemAccountDefinition.decode(sourceAccount);
+            fail(`Fleet ${fleet.name} idle coordinate (${String(fleet.location.x)}, ${String(fleet.location.y)}) no longer matches source Star System ${source.name}. Refresh the Fleet and galaxy before retrying.`, sourceSystem);
+        }
+        fail(`Fleet ${fleet.name} idle coordinate (${String(fleet.location.x)}, ${String(fleet.location.y)}) matches multiple Star Systems in the configured Game. Refresh the galaxy and repair the contradictory System data before retrying.`, fleet.address);
+    }
+    const { account: sourceAccount, address: sourceSystem } = exactSourceCandidates[0];
+    const characterAccount = requireRawAccount(characterCandidate, `Fleet ${fleet.name} cannot use a warp lane because its Profile has no canonical Character at ${character}. Create the Character for Profile ${options.authorization.profile} in the configured Game, refresh the Fleet, and retry.`, character);
+    const destinationAccount = requireRawAccount(destinationCandidate, `Fleet ${fleet.name} cannot use a warp lane because destination Star System ${options.destinationSystem} is missing. Choose a Star System in the configured Game, refresh the galaxy, and retry.`, options.destinationSystem);
+    const currencyCacheAccount = requireRawAccount(currencyCandidate, `Fleet ${fleet.name} cannot use a warp lane because canonical CurrencyCache ${currencyCache} is missing. Verify the configured Game and cluster, refresh the Game currency configuration, and retry.`, currencyCache);
+    const factionRelationTrackerAccount = requireRawAccount(factionCandidate, `Fleet ${fleet.name} cannot use a warp lane because canonical FactionRelationTracker ${factionRelationTracker} is missing. Verify the configured Game and cluster, refresh the faction relation data, and retry.`, factionRelationTracker);
+    const regionTrackerAccount = requireRawAccount(regionCandidate, `Fleet ${fleet.name} cannot use a warp lane because canonical RegionTracker ${regionTracker} is missing. Verify the configured Game and cluster, refresh the world region data, and retry.`, regionTracker);
+    validateCharacterForCoordinateMovement(characterAccount, fleet, options.authorization.profile, game, character);
+    const source = await validateLaneSystemRead(sourceAccount, fleet, game, 'source');
+    const destination = await validateLaneSystemRead(destinationAccount, fleet, game, 'destination');
+    validateCurrencyCacheRead(currencyCacheAccount, fleet, game, currencyCache);
+    validateFactionRelationTrackerRead(factionRelationTrackerAccount, fleet, game, factionRelationTracker);
+    validateRegionTrackerRead(regionTrackerAccount, fleet, game, regionTracker);
+    if (sourceSystem === options.destinationSystem) {
+        fail(`Fleet ${fleet.name} destination Star System ${source.name} is its current Star System. Choose a different connected Star System and retry.`, options.destinationSystem);
+    }
+    if (!source.connections.some((connection) => connection.systemId === destination.systemId)) {
+        fail(`Star System ${source.name} does not have a warp lane to Star System ${destination.name}. Choose a connected Star System from the source System's decoded connections and retry.`, options.destinationSystem);
+    }
+    return {
+        character,
+        characterAccount,
+        currencyCache,
+        currencyCacheAccount,
+        destination,
+        destinationAccount,
+        factionRelationTracker,
+        factionRelationTrackerAccount,
+        fleetAccount,
+        regionTracker,
+        regionTrackerAccount,
+        source,
+        sourceAccount,
+        sourceSystem,
+    };
+}
+/** Plans one explicit connected-system Fleet warp without local economics estimates.
+ *
+ * The planner resolves the source Star System from the idle Fleet coordinate,
+ * proves connectivity from that System's decoded connections, and resolves all
+ * generated instruction accounts internally.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const fleet: FleetSnapshot;
+ * declare const destinationSystem: Address;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planFleetWarpLane(ctx, fleet, {
+ *   authorization,
+ *   destinationSystem,
+ * });
+ * ```
+ */
+export async function planFleetWarpLane(ctx, fleet, options) {
+    validatePlanAuthorization(options.authorization);
+    assertFleetOwner(fleet, options.authorization);
+    requireIdleLaneState(fleet);
+    const game = requireGameAddress(ctx);
+    const resolved = await resolveWarpLane(ctx, fleet, options);
+    const description = `Warp fleet ${fleet.name} from Star System ${resolved.source.name} to Star System ${resolved.destination.name} via warp lane.`;
+    return createPlan({
+        kind: 'fleet.warp-lane',
+        preconditions: await Promise.all([
+            precondition(resolved.fleetAccount, `Fleet ${fleet.name} remains idle at source Star System ${resolved.source.name}.`),
+            precondition(resolved.characterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game.`),
+            precondition(resolved.sourceAccount, `Source Star System ${resolved.source.name} remains at Fleet ${fleet.name}'s coordinate with a connection to system id ${String(resolved.destination.systemId)}.`),
+            precondition(resolved.destinationAccount, `Destination Star System ${resolved.destination.name} remains system id ${String(resolved.destination.systemId)} in the configured Game.`),
+            precondition(resolved.currencyCacheAccount, 'The canonical CurrencyCache remains assigned to the configured Game.'),
+            precondition(resolved.factionRelationTrackerAccount, 'The canonical FactionRelationTracker remains assigned to the configured Game.'),
+            precondition(resolved.regionTrackerAccount, 'The canonical RegionTracker remains assigned to the configured Game.'),
+        ]),
+        steps: [
+            {
+                describes: description,
+                instruction: adaptWarpLaneInstruction({
+                    authorization: options.authorization,
+                    character: resolved.character,
+                    currencyCache: resolved.currencyCache,
+                    factionRelationTracker: resolved.factionRelationTracker,
+                    fleet: fleet.address,
+                    fromSystem: resolved.sourceSystem,
+                    game,
+                    regionTracker: resolved.regionTracker,
+                    toSystem: options.destinationSystem,
+                }),
+                semantics: movementStartSemantics(fleet.address),
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: description,
+    });
+}
+/** Plans one explicit Fleet subwarp to a coordinate without movement estimates.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const fleet: FleetSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planFleetSubwarp(ctx, fleet, {
+ *   authorization,
+ *   destination: { x: 12, y: -7 },
+ * });
+ * ```
+ */
+export function planFleetSubwarp(ctx, fleet, options) {
+    return planCoordinateMovement('subwarp', ctx, fleet, options);
+}
+/** Plans one explicit Fleet coordinate warp without movement estimates.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const fleet: FleetSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planFleetWarpToCoordinate(ctx, fleet, {
+ *   authorization,
+ *   destination: { x: 12, y: -7 },
+ * });
+ * ```
+ */
+export function planFleetWarpToCoordinate(ctx, fleet, options) {
+    return planCoordinateMovement('warp', ctx, fleet, options);
+}
+/** Plans settlement of one Fleet warp or subwarp arrival.
+ *
+ * Settlement is distinct from stopping subwarp early: the program completes an
+ * elapsed movement, while an in-transit call is a measured safe no-op. Subwarp
+ * settlement charges the fuel recorded when movement started; warp fuel was
+ * already charged up front. Settlement does not clear the independent warp
+ * cooldown, so an arrived Fleet can be idle but still unable to warp again.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const fleet: FleetSnapshot;
+ * declare const funder: Address;
+ * const plan = await planFleetSettleArrival(ctx, fleet, { funder });
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planFleetSettleArrival(ctx, fleet, input) {
+    const { funder } = validateSettleArrivalOptions(input);
+    const movement = requireSettleArrivalState(fleet);
+    const game = requireGameAddress(ctx);
+    const character = await findCharacterPda(fleet.ownerProfile.address, game);
+    const description = movement === 'subwarp'
+        ? `Settle fleet ${fleet.name} after subwarp arrival and charge the fuel recorded when subwarp started.`
+        : `Settle fleet ${fleet.name} after warp arrival; warp cooldown remains independent.`;
+    return createPlan({
+        kind: 'fleet.settle-arrival',
+        preconditions: [],
+        steps: [
+            {
+                describes: description,
+                instruction: adaptFleetSettleArrivalInstruction({
+                    character,
+                    fleet: fleet.address,
+                    funder,
+                    game,
+                }),
+                signers: [funder],
+            },
+        ],
+        summary: `Settle arrival for fleet ${fleet.name}.`,
+    });
+}
+/** Plans an early Fleet subwarp stop without signing, simulation, or write RPC.
+ *
+ * This operation stops an in-progress subwarp before arrival. Use
+ * {@link planFleetSettleArrival} for a trip already known to have completed;
+ * callers should not deliberately stop a completed trip. An idle Fleet is
+ * still accepted so the program's benign no-op handles the normal race where
+ * subwarp completes between planning and execution.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const fleet: FleetSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planFleetStopSubwarp(ctx, fleet, { authorization });
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planFleetStopSubwarp(ctx, fleet, options) {
+    validatePlanAuthorization(options.authorization);
+    assertFleetOwner(fleet, options.authorization);
+    requireStopSubwarpState(fleet);
+    const game = requireGameAddress(ctx);
+    const character = await findCharacterPda(options.authorization.profile, game);
+    const regionTracker = await deriveRegionTrackerAddress(game);
+    const [regionCandidate] = await readContextRawAccounts(ctx, [regionTracker]);
+    const regionTrackerAccount = requireRawAccount(regionCandidate, `Canonical RegionTracker ${regionTracker} is missing. Verify the configured Game and cluster, refresh world region data, and retry stopping Fleet ${fleet.name}.`, regionTracker);
+    validateRegionTrackerRead(regionTrackerAccount, fleet, game, regionTracker, 'stop subwarp');
+    const description = `Stop subwarp early for fleet ${fleet.name}; leave it idle if the trip already completed.`;
+    return createPlan({
+        kind: 'fleet.stop-subwarp',
+        preconditions: [],
+        steps: [
+            {
+                describes: description,
+                instruction: adaptStopSubwarpInstruction({
+                    authorization: options.authorization,
+                    character,
+                    fleet: fleet.address,
+                    game,
+                    regionTracker,
+                }),
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: `Stop subwarp for fleet ${fleet.name}.`,
+    });
+}
+/** Plans one explicit Fleet undock without signing, simulation, or write RPC.
+ *
+ * The planner accepts a loaded Fleet snapshot, resolves its canonical Character,
+ * docked Star System, and Starbase Player internally, and returns one inspectable
+ * docked-to-idle Plan.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const fleet: FleetSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planFleetUndock(ctx, fleet, { authorization });
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planFleetUndock(ctx, fleet, options) {
+    validatePlanAuthorization(options.authorization);
+    assertFleetOwner(fleet, options.authorization);
+    const docked = requireDockedState(fleet);
+    const game = requireGameAddress(ctx);
+    const characterAddress = await findCharacterPda(options.authorization.profile, game);
+    const starbasePlayerAddress = await deriveStarbasePlayerAddress(docked.system.address, characterAddress);
+    const [fleetCandidate, characterCandidate, systemCandidate, playerCandidate] = await readContextRawAccounts(ctx, [
+        fleet.address,
+        characterAddress,
+        docked.system.address,
+        starbasePlayerAddress,
+    ]);
+    const fleetAccount = requireRawAccount(fleetCandidate, `Fleet ${fleet.name} is no longer available at ${fleet.address}. Refresh the Fleet and retry planning the undock action.`, fleet.address);
+    const characterAccount = requireRawAccount(characterCandidate, `Fleet ${fleet.name} cannot undock because its Profile has no canonical Character at ${characterAddress}. Create the Character for Profile ${options.authorization.profile} in the configured Game, refresh the Fleet, and retry.`, characterAddress);
+    const systemAccount = requireRawAccount(systemCandidate, `Fleet ${fleet.name} is docked at Star System ${docked.system.address}, but that System account is missing. Verify the configured Game and cluster, refresh the Fleet, and retry.`, docked.system.address);
+    const playerAccount = requireRawAccount(playerCandidate, `Fleet ${fleet.name} cannot undock because its Starbase Player registration is missing at ${starbasePlayerAddress}. Register the Character at this Starbase, refresh the Fleet, and retry.`, starbasePlayerAddress);
+    validateFleetRead(fleetAccount, fleet, game, docked.system.address, docked.systemSeqId);
+    validateCharacterRead(characterAccount, fleet, options.authorization.profile, game);
+    const system = await validateSystemRead(systemAccount, fleet, game, docked.systemSeqId);
+    validateStarbasePlayerRead(playerAccount, fleet, options.authorization.profile, characterAddress, docked.system.address, starbasePlayerAddress);
+    const instruction = adaptDockedToIdleInstruction({
+        authorization: options.authorization,
+        fleet: fleet.address,
+        game,
+        systemAndStarbasePlayerStarbasePlayer: starbasePlayerAddress,
+        systemAndStarbasePlayerSystem: docked.system.address,
+    });
+    const description = `Undock fleet ${fleet.name} from the Starbase in Star System ${system.name}.`;
+    return createPlan({
+        kind: 'fleet.undock',
+        preconditions: await Promise.all([
+            precondition(fleetAccount, `Fleet ${fleet.name} remains docked at Star System ${system.name}.`),
+            precondition(characterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game.`),
+            precondition(systemAccount, `Star System ${system.name} remains the docked System for Fleet ${fleet.name}.`),
+            precondition(playerAccount, `The Starbase Player remains registered for Fleet ${fleet.name} at Star System ${system.name}.`),
+        ]),
+        steps: [
+            {
+                describes: description,
+                instruction,
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: `Undock fleet ${fleet.name} from Star System ${system.name}.`,
+    });
+}
+/** Plans one explicit Fleet dock without signing, simulation, or write RPC.
+ *
+ * The planner accepts a loaded idle Fleet snapshot, resolves the only canonical
+ * Character, Star System at its current coordinate, and Starbase Player
+ * internally, and returns one inspectable idle-to-docked Plan.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const fleet: FleetSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planFleetDock(ctx, fleet, { authorization });
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planFleetDock(ctx, fleet, options) {
+    validatePlanAuthorization(options.authorization);
+    assertFleetOwner(fleet, options.authorization);
+    requireDockIdleState(fleet);
+    const game = requireGameAddress(ctx);
+    const [fleetCandidate] = await readContextRawAccounts(ctx, [fleet.address]);
+    const fleetAccount = requireRawAccount(fleetCandidate, `Fleet ${fleet.name} is no longer available at ${fleet.address}. Refresh the Fleet and retry planning the dock action.`, fleet.address);
+    const validatedFleet = await validateIdleFleetRead(fleetAccount, fleet, game, 'dock');
+    const characterAddress = await findCharacterPda(options.authorization.profile, game);
+    const [characterCandidate] = await readContextRawAccounts(ctx, [
+        characterAddress,
+    ]);
+    const characterAccount = requireRawAccount(characterCandidate, `Fleet ${fleet.name} cannot dock because its Profile has no canonical Character at ${characterAddress}. Create the Character for Profile ${options.authorization.profile} in the configured Game, refresh the Fleet, and retry.`, characterAddress);
+    validateCharacterForCoordinateMovement(characterAccount, fleet, options.authorization.profile, game, characterAddress, 'dock');
+    const discoveredSystems = await ctx.data.discover(starSystemAccountDefinition, {
+        filters: buildStarSystemDiscoveryFilters(game),
+        strategy: 'targeted-program-accounts',
+    });
+    const matchingSystems = discoveredSystems.filter((system) => system.data.coordinates.x === fleet.location.x &&
+        system.data.coordinates.y === fleet.location.y);
+    if (matchingSystems.length === 0)
+        failNoDockableStarbase(fleet);
+    const systemCandidates = await readContextRawAccounts(ctx, matchingSystems.map((candidate) => candidate.address));
+    const exactSystems = matchingSystems.flatMap((candidate, index) => {
+        const account = systemCandidates[index];
+        return account !== undefined &&
+            hasExactSystemLocation(account, validatedFleet.location)
+            ? [{ account, address: candidate.address }]
+            : [];
+    });
+    if (exactSystems.length !== 1) {
+        if (matchingSystems.length === 1) {
+            const systemAddress = matchingSystems[0].address;
+            const systemAccount = systemCandidates[0] ?? failNoDockableStarbase(fleet);
+            await validateDockSystemRead(systemAccount, fleet, game, systemAddress, validatedFleet.location);
+        }
+        fail(`Fleet ${fleet.name} coordinate (${String(fleet.location.x)}, ${String(fleet.location.y)}) matches multiple Star Systems in the configured Game, so there is no canonical Starbase to dock at. Refresh the galaxy and repair the contradictory System data before retrying.`, fleet.address);
+    }
+    const { account: systemAccount, address: systemAddress } = exactSystems[0];
+    const system = await validateDockSystemRead(systemAccount, fleet, game, systemAddress, validatedFleet.location);
+    if (system.starbase === undefined)
+        failNoDockableStarbase(fleet);
+    const starbasePlayerAddress = await deriveStarbasePlayerAddress(systemAddress, characterAddress);
+    const [playerCandidate] = await readContextRawAccounts(ctx, [
+        starbasePlayerAddress,
+    ]);
+    const playerAccount = requireRawAccount(playerCandidate, `Fleet ${fleet.name} cannot dock because Character ${characterAddress} is not registered at Starbase ${system.name} in Star System ${systemAddress}. Register the Character at this Starbase before docking, refresh the Fleet, and retry.`, starbasePlayerAddress);
+    validateStarbasePlayerRead(playerAccount, fleet, options.authorization.profile, characterAddress, systemAddress, starbasePlayerAddress, 'dock');
+    const instruction = adaptIdleToDockedInstruction({
+        authorization: options.authorization,
+        fleet: fleet.address,
+        game,
+        systemAndStarbasePlayerStarbasePlayer: starbasePlayerAddress,
+        systemAndStarbasePlayerSystem: systemAddress,
+    });
+    const description = `Dock fleet ${fleet.name} at the Starbase in Star System ${system.name}.`;
+    return createPlan({
+        kind: 'fleet.dock',
+        preconditions: await Promise.all([
+            precondition(fleetAccount, `Fleet ${fleet.name} remains idle at Starbase System ${system.name} coordinate (${String(fleet.location.x)}, ${String(fleet.location.y)}).`),
+            precondition(characterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game.`),
+            precondition(systemAccount, `Star System ${system.name} remains the Starbase System at Fleet ${fleet.name} coordinate (${String(fleet.location.x)}, ${String(fleet.location.y)}).`),
+            precondition(playerAccount, `The Starbase Player remains registered for Fleet ${fleet.name} at Starbase ${system.name}.`),
+        ]),
+        steps: [
+            {
+                describes: description,
+                instruction,
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: `Dock fleet ${fleet.name} at Starbase ${system.name}.`,
+    });
+}
+//# sourceMappingURL=index.js.map