@aephia/atlas-kit 0.6.0-next.98 → 0.6.0

package/dist/fleets/actions/index.js

@@ -1,24 +1,32 @@
 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 { factionValue } from '../../internal/c4/faction.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 { hashRegionAccess, hashRegionPath, } from '../../internal/planning/region-access.js';
 import { resolveXpRuntime } from '../../internal/planning/xp-runtime.js';
-import { getAddressEncoder, isAddress } from '@solana/kit';
+import { isAddress } from '@solana/kit';
 import { InvalidActionInputError, SageSdkError } from '../../client/errors.js';
 import { readContextRawAccounts } from '../../client/reconciliation.js';
+import { readMovementStorageAction } from '../../internal/planning/movement-storage-actions.js';
+import { planStorageFunding } from '../../internal/planning/storage-actions.js';
+import { RENT_ADDRESS } from '../../internal/planning/rent.js';
 import { deriveFleetAddress, fleetAccountDefinition, } from '../../internal/c4/fleet.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, adaptIdleToDockedInstruction, adaptStartSubwarpInstruction, adaptStopSubwarpInstruction, adaptWarpLaneInstruction, adaptWarpToCoordinateInstruction, validatePlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
-import { createPlan, } from '../../planning/index.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 { isSubPrecisionRoute } from '../../internal/fleet-route.js';
+import { accountStatePrecondition } from '../../internal/planning/account-state.js';
+import { characterAccessPrecondition } from '../../internal/planning/character-access.js';
 const FLEET_STATE_IDLE = 'fleet.state.idle';
 const FLEET_STATE_MOVEMENT_STARTED = 'fleet.state.movement-started';
 function movementStartSemantics(fleet) {
@@ -70,20 +78,6 @@ function validateSettleArrivalOptions(value) {
     }
     throw new InvalidActionInputError('options', value, 'direct Profile authorization', remedy);
 }
-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);
@@ -95,30 +89,29 @@ 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);
 }
+/** The program moves and undocks a Fleet only with at least its required
+ * crew aboard; undocking also needs a non-empty ship map. The program counts
+ * map entries, not quantities, and leaves zero-quantity entries behind when
+ * ships are removed, so such a Fleet still undocks. */
+function requireNormalizedCrew(data, fleet, action, requireShips = false) {
+    if (data.crewCount < data.stats.misc.requiredCrew)
+        fail(`Fleet ${fleet.name} has ${String(data.crewCount)} crew aboard but needs at least ${String(data.stats.misc.requiredCrew)} to ${action}. Load crew while docked (planLoadFleetCrew), refresh the Fleet, and retry.`, fleet.address);
+    if (requireShips && data.fleetShips.length === 0)
+        fail(`Fleet ${fleet.name} has no ships and cannot ${action}. Add ships while docked, refresh the Fleet, and retry.`, fleet.address);
+}
 function validateFleetRead(account, fleet, game, system, systemSequenceId) {
     const data = fleetAccountDefinition.decode(account);
     if (account.address !== fleet.address ||
@@ -129,22 +122,17 @@ function validateFleetRead(account, fleet, game, system, systemSequenceId) {
         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);
     }
+    requireNormalizedCrew(data, fleet, 'undock', true);
     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;
 }
@@ -158,36 +146,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.`);
@@ -196,25 +157,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);
@@ -235,7 +244,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;
@@ -244,10 +253,12 @@ async function validateIdleFleetRead(account, fleet, game, actionLocation, planN
         exactLocation = exact.state.fields[0].journey.to;
     }
     return {
+        data,
         location: {
             x: exactLocation[0].raw,
             y: exactLocation[1].raw,
         },
+        npc: data.npcFactionId !== 0,
     };
 }
 function validateRegionTrackerRead(account, fleet, game, canonicalAddress, action = 'move') {
@@ -255,7 +266,7 @@ 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);
@@ -265,21 +276,18 @@ function validateCrewBindingRead(account, fleet, canonicalAddress) {
     }
     return data;
 }
-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;
+/** The Region containing a coordinate, or `null` for deep space. */
+function resolveRegionId(tracker, coordinate) {
+    return (tracker.regions.unsizedList.find((candidate) => regionContainsCoordinate(candidate, coordinate))?.id ?? null);
 }
 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) {
+async function resolveCoordinateMovement(mode, ctx, fleet, authorization, actionLocation, destination) {
     const game = requireGameAddress(ctx);
     const [character, regionTracker, crewBinding] = await Promise.all([
         findCharacterPda(authorization.profile, game),
@@ -293,39 +301,70 @@ 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);
+    requireNormalizedCrew(validatedFleet.data, fleet, mode);
+    if (destination.exact.x === validatedFleet.location.x &&
+        destination.exact.y === validatedFleet.location.y) {
+        failSameCoordinate(fleet, `${destination.field} ${destination.description}`);
+    }
+    if (mode === 'subwarp' &&
+        isSubPrecisionRoute(validatedFleet.location, destination.exact)) {
+        fail(`Fleet ${fleet.name} ${destination.field} ${destination.description} is closer to its action coordinate than the program can measure, so this subwarp would be refused. Choose a destination farther away and retry.`, fleet.address);
     }
-    validateCharacterForCoordinateMovement(characterAccount, fleet, authorization.profile, game, character);
     const tracker = validateRegionTrackerRead(regionTrackerAccount, fleet, game, regionTracker);
     if (crewCandidate !== undefined) {
         validateCrewBindingRead(crewCandidate, fleet, crewBinding);
     }
+    const destinationRegionId = resolveRegionId(tracker, destination.exact);
+    // A player Fleet may cross deep space, but stopping there needs High Risk
+    // zone access.
+    if (destinationRegionId === null &&
+        !validatedFleet.npc &&
+        characterAccountDefinition.decode(characterAccount).modifiers.values
+            .securityZoneAccess !== 'high') {
+        fail(`Fleet ${fleet.name} ${destination.field} ${destination.field === 'destinationRaw' ? `(${String(destination.exact.x)}, ${String(destination.exact.y)}) raw I8F56` : destination.description} is in deep space, outside every Region, and its Character lacks the High Risk zone access needed to stop there. Research High Risk zone access or choose a destination inside a Region, then retry.`, character);
+    }
     return {
         character,
         characterAccount,
         ...(crewCandidate === undefined
             ? {}
             : { crewBinding, crewBindingAccount: crewCandidate }),
-        destinationRegionId: resolveRegionId(tracker, exactDestination, destination, 'destination', fleet, regionTracker),
+        destinationRegionId,
         fleetAccount,
         regionTracker,
         regionTrackerAccount,
-        startRegionId: resolveRegionId(tracker, validatedFleet.location, actionLocation, 'current', fleet, regionTracker),
+        from: validatedFleet.location,
+        startRegionId: resolveRegionId(tracker, validatedFleet.location),
     };
 }
+/** Starting a journey changes the Fleet to its movement state; the program
+ * funds any growth from the Profile vault with the signing key. */
+async function planMovementStorage(ctx, instruction, fleetAccount, profile) {
+    const [profileAccount, rentAccount] = await readContextRawAccounts(ctx, [
+        profile,
+        RENT_ADDRESS,
+    ]);
+    const accounts = new Map([
+        [fleetAccount.address, fleetAccount],
+        [profile, profileAccount],
+        [RENT_ADDRESS, rentAccount],
+    ]);
+    return planStorageFunding({
+        action: readMovementStorageAction(instruction, accounts),
+        accounts,
+        label: 'movement start',
+    });
+}
 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(mode, ctx, fleet, options.authorization, actionLocation, destination);
     const xp = await resolveXpRuntime(ctx, {
         game,
         character: resolved.character,
@@ -347,14 +386,15 @@ 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 storage = await planMovementStorage(ctx, instruction, resolved.fleetAccount, options.authorization.profile);
+    const description = `${verb} fleet ${fleet.name} to coordinate ${destination.description}. ${storage.disclosure}`;
     const accounts = [
         {
             kind: 'xp-runtime',
@@ -363,28 +403,30 @@ async function planCoordinateMovement(mode, ctx, fleet, options) {
             accounts: xp.accounts,
             describes: 'The configured Game and canonical Character XP accounts remain eligible for movement.',
         },
-        await precondition(resolved.fleetAccount, fleet.state.kind === 'idle'
+        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 characterAccessPrecondition(resolved.characterAccount, { game, profile: options.authorization.profile }, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game with the research modifiers that set its movement and Region access; its ATLAS, XP and asset counts may change.`),
         {
-            kind: 'movement-character',
-            address: resolved.character,
+            kind: 'region-path',
+            address: resolved.regionTracker,
             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.',
+            fleet: fleet.address,
+            fromX: resolved.from.x,
+            fromY: resolved.from.y,
+            toX: destination.exact.x,
+            toY: destination.exact.y,
+            pathHash: await hashRegionPath(resolved.regionTrackerAccount, game, resolved.from, destination.exact),
+            describes: `The Regions Fleet ${fleet.name}'s straight path to ${destination.description} can cross keep their borders, owner, safety status and risk zone, and no Region is added or removed; other Regions may change.`,
         },
-        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.`),
+                await accountStatePrecondition(resolved.crewBindingAccount, `Fleet ${fleet.name}'s optional FleetCrewBinding remains assigned to the Fleet and owner Profile.`),
             ]),
+        storage.guard,
     ];
-    return createPlan({
+    return buildPlannerPlan({
         kind: mode === 'subwarp' ? 'fleet.subwarp' : 'fleet.warp-to-coordinate',
         preconditions: accounts,
         steps: [
@@ -398,20 +440,35 @@ async function planCoordinateMovement(mode, ctx, fleet, options) {
         summary: description,
     });
 }
-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) {
@@ -420,12 +477,7 @@ 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);
     }
@@ -440,7 +492,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,
@@ -454,31 +506,16 @@ async function resolveWarpLane(ctx, fleet, actionLocation, options) {
     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, 'warp lane');
-    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);
+    requireNormalizedCrew(validatedFleet.data, fleet, 'use a 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');
+    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);
@@ -511,7 +548,9 @@ async function resolveWarpLane(ctx, fleet, actionLocation, options) {
  * proves connectivity from that System's decoded connections, and resolves all
  * 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.
+ * checked before signing. The Regions containing the destination keep their
+ * owner, safety status and risk zone, which decide destination access; other
+ * Regions may change. Refresh and recreate older Plans to use these guards.
  *
  * Connectivity does not guarantee eligibility. The program remains authoritative
  * for faction-relationship and destination-risk checks and any ATLAS toll.
@@ -542,8 +581,21 @@ export async function planFleetWarpLane(ctx, fleet, options) {
         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({
+    const instruction = adaptWarpLaneInstruction({
+        ...xp.accounts,
+        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,
+    });
+    const storage = await planMovementStorage(ctx, instruction, resolved.fleetAccount, options.authorization.profile);
+    const description = `Warp fleet ${fleet.name} from Star System ${resolved.source.name} to Star System ${resolved.destination.name} via warp lane. ${storage.disclosure}`;
+    return buildPlannerPlan({
         kind: 'fleet.warp-lane',
         preconditions: [
             {
@@ -554,47 +606,34 @@ export async function planFleetWarpLane(ctx, fleet, options) {
                 describes: 'The configured Game and canonical Character XP accounts remain eligible for movement.',
             },
             ...(await Promise.all([
-                precondition(resolved.fleetAccount, fleet.state.kind === 'idle'
+                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.',
-                })),
-                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.`),
+                characterAccessPrecondition(resolved.characterAccount, { game, profile: options.authorization.profile }, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game with the research modifiers that set its movement and Region access; its ATLAS, XP and asset counts may change.`),
+                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.',
                 }),
-                precondition(resolved.factionRelationTrackerAccount, 'The canonical FactionRelationTracker remains assigned to the configured Game.'),
-                precondition(resolved.regionTrackerAccount, 'The canonical RegionTracker remains assigned to the configured Game.'),
+                accountStatePrecondition(resolved.factionRelationTrackerAccount, 'The canonical FactionRelationTracker remains assigned to the configured Game.'),
+                hashRegionAccess(resolved.regionTrackerAccount, resolved.destinationAccount, game).then((accessHash) => ({
+                    kind: 'region-access',
+                    address: resolved.regionTracker,
+                    game,
+                    system: options.destinationSystem,
+                    accessHash,
+                    describes: `The Regions containing destination Star System ${resolved.destination.name} keep their owner, safety status and risk zone; other Regions may change.`,
+                })),
             ])),
+            storage.guard,
         ],
         steps: [
             {
                 describes: description,
-                instruction: adaptWarpLaneInstruction({
-                    ...xp.accounts,
-                    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,
-                }),
+                instruction,
                 semantics: movementStartSemantics(fleet.address),
                 signers: [options.authorization.authority],
             },
@@ -602,7 +641,13 @@ 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.
+ *
+ * A coordinate outside every Region is deep space and carries no Region hint.
+ * A player Fleet may cross deep space, but stopping there needs the Character's
+ * High Risk zone access; NPC Fleets need none. The Plan guards only the
+ * Regions whose bounding boxes overlap the straight path's, plus the Region
+ * count, so a Starbase capture or upgrade elsewhere leaves it valid.
  *
  * @example
  * ```ts
@@ -611,14 +656,20 @@ 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.
+ *
+ * A coordinate outside every Region is deep space and carries no Region hint.
+ * A player Fleet may cross deep space, but stopping there needs the Character's
+ * High Risk zone access; NPC Fleets need none. The Plan guards only the
+ * Regions whose bounding boxes overlap the straight path's, plus the Region
+ * count, so a Starbase capture or upgrade elsewhere leaves it valid.
  *
  * @example
  * ```ts
@@ -627,7 +678,7 @@ 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) },
  * });
  * ```
  */
@@ -674,7 +725,7 @@ export async function planFleetSettleArrival(ctx, fleet, input) {
         regionTracker,
         ...xp.accounts,
     });
-    return createPlan({
+    return buildPlannerPlan({
         kind: 'fleet.settle-arrival',
         preconditions: [
             {
@@ -723,7 +774,8 @@ 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);
@@ -736,7 +788,7 @@ export async function planFleetStopSubwarp(ctx, fleet, options) {
         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: [
             {
@@ -793,12 +845,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,
@@ -808,13 +859,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}.`),
+            characterAccessPrecondition(characterAccount, { game, profile: options.authorization.profile }, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game with its research modifiers; its ATLAS, XP and asset counts may change.`),
+            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: [
             {
@@ -828,10 +879,18 @@ 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.
+ *
+ * Docking is admitted when the Starbase Player belongs to the Starbase's
+ * controlling faction, whatever the territory and economics settings. A
+ * foreign Starbase Player is refused while territory access is off; foreign
+ * docking under territory access and dynamic-faction Starbases are refused as
+ * unsupported.
  *
  * @example
  * ```ts
@@ -854,34 +913,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);
@@ -889,7 +927,7 @@ export async function planFleetDock(ctx, fleet, options) {
         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 playerData = validateStarbasePlayerRead(playerAccount, fleet, options.authorization.profile, characterAddress, systemAddress, starbasePlayerAddress, 'dock');
     const [tracker, ownership] = await Promise.all([
         deriveFactionRelationTrackerAddress(game),
         deriveFactionOwnershipAddress(game, 'starbase', systemAddress),
@@ -900,13 +938,19 @@ export async function planFleetDock(ctx, fleet, options) {
         game,
         system: systemAddress,
         ownership,
-        describes: 'Docking retains qualified default faction gating and legacy System control.',
+        starbasePlayer: starbasePlayerAddress,
+        describes: 'Docking keeps the same Starbase controller, Starbase Player faction and faction admission.',
     };
     const [trackerAccount, ownershipAccount] = await readContextRawAccounts(ctx, [
         tracker,
         ownership,
     ]);
-    await validateFleetDockingPolicy(trackerAccount, ownershipAccount, policy);
+    await validateFleetDockingPolicy({
+        tracker: trackerAccount,
+        ownership: ownershipAccount,
+        system: systemAccount,
+        starbasePlayer: playerAccount,
+    }, policy);
     const instruction = adaptIdleToDockedInstruction({
         factionRelationTracker: tracker,
         factionOwnership: ownership,
@@ -922,10 +966,10 @@ export async function planFleetDock(ctx, fleet, options) {
         profile: options.authorization.profile,
         authority: options.authorization.authority,
         certificate: instruction.accounts[2].address,
-        keyIndex: options.authorization.keyIndex,
         character: characterAddress,
         system: systemAddress,
         starbasePlayer: starbasePlayerAddress,
+        keyIndex: options.authorization.keyIndex,
     };
     const amounts = await resolveDockFunding(ctx, fundingIntent, [
         fleetAccount,
@@ -941,17 +985,17 @@ export async function planFleetDock(ctx, fleet, options) {
             : `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: [
             policy,
             ...(await Promise.all([
-                precondition(fleetAccount, fleet.state.kind === 'idle'
+                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)}).`),
-                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}.`),
+                characterAccessPrecondition(characterAccount, { game, profile: options.authorization.profile }, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game with its research modifiers; its ATLAS, XP and asset counts may change.`),
+                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,
         ],
@@ -968,7 +1012,10 @@ 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 { planFleetDisband } from './disband.js';
+export { planSyncFleetWithGame } from './sync.js';
 export { planFleetStartRespawn, planFleetCompleteRespawn, } from './respawn.js';
 export { planLoadFleetCrew, planUnloadFleetCrew, } from './crew-transfer.js';
+export { estimateFleetDeploymentStorage, } from './deployment-storage.js';
 export { getFleetDockDebitBounds, } from './dock-bounds.js';
 //# sourceMappingURL=index.js.map