@aephia/atlas-kit 0.6.0-next.13 → 0.6.0-next.131

package/dist/fleets/actions/index.js

@@ -1,16 +1,26 @@
-import { getAddressEncoder, getBytesEncoder, getProgramDerivedAddress, isAddress, } from '@solana/kit';
+import { deriveCurrencyCache, validateCurrencyCache, } from '../../internal/c4/currency-cache.js';
+import { resolveDockFunding } from '../../internal/planning/fleet-dock-funding.js';
+import { validateFleetDockingPolicy } from '../../internal/planning/fleet-docking.js';
+import { deriveFactionOwnershipAddress } from '../../internal/c4/factions.js';
+import { regionContainsCoordinate } from '../../internal/c4/region-geometry.js';
+import { hashMovementCharacter } from '../../internal/planning/movement-character.js';
+import { resolveXpRuntime } from '../../internal/planning/xp-runtime.js';
+import { 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 { deriveFleetCrewBindingAddress, fleetCrewBindingAccountDefinition, matchesFleetCrewBindingIdentity, } 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 { FixedPoint, getFleetDecoder, getRegionTrackerDecoder, getStarSystemDecoder, } from '../../internal/c4/runtime-bindings.js';
+import { characterAccountDefinition, findCharacterPda, } from '../../internal/c4/character.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';
+import { adaptDockedToIdleInstruction, adaptIdleToDockedInstruction, adaptStartSubwarpInstruction, adaptStopSubwarpInstruction, adaptWarpLaneInstruction, adaptWarpToCoordinateInstruction, validatePlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
+import { buildPlannerPlan } from '../../planning/plan-construction.js';
+import { resolveFleetArrival } from '../../internal/planning/fleet-arrival.js';
+import { failFleetState, requireActionCoordinate, } from '../../internal/planning/fleet-state.js';
+import { accountStatePrecondition } from '../../internal/planning/account-state.js';
 const FLEET_STATE_IDLE = 'fleet.state.idle';
 const FLEET_STATE_MOVEMENT_STARTED = 'fleet.state.movement-started';
 function movementStartSemantics(fleet) {
@@ -32,50 +42,35 @@ function fail(message, address) {
     throw new SageSdkError('ACTION_PRECONDITION_FAILED', message, { address });
 }
 function validateSettleArrivalOptions(value) {
+    const remedy = 'Pass only { authorization: { profile, authority, keyIndex } } for Career XP subwarp. Certificates and delegated sub-Profiles are not supported.';
     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.');
+        throw new InvalidActionInputError('options', value, 'one explicit arrival authorization route', remedy);
     }
     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);
+    if (Object.keys(record).length === 1 &&
+        Object.hasOwn(record, 'authorization')) {
+        const auth = record.authorization;
+        if (auth !== null && typeof auth === 'object' && !Array.isArray(auth)) {
+            const fields = auth;
+            if (Object.keys(fields).length === 3 &&
+                Object.hasOwn(fields, 'keyIndex') &&
+                Object.hasOwn(fields, 'profile') &&
+                Object.hasOwn(fields, 'authority') &&
+                typeof fields.profile === 'string' &&
+                isAddress(fields.profile) &&
+                typeof fields.authority === 'string' &&
+                isAddress(fields.authority)) {
+                const authorization = {
+                    profile: fields.profile,
+                    authority: fields.authority,
+                    keyIndex: fields.keyIndex,
+                };
+                validatePlanAuthorization(authorization);
+                return { authorization };
+            }
+        }
     }
-}
-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);
+    throw new InvalidActionInputError('options', value, 'direct Profile authorization', remedy);
 }
 function assertFleetOwner(fleet, authorization) {
     if (fleet.ownerProfile.address !== authorization.profile) {
@@ -88,26 +83,15 @@ function requireDockedState(fleet) {
     }
     return fleet.state;
 }
-const REFRESH_TO_IDLE_REMEDIES = {
-    claimStakeTransfer: 'Wait for or complete the claim-stake transfer, refresh the Fleet, and retry.',
-    destroyed: 'Respawn the Fleet, refresh it, and retry.',
-    docked: 'Undock the Fleet, refresh it, and retry.',
-    mining: 'Stop mining, refresh the Fleet, and retry.',
-    respawn: 'Wait for the Fleet to recover, refresh it, and retry.',
-};
 function requireRefreshableIdleState(fleet, action) {
-    if (fleet.state.kind === 'idle')
-        return fleet.location;
-    if (fleet.state.kind === 'warp' || fleet.state.kind === 'subwarp') {
-        return fleet.state.to;
+    // Docking refreshes the Fleet without its Character, and a subwarp journey
+    // cannot be settled without one, so a dock Plan from a subwarp snapshot
+    // always fails on chain. Movement starts carry the Character and may refresh
+    // either journey.
+    if (action === 'dock' && fleet.state.kind === 'subwarp') {
+        fail(`Fleet ${fleet.name} is subwarp and cannot dock; docking refreshes the Fleet without its Character, so it cannot settle a subwarp journey. Settle the arrival with planFleetSettleArrival or stop the subwarp with planFleetStopSubwarp, refresh the Fleet, and retry.`, fleet.address);
     }
-    const remedy = REFRESH_TO_IDLE_REMEDIES[fleet.state.kind];
-    const requirement = action === 'dock'
-        ? 'the Fleet must be idle or in a refreshable warp/subwarp state at a Starbase System coordinate'
-        : action === 'warp through a lane'
-            ? 'the Fleet must be idle or in a refreshable warp/subwarp state at a Star System coordinate'
-            : 'the Fleet must be idle or in a refreshable warp/subwarp state at a coordinate';
-    fail(`Fleet ${fleet.name} is ${fleet.state.kind}, so it cannot ${action}; ${requirement}. ${remedy} Then retry ${action === 'dock' ? 'docking' : action}.`, fleet.address);
+    return requireActionCoordinate(fleet, action, `it must be idle or in a refreshable warp/subwarp state at ${action === 'dock' ? 'a Starbase System coordinate' : action === 'warp through a lane' ? 'a Star System coordinate' : 'a coordinate'}`);
 }
 function requireRawAccount(account, message, address) {
     return account ?? fail(message, address);
@@ -124,20 +108,14 @@ function validateFleetRead(account, fleet, game, system, systemSequenceId) {
     }
     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) {
+/** Requires a Star System of the configured Game at its canonical PDA and,
+ * for a docked Fleet, at the docked sequence. */
+async function validateFleetSystemRead(account, fleet, game, action, label = 'Star System', sequenceId) {
     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);
+        (await deriveStarSystemAddress(game, data.systemId)) !== account.address ||
+        (sequenceId !== undefined && data.sequenceId !== sequenceId)) {
+        fail(`Fleet ${fleet.name} cannot ${action} because ${label} ${account.address} does not match the configured Game${sequenceId === undefined ? ' or its canonical PDA' : ', its canonical PDA or the docked sequence'}. Refresh the Fleet and galaxy, then retry.`, account.address);
     }
     return data;
 }
@@ -151,36 +129,9 @@ function validateStarbasePlayerRead(account, fleet, profile, character, system,
     }
     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, location) {
     return fail(`Fleet ${fleet.name} action coordinate (${String(location.x)}, ${String(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 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.`);
@@ -189,25 +140,73 @@ function validateCoordinateComponent(field, value) {
         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, actionLocation, destination) {
+function validateDisplayDestination(fleet, actionLocation, destination) {
     validateCoordinateComponent('destination.x', destination.x);
     validateCoordinateComponent('destination.y', destination.y);
     if (destination.x === actionLocation.x &&
         destination.y === actionLocation.y) {
-        failSameCoordinate(fleet, destination);
+        failSameCoordinate(fleet, `destination (${String(destination.x)}, ${String(destination.y)})`);
     }
 }
 function failSameCoordinate(fleet, destination) {
-    return fail(`Fleet ${fleet.name} destination (${String(destination.x)}, ${String(destination.y)}) is its action coordinate. Choose a different coordinate and retry.`, fleet.address);
+    return fail(`Fleet ${fleet.name} ${destination} is its action 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 ||
+const SIGNED_I64_MIN = -(1n << 63n);
+const SIGNED_I64_MAX = (1n << 63n) - 1n;
+function validateRawCoordinateComponent(field, value) {
+    if (typeof value !== 'bigint') {
+        throw new InvalidActionInputError(field, value, 'a bigint containing the exact raw I8F56 axis', `Set ${field} to the signed 64-bit raw coordinate from the selected game value before retrying.`);
+    }
+    if (value < SIGNED_I64_MIN || value > SIGNED_I64_MAX) {
+        throw new InvalidActionInputError(field, value, `a signed 64-bit raw I8F56 bigint from ${String(SIGNED_I64_MIN)} through ${String(SIGNED_I64_MAX)}`, `Set ${field} within the exact movement instruction range before retrying.`);
+    }
+    return value;
+}
+function resolveCoordinateDestination(fleet, actionLocation, options) {
+    const hasDisplay = Object.hasOwn(options, 'destination');
+    const hasRaw = Object.hasOwn(options, 'destinationRaw');
+    if (hasDisplay === hasRaw) {
+        throw new InvalidActionInputError('destination/destinationRaw', options, 'exactly one of destination or destinationRaw', 'Set destination for caller-selected display rounding or destinationRaw for exact signed-I8F56 intent, omit the other property entirely, then retry.');
+    }
+    if (hasDisplay) {
+        const destination = options.destination;
+        if (destination === undefined || destination === null) {
+            throw new InvalidActionInputError('destination', destination, 'an object with finite numeric x and y axes', 'Set destination to display coordinates, or replace it with destinationRaw for exact signed-I8F56 intent.');
+        }
+        validateDisplayDestination(fleet, actionLocation, destination);
+        return {
+            description: `(${String(destination.x)}, ${String(destination.y)})`,
+            exact: exactCoordinate(destination),
+            field: 'destination',
+        };
+    }
+    const destinationRaw = options.destinationRaw;
+    if (destinationRaw === undefined ||
+        destinationRaw === null ||
+        typeof destinationRaw !== 'object') {
+        throw new InvalidActionInputError('destinationRaw', destinationRaw, 'an object with bigint x and y axes', 'Set destinationRaw to exact signed-I8F56 coordinates, or replace it with destination display coordinates.');
+    }
+    const exact = {
+        x: validateRawCoordinateComponent('destinationRaw.x', destinationRaw.x),
+        y: validateRawCoordinateComponent('destinationRaw.y', destinationRaw.y),
+    };
+    return {
+        description: `(${FixedPoint.fromRaw(exact.x, 56).toString()}, ${FixedPoint.fromRaw(exact.y, 56).toString()})`,
+        exact,
+        field: 'destinationRaw',
+    };
+}
+/** Requires the authorization Profile's canonical Character in the
+ * configured Game. */
+function requireFleetCharacter(account, fleet, profile, game, address, action) {
+    const character = requireRawAccount(account, `Fleet ${fleet.name} cannot ${action} because its Profile has no canonical Character at ${address}. Create the Character for Profile ${profile} in the configured Game, refresh the Fleet, and retry.`, address);
+    const data = characterAccountDefinition.decode(character);
+    if (character.address !== address ||
         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);
+        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.`, address);
     }
-    return data;
+    return character;
 }
 async function validateIdleFleetRead(account, fleet, game, actionLocation, planName = 'coordinate movement') {
     const data = fleetAccountDefinition.decode(account);
@@ -228,7 +227,7 @@ async function validateIdleFleetRead(account, fleet, game, actionLocation, planN
         stateLocation?.y !== actionLocation.y) {
         fail(`Fleet ${fleet.name} changed or no longer matches its configured Game, owner, address, PDA, or idle coordinate, movement state, and action coordinate. Refresh the Fleet and create a new ${planName} Plan before retrying.`, fleet.address);
     }
-    const exact = sage.getFleetDecoder().decode(account.data);
+    const exact = getFleetDecoder().decode(account.data);
     let exactLocation = exact.location;
     if (exact.state.__kind === 'MoveWarp') {
         exactLocation = exact.state.fields[0].to;
@@ -248,71 +247,31 @@ function validateRegionTrackerRead(account, fleet, game, canonicalAddress, actio
     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);
+    return 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) {
+        !matchesFleetCrewBindingIdentity(data, fleet.address, 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) {
+function resolveRegionId(tracker, coordinate, coordinateDescription, 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);
+        const errorDescription = label === 'destinationRaw'
+            ? `(${String(coordinate.x)}, ${String(coordinate.y)}) raw I8F56`
+            : coordinateDescription;
+        fail(`Fleet ${fleet.name} ${label} coordinate ${errorDescription} 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,
+        x: FixedPoint.fromNumber(coordinate.x, spec).raw,
+        y: FixedPoint.fromNumber(coordinate.y, spec).raw,
     };
 }
 async function resolveCoordinateMovement(ctx, fleet, authorization, actionLocation, destination) {
@@ -329,15 +288,13 @@ async function resolveCoordinateMovement(ctx, fleet, authorization, actionLocati
         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 characterAccount = requireFleetCharacter(characterCandidate, fleet, authorization.profile, game, character, 'move');
     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, actionLocation);
-    const exactDestination = exactCoordinate(destination);
-    if (exactDestination.x === validatedFleet.location.x &&
-        exactDestination.y === validatedFleet.location.y) {
-        failSameCoordinate(fleet, destination);
+    if (destination.exact.x === validatedFleet.location.x &&
+        destination.exact.y === validatedFleet.location.y) {
+        failSameCoordinate(fleet, `${destination.field} ${destination.description}`);
     }
-    validateCharacterForCoordinateMovement(characterAccount, fleet, authorization.profile, game, character);
     const tracker = validateRegionTrackerRead(regionTrackerAccount, fleet, game, regionTracker);
     if (crewCandidate !== undefined) {
         validateCrewBindingRead(crewCandidate, fleet, crewBinding);
@@ -348,21 +305,27 @@ async function resolveCoordinateMovement(ctx, fleet, authorization, actionLocati
         ...(crewCandidate === undefined
             ? {}
             : { crewBinding, crewBindingAccount: crewCandidate }),
-        destinationRegionId: resolveRegionId(tracker, exactDestination, destination, 'destination', fleet, regionTracker),
+        destinationRegionId: resolveRegionId(tracker, destination.exact, destination.description, destination.field, fleet, regionTracker),
         fleetAccount,
         regionTracker,
         regionTrackerAccount,
-        startRegionId: resolveRegionId(tracker, validatedFleet.location, actionLocation, 'current', fleet, regionTracker),
+        startRegionId: resolveRegionId(tracker, validatedFleet.location, `(${String(actionLocation.x)}, ${String(actionLocation.y)})`, 'current', fleet, regionTracker),
     };
 }
 async function planCoordinateMovement(mode, ctx, fleet, options) {
     validatePlanAuthorization(options.authorization);
     assertFleetOwner(fleet, options.authorization);
     const actionLocation = requireRefreshableIdleState(fleet, 'start coordinate movement');
-    validateDestination(fleet, actionLocation, options.destination);
+    const destination = resolveCoordinateDestination(fleet, actionLocation, options);
     const game = requireGameAddress(ctx);
-    const resolved = await resolveCoordinateMovement(ctx, fleet, options.authorization, actionLocation, options.destination);
+    const resolved = await resolveCoordinateMovement(ctx, fleet, options.authorization, actionLocation, destination);
+    const xp = await resolveXpRuntime(ctx, {
+        game,
+        character: resolved.character,
+        profile: options.authorization.profile,
+    });
     const common = {
+        ...xp.accounts,
         authorization: options.authorization,
         character: resolved.character,
         ...(resolved.crewBinding === undefined
@@ -377,27 +340,44 @@ async function planCoordinateMovement(mode, ctx, fleet, options) {
     const instruction = mode === 'subwarp'
         ? adaptStartSubwarpInstruction({
             ...common,
-            toCoordinate: [options.destination.x, options.destination.y],
+            toCoordinate: [destination.exact.x, destination.exact.y],
         })
         : adaptWarpToCoordinateInstruction({
             ...common,
-            destination: [options.destination.x, options.destination.y],
+            destination: [destination.exact.x, destination.exact.y],
         });
     const verb = mode === 'subwarp' ? 'Subwarp' : 'Warp';
-    const description = `${verb} fleet ${fleet.name} to coordinate (${String(options.destination.x)}, ${String(options.destination.y)}).`;
+    const description = `${verb} fleet ${fleet.name} to coordinate ${destination.description}.`;
     const accounts = [
-        await precondition(resolved.fleetAccount, fleet.state.kind === 'idle'
+        {
+            kind: 'xp-runtime',
+            address: game,
+            intent: xp.intent,
+            accounts: xp.accounts,
+            describes: 'The configured Game and canonical Character XP accounts remain eligible for movement.',
+        },
+        await accountStatePrecondition(resolved.fleetAccount, fleet.state.kind === 'idle'
             ? `Fleet ${fleet.name} remains idle at coordinate (${String(actionLocation.x)}, ${String(actionLocation.y)}).`
             : `Fleet ${fleet.name} remains ${fleet.state.kind} with action coordinate (${String(actionLocation.x)}, ${String(actionLocation.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.`),
+        {
+            kind: 'movement-character',
+            address: resolved.character,
+            game,
+            profile: options.authorization.profile,
+            stateHash: await hashMovementCharacter(resolved.characterAccount, {
+                game,
+                profile: options.authorization.profile,
+            }),
+            describes: 'The canonical Character retains its movement modifiers and non-accrual state.',
+        },
+        await accountStatePrecondition(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.`),
+                await accountStatePrecondition(resolved.crewBindingAccount, `Fleet ${fleet.name}'s optional FleetCrewBinding remains assigned to the Fleet and owner Profile.`),
             ]),
     ];
-    return createPlan({
+    return buildPlannerPlan({
         kind: mode === 'subwarp' ? 'fleet.subwarp' : 'fleet.warp-to-coordinate',
         preconditions: accounts,
         steps: [
@@ -411,45 +391,35 @@ async function planCoordinateMovement(mode, ctx, fleet, options) {
         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);
+    const exact = getStarSystemDecoder().decode(account.data);
     return (exact.coordinates[0].raw === location.x &&
         exact.coordinates[1].raw === location.y);
 }
+/** The Star Systems of the configured Game discovered at a Fleet's displayed
+ * action coordinate. */
+async function discoverSystemsAt(ctx, game, location) {
+    const systems = await ctx.data.discover(starSystemAccountDefinition, {
+        filters: buildStarSystemDiscoveryFilters(game),
+        strategy: 'targeted-program-accounts',
+    });
+    return systems
+        .filter(({ data }) => data.coordinates.x === location.x && data.coordinates.y === location.y)
+        .map(({ address }) => address);
+}
+/** Selects the one fresh candidate whose exact coordinate is the Fleet's. */
+function selectSystemAt(fleet, location, exact, candidates, accounts) {
+    const matches = accounts.filter((account) => account !== undefined && hasExactSystemLocation(account, exact));
+    if (matches.length === 1)
+        return matches[0];
+    const coordinate = `Fleet ${fleet.name} action coordinate (${String(location.x)}, ${String(location.y)})`;
+    if (candidates.length === 1) {
+        const [only] = accounts;
+        fail(`${coordinate} no longer matches Star System ${only === undefined ? candidates[0] : starSystemAccountDefinition.decode(only).name}. Refresh the Fleet and galaxy, then retry.`, candidates[0]);
+    }
+    return fail(`${coordinate} matches multiple Star Systems in the configured Game. Refresh the galaxy and repair the contradictory System data before retrying.`, fleet.address);
+}
 function validateFactionRelationTrackerRead(account, fleet, game, canonicalAddress) {
     const data = factionRelationTrackerAccountDefinition.decode(account);
     if (account.address !== canonicalAddress || data.game !== game) {
@@ -458,18 +428,13 @@ function validateFactionRelationTrackerRead(account, fleet, game, canonicalAddre
 }
 async function resolveWarpLane(ctx, fleet, actionLocation, 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 === actionLocation.x &&
-        system.data.coordinates.y === actionLocation.y);
+    const sourceCandidates = await discoverSystemsAt(ctx, game, actionLocation);
     if (sourceCandidates.length === 0) {
         fail(`Fleet ${fleet.name} action coordinate (${String(actionLocation.x)}, ${String(actionLocation.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),
+        deriveCurrencyCache(game).then(([address]) => address),
         deriveFactionRelationTrackerAddress(game),
         deriveRegionTrackerAddress(game),
     ]);
@@ -478,7 +443,7 @@ async function resolveWarpLane(ctx, fleet, actionLocation, options) {
     const reads = await readContextRawAccounts(ctx, [
         fleet.address,
         character,
-        ...sourceCandidates.map((candidate) => candidate.address),
+        ...sourceCandidates,
         options.destinationSystem,
         currencyCache,
         factionRelationTracker,
@@ -491,33 +456,17 @@ async function resolveWarpLane(ctx, fleet, actionLocation, options) {
     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, actionLocation);
-    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} action coordinate (${String(actionLocation.x)}, ${String(actionLocation.y)}) no longer matches source Star System ${source.name}. Refresh the Fleet and galaxy before retrying.`, sourceSystem);
-        }
-        fail(`Fleet ${fleet.name} action coordinate (${String(actionLocation.x)}, ${String(actionLocation.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 validatedFleet = await validateIdleFleetRead(fleetAccount, fleet, game, actionLocation, 'warp lane');
+    const sourceAccount = selectSystemAt(fleet, actionLocation, validatedFleet.location, sourceCandidates, reads.slice(sourceOffset, destinationOffset));
+    const sourceSystem = sourceAccount.address;
+    const characterAccount = requireFleetCharacter(characterCandidate, fleet, options.authorization.profile, game, character, 'use a warp lane');
     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);
+    const source = await validateFleetSystemRead(sourceAccount, fleet, game, 'use a warp lane', 'source Star System');
+    const destination = await validateFleetSystemRead(destinationAccount, fleet, game, 'use a warp lane', 'destination Star System');
+    await validateCurrencyCache(currencyCacheAccount, game, 'warp lane');
     validateFactionRelationTrackerRead(factionRelationTrackerAccount, fleet, game, factionRelationTracker);
     validateRegionTrackerRead(regionTrackerAccount, fleet, game, regionTracker);
     if (sourceSystem === options.destinationSystem) {
@@ -547,7 +496,15 @@ async function resolveWarpLane(ctx, fleet, actionLocation, options) {
  *
  * The planner resolves the source Star System from the Fleet's action coordinate,
  * proves connectivity from that System's decoded connections, and resolves all
- * generated instruction accounts internally.
+ * generated instruction accounts internally. CurrencyCache shared accounting may
+ * change; canonical identity/layout and the existing toll-input guards remain
+ * checked before signing. Refresh and recreate older Plans to use this guard.
+ *
+ * Connectivity does not guarantee eligibility. The program remains authoritative
+ * for faction-relationship and destination-risk checks and any ATLAS toll.
+ * Tested current PTR routes succeed with empty Fuel tanks. This planner does
+ * not estimate lane costs or treat enabled cross-faction economics as blanket
+ * permission.
  *
  * @example
  * ```ts
@@ -567,24 +524,54 @@ export async function planFleetWarpLane(ctx, fleet, options) {
     const actionLocation = requireRefreshableIdleState(fleet, 'warp through a lane');
     const game = requireGameAddress(ctx);
     const resolved = await resolveWarpLane(ctx, fleet, actionLocation, options);
+    const xp = await resolveXpRuntime(ctx, {
+        game,
+        character: resolved.character,
+        profile: options.authorization.profile,
+    });
     const description = `Warp fleet ${fleet.name} from Star System ${resolved.source.name} to Star System ${resolved.destination.name} via warp lane.`;
-    return createPlan({
+    return buildPlannerPlan({
         kind: 'fleet.warp-lane',
-        preconditions: await Promise.all([
-            precondition(resolved.fleetAccount, fleet.state.kind === 'idle'
-                ? `Fleet ${fleet.name} remains idle at Star System ${resolved.source.name}.`
-                : `Fleet ${fleet.name} remains ${fleet.state.kind} at action 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 action 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.'),
-        ]),
+        preconditions: [
+            {
+                kind: 'xp-runtime',
+                address: game,
+                intent: xp.intent,
+                accounts: xp.accounts,
+                describes: 'The configured Game and canonical Character XP accounts remain eligible for movement.',
+            },
+            ...(await Promise.all([
+                accountStatePrecondition(resolved.fleetAccount, fleet.state.kind === 'idle'
+                    ? `Fleet ${fleet.name} remains idle at Star System ${resolved.source.name}.`
+                    : `Fleet ${fleet.name} remains ${fleet.state.kind} at action source Star System ${resolved.source.name}.`),
+                hashMovementCharacter(resolved.characterAccount, {
+                    game,
+                    profile: options.authorization.profile,
+                }).then((stateHash) => ({
+                    kind: 'movement-character',
+                    address: resolved.character,
+                    game,
+                    profile: options.authorization.profile,
+                    stateHash,
+                    describes: 'The canonical Character retains its movement modifiers and non-accrual state.',
+                })),
+                accountStatePrecondition(resolved.sourceAccount, `Source Star System ${resolved.source.name} remains at Fleet ${fleet.name}'s action coordinate with a connection to system id ${String(resolved.destination.systemId)}.`),
+                accountStatePrecondition(resolved.destinationAccount, `Destination Star System ${resolved.destination.name} remains system id ${String(resolved.destination.systemId)} in the configured Game.`),
+                Promise.resolve({
+                    kind: 'currency-cache',
+                    address: resolved.currencyCacheAccount.address,
+                    game,
+                    describes: 'The canonical CurrencyCache retains its supported Game identity and layout; shared accounting may change.',
+                }),
+                accountStatePrecondition(resolved.factionRelationTrackerAccount, 'The canonical FactionRelationTracker remains assigned to the configured Game.'),
+                accountStatePrecondition(resolved.regionTrackerAccount, 'The canonical RegionTracker remains assigned to the configured Game.'),
+            ])),
+        ],
         steps: [
             {
                 describes: description,
                 instruction: adaptWarpLaneInstruction({
+                    ...xp.accounts,
                     authorization: options.authorization,
                     character: resolved.character,
                     currencyCache: resolved.currencyCache,
@@ -602,7 +589,7 @@ export async function planFleetWarpLane(ctx, fleet, options) {
         summary: description,
     });
 }
-/** Plans one explicit Fleet subwarp to a coordinate without movement estimates.
+/** Plans one explicit Fleet subwarp to a display or exact raw coordinate without movement estimates.
  *
  * @example
  * ```ts
@@ -611,14 +598,14 @@ export async function planFleetWarpLane(ctx, fleet, options) {
  * declare const authorization: PlanAuthorization;
  * const plan = await planFleetSubwarp(ctx, fleet, {
  *   authorization,
- *   destination: { x: 12, y: -7 },
+ *   destinationRaw: { x: 12n << 56n, y: -(7n << 56n) },
  * });
  * ```
  */
 export function planFleetSubwarp(ctx, fleet, options) {
     return planCoordinateMovement('subwarp', ctx, fleet, options);
 }
-/** Plans one explicit Fleet coordinate warp without movement estimates.
+/** Plans one explicit Fleet coordinate warp to a display or exact raw coordinate without movement estimates.
  *
  * @example
  * ```ts
@@ -627,54 +614,80 @@ export function planFleetSubwarp(ctx, fleet, options) {
  * declare const authorization: PlanAuthorization;
  * const plan = await planFleetWarpToCoordinate(ctx, fleet, {
  *   authorization,
- *   destination: { x: 12, y: -7 },
+ *   destinationRaw: { x: 12n << 56n, y: -(7n << 56n) },
  * });
  * ```
  */
 export function planFleetWarpToCoordinate(ctx, fleet, options) {
     return planCoordinateMovement('warp', ctx, fleet, options);
 }
-/** Plans settlement of one Fleet warp or subwarp arrival.
+/** Plans settlement after chain time confirms the scheduled Fleet journey duration has elapsed.
  *
- * 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.
+ * Game version 2 subwarp requires explicit direct Profile authorization and
+ * existing reconciled Career XP accounts. Warp settlement is unsupported.
+ * Journeys whose scheduled duration has not elapsed and Idle Fleets fail locally.
+ * Planning and execution read fresh accounts; no host clock is used.
+ *
+ * Settlement does not guarantee reaching the destination: insufficient Fuel can
+ * leave the Fleet Idle short of it. Low Fuel produces a planning-time warning,
+ * not a rejection. Inspect refreshed state and location after confirmation.
+ * Subwarp settles fuel and XP and may refund released storage rent to the
+ * Profile. Warp cooldown remains independent. Fresh checks cannot prevent a
+ * concurrent transaction from starting another journey before execution; the
+ * authorized instruction could stop that new journey. Intentional early
+ * stopping remains the separate {@link planFleetStopSubwarp} operation.
  *
  * @example
  * ```ts
  * declare const ctx: SageContext;
  * declare const fleet: FleetSnapshot;
- * declare const funder: Address;
- * const plan = await planFleetSettleArrival(ctx, fleet, { funder });
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planFleetSettleArrival(ctx, fleet, { authorization });
  * 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({
+    const options = validateSettleArrivalOptions(input);
+    const { intent, character, regionTracker, xp, lowFuel } = await resolveFleetArrival(ctx, fleet.address, options);
+    const fuelWarning = lowFuel
+        ? ' Fuel is below the recorded journey budget (at planning); may stop short with no Fuel.'
+        : '';
+    const description = `Settle subwarp: fuel and Career XP; possible rent refund to Profile ${intent.profile}. Settlement does not guarantee reaching the destination.${fuelWarning} Read confirmed state/location. A race could stop a new journey.`;
+    const instruction = adaptStopSubwarpInstruction({
+        authorization: intent.authorization,
+        character,
+        fleet: intent.fleet,
+        game: intent.game,
+        regionTracker,
+        ...xp.accounts,
+    });
+    return buildPlannerPlan({
         kind: 'fleet.settle-arrival',
-        preconditions: [],
+        preconditions: [
+            {
+                kind: 'fleet-arrival',
+                address: intent.fleet,
+                intent,
+                character,
+                regionTracker,
+                describes: 'The owned journey must still have elapsed on chain; direct Profile authority must remain valid.',
+            },
+            {
+                kind: 'xp-runtime',
+                address: intent.game,
+                intent: xp.intent,
+                accounts: xp.accounts,
+                describes: 'The current Game runtime and required Career XP accounts must remain supported; XP balances may change.',
+            },
+        ],
         steps: [
             {
                 describes: description,
-                instruction: adaptFleetSettleArrivalInstruction({
-                    character,
-                    fleet: fleet.address,
-                    funder,
-                    game,
-                }),
-                signers: [funder],
+                instruction,
+                signers: [intent.authorization.authority],
             },
         ],
-        summary: `Settle arrival for fleet ${fleet.name}.`,
+        summary: `Settle elapsed subwarp for fleet ${fleet.name}.`,
     });
 }
 /** Plans an early Fleet subwarp stop without signing, simulation, or write RPC.
@@ -697,21 +710,36 @@ export async function planFleetSettleArrival(ctx, fleet, input) {
 export async function planFleetStopSubwarp(ctx, fleet, options) {
     validatePlanAuthorization(options.authorization);
     assertFleetOwner(fleet, options.authorization);
-    requireStopSubwarpState(fleet);
+    if (fleet.state.kind !== 'subwarp' && fleet.state.kind !== 'idle')
+        failFleetState(fleet, fleet.state.kind, 'stop subwarp', 'it must be subwarping or idle');
     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 xp = await resolveXpRuntime(ctx, {
+        game,
+        character,
+        profile: options.authorization.profile,
+    });
     const description = `Stop subwarp early for fleet ${fleet.name}; leave it idle if the trip already completed.`;
-    return createPlan({
+    return buildPlannerPlan({
         kind: 'fleet.stop-subwarp',
-        preconditions: [],
+        preconditions: [
+            {
+                kind: 'xp-runtime',
+                address: game,
+                intent: xp.intent,
+                accounts: xp.accounts,
+                describes: 'The configured Game and canonical Character XP accounts remain eligible for movement.',
+            },
+        ],
         steps: [
             {
                 describes: description,
                 instruction: adaptStopSubwarpInstruction({
+                    ...xp.accounts,
                     authorization: options.authorization,
                     character,
                     fleet: fleet.address,
@@ -753,12 +781,11 @@ export async function planFleetUndock(ctx, fleet, options) {
         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 characterAccount = requireFleetCharacter(characterCandidate, fleet, options.authorization.profile, game, characterAddress, 'undock');
     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);
+    const system = await validateFleetSystemRead(systemAccount, fleet, game, 'undock', 'Star System', docked.systemSeqId);
     validateStarbasePlayerRead(playerAccount, fleet, options.authorization.profile, characterAddress, docked.system.address, starbasePlayerAddress);
     const instruction = adaptDockedToIdleInstruction({
         authorization: options.authorization,
@@ -768,13 +795,13 @@ export async function planFleetUndock(ctx, fleet, options) {
         systemAndStarbasePlayerSystem: docked.system.address,
     });
     const description = `Undock fleet ${fleet.name} from the Starbase in Star System ${system.name}.`;
-    return createPlan({
+    return buildPlannerPlan({
         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}.`),
+            accountStatePrecondition(fleetAccount, `Fleet ${fleet.name} remains docked at Star System ${system.name}.`),
+            accountStatePrecondition(characterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game.`),
+            accountStatePrecondition(systemAccount, `Star System ${system.name} remains the docked System for Fleet ${fleet.name}.`),
+            accountStatePrecondition(playerAccount, `The Starbase Player remains registered for Fleet ${fleet.name} at Star System ${system.name}.`),
         ]),
         steps: [
             {
@@ -788,10 +815,12 @@ export async function planFleetUndock(ctx, fleet, options) {
 }
 /** Plans one explicit Fleet dock without signing, simulation, or write RPC.
  *
- * The planner accepts a loaded idle or refreshable movement Fleet snapshot,
+ * The planner accepts a loaded idle or refreshable warp Fleet snapshot,
  * resolves the only canonical Character, Star System at its action coordinate,
  * and Starbase Player internally, and returns one inspectable idle-to-docked
- * Plan.
+ * Plan. A subwarp snapshot is refused: the dock step refreshes the Fleet
+ * without its Character and cannot settle a subwarp journey, so settle the
+ * arrival or stop the subwarp first.
  *
  * @example
  * ```ts
@@ -814,34 +843,13 @@ export async function planFleetDock(ctx, fleet, options) {
     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 === actionLocation.x &&
-        system.data.coordinates.y === actionLocation.y);
-    if (matchingSystems.length === 0)
+    const characterAccount = requireFleetCharacter(characterCandidate, fleet, options.authorization.profile, game, characterAddress, 'dock');
+    const candidates = await discoverSystemsAt(ctx, game, actionLocation);
+    if (candidates.length === 0)
         failNoDockableStarbase(fleet, actionLocation);
-    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, actionLocation);
-            await validateDockSystemRead(systemAccount, fleet, game, systemAddress, validatedFleet.location);
-        }
-        fail(`Fleet ${fleet.name} action coordinate (${String(actionLocation.x)}, ${String(actionLocation.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);
+    const systemAccount = selectSystemAt(fleet, actionLocation, validatedFleet.location, candidates, await readContextRawAccounts(ctx, candidates));
+    const systemAddress = systemAccount.address;
+    const system = await validateFleetSystemRead(systemAccount, fleet, game, 'dock');
     if (system.starbase === undefined)
         failNoDockableStarbase(fleet, actionLocation);
     const starbasePlayerAddress = await deriveStarbasePlayerAddress(systemAddress, characterAddress);
@@ -850,24 +858,71 @@ export async function planFleetDock(ctx, fleet, options) {
     ]);
     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 [tracker, ownership] = await Promise.all([
+        deriveFactionRelationTrackerAddress(game),
+        deriveFactionOwnershipAddress(game, 'starbase', systemAddress),
+    ]);
+    const policy = {
+        kind: 'fleet-docking-policy',
+        address: tracker,
+        game,
+        system: systemAddress,
+        ownership,
+        describes: 'Docking retains qualified default faction gating and legacy System control.',
+    };
+    const [trackerAccount, ownershipAccount] = await readContextRawAccounts(ctx, [
+        tracker,
+        ownership,
+    ]);
+    await validateFleetDockingPolicy(trackerAccount, ownershipAccount, policy);
     const instruction = adaptIdleToDockedInstruction({
+        factionRelationTracker: tracker,
+        factionOwnership: ownership,
         authorization: options.authorization,
         fleet: fleet.address,
         game,
         systemAndStarbasePlayerStarbasePlayer: starbasePlayerAddress,
         systemAndStarbasePlayerSystem: systemAddress,
     });
+    const fundingIntent = {
+        address: fleet.address,
+        game,
+        profile: options.authorization.profile,
+        authority: options.authorization.authority,
+        certificate: instruction.accounts[2].address,
+        character: characterAddress,
+        system: systemAddress,
+        starbasePlayer: starbasePlayerAddress,
+        keyIndex: options.authorization.keyIndex,
+    };
+    const amounts = await resolveDockFunding(ctx, fundingIntent, [
+        fleetAccount,
+        playerAccount,
+        systemAccount,
+    ]);
+    const funding = {
+        kind: 'fleet-dock-funding',
+        ...fundingIntent,
+        ...amounts,
+        describes: amounts.status === 'available'
+            ? `Maximum gross Profile storage debit: ${String(amounts.maximumProfileDebit)} lamports. No refunds or surplus are credited; transaction fees are separate. Rechecked before signing, not enforced atomically on chain.`
+            : `Docking storage debit bounds are unavailable (${amounts.reason}); this does not imply zero Profile debit. Inspect simulation and fund the Profile explicitly if needed; transaction fees are separate.`,
+    };
     const description = `Dock fleet ${fleet.name} at the Starbase in Star System ${system.name}.`;
-    return createPlan({
+    return buildPlannerPlan({
         kind: 'fleet.dock',
-        preconditions: await Promise.all([
-            precondition(fleetAccount, fleet.state.kind === 'idle'
-                ? `Fleet ${fleet.name} remains idle at Starbase System ${system.name} coordinate (${String(actionLocation.x)}, ${String(actionLocation.y)}).`
-                : `Fleet ${fleet.name} remains ${fleet.state.kind} at Starbase System ${system.name} action coordinate (${String(actionLocation.x)}, ${String(actionLocation.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(actionLocation.x)}, ${String(actionLocation.y)}).`),
-            precondition(playerAccount, `The Starbase Player remains registered for Fleet ${fleet.name} at Starbase ${system.name}.`),
-        ]),
+        preconditions: [
+            policy,
+            ...(await Promise.all([
+                accountStatePrecondition(fleetAccount, fleet.state.kind === 'idle'
+                    ? `Fleet ${fleet.name} remains idle at Starbase System ${system.name} coordinate (${String(actionLocation.x)}, ${String(actionLocation.y)}).`
+                    : `Fleet ${fleet.name} remains ${fleet.state.kind} at Starbase System ${system.name} action coordinate (${String(actionLocation.x)}, ${String(actionLocation.y)}).`),
+                accountStatePrecondition(characterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game.`),
+                accountStatePrecondition(systemAccount, `Star System ${system.name} remains the Starbase System at Fleet ${fleet.name} coordinate (${String(actionLocation.x)}, ${String(actionLocation.y)}).`),
+                accountStatePrecondition(playerAccount, `The Starbase Player remains registered for Fleet ${fleet.name} at Starbase ${system.name}.`),
+            ])),
+            funding,
+        ],
         steps: [
             {
                 describes: description,
@@ -879,4 +934,9 @@ export async function planFleetDock(ctx, fleet, options) {
     });
 }
 export { planDepositShipsToGame, } from './ship-import.js';
+export { planCreateFleet, } from './create-fleet.js';
+export { planAddShipToFleet, } from './add-ship.js';
+export { planFleetStartRespawn, planFleetCompleteRespawn, } from './respawn.js';
+export { planLoadFleetCrew, planUnloadFleetCrew, } from './crew-transfer.js';
+export { getFleetDockDebitBounds, } from './dock-bounds.js';
 //# sourceMappingURL=index.js.map