@aephia/atlas-kit 0.6.0-next.1 → 0.6.0-next.100

package/dist/fleets/actions/index.js

@@ -1,16 +1,24 @@
-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 { getAddressEncoder, 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 { FixedPoint, getFleetDecoder, getRegionTrackerDecoder, getStarSystemDecoder, } from '../../internal/c4/runtime-bindings.js';
 import { characterAccountDefinition, findCharacterPda, } from '../../internal/c4/identity.js';
 import { deriveStarbasePlayerAddress, starbasePlayerAccountDefinition, } from '../../internal/c4/starbase.js';
 import { buildStarSystemDiscoveryFilters, deriveStarSystemAddress, starSystemAccountDefinition, } from '../../internal/c4/world.js';
 import { requireGameAddress } from '../../internal/game-context.js';
-import { adaptDockedToIdleInstruction, adaptFleetSettleArrivalInstruction, adaptIdleToDockedInstruction, adaptStartSubwarpInstruction, adaptStopSubwarpInstruction, adaptWarpLaneInstruction, adaptWarpToCoordinateInstruction, validatePlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
+import { adaptDockedToIdleInstruction, adaptIdleToDockedInstruction, adaptStartSubwarpInstruction, adaptStopSubwarpInstruction, adaptWarpLaneInstruction, adaptWarpToCoordinateInstruction, validatePlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
 import { createPlan, } from '../../planning/index.js';
+import { resolveFleetArrival } from '../../internal/planning/fleet-arrival.js';
 const FLEET_STATE_IDLE = 'fleet.state.idle';
 const FLEET_STATE_MOVEMENT_STARTED = 'fleet.state.movement-started';
 function movementStartSemantics(fleet) {
@@ -32,36 +40,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 };
+            }
+        }
     }
+    throw new InvalidActionInputError('options', value, 'direct Profile authorization', remedy);
 }
 const STOP_SUBWARP_REMEDIES = {
     claimStakeTransfer: 'Finish the Claim Stake transfer',
@@ -228,7 +235,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,59 +255,16 @@ 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) {
     const region = tracker.regions.unsizedList.find((candidate) => regionContainsCoordinate(candidate, coordinate));
     if (region === undefined) {
@@ -311,8 +275,8 @@ function resolveRegionId(tracker, coordinate, displayCoordinate, label, fleet, t
 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) {
@@ -362,7 +326,13 @@ async function planCoordinateMovement(mode, ctx, fleet, options) {
     validateDestination(fleet, actionLocation, options.destination);
     const game = requireGameAddress(ctx);
     const resolved = await resolveCoordinateMovement(ctx, fleet, options.authorization, actionLocation, options.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
@@ -386,10 +356,27 @@ async function planCoordinateMovement(mode, ctx, fleet, options) {
     const verb = mode === 'subwarp' ? 'Subwarp' : 'Warp';
     const description = `${verb} fleet ${fleet.name} to coordinate (${String(options.destination.x)}, ${String(options.destination.y)}).`;
     const accounts = [
+        {
+            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 precondition(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.`),
+        {
+            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 precondition(resolved.regionTrackerAccount, `The configured RegionTracker continues to map Fleet ${fleet.name}'s current and destination coordinates.`),
         ...(resolved.crewBindingAccount === undefined
             ? []
@@ -411,31 +398,6 @@ 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);
@@ -446,7 +408,7 @@ async function validateLaneSystemRead(account, fleet, game, label) {
 }
 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);
 }
@@ -469,7 +431,7 @@ async function resolveWarpLane(ctx, fleet, actionLocation, options) {
     }
     const [character, currencyCache, factionRelationTracker, regionTracker] = await Promise.all([
         findCharacterPda(options.authorization.profile, game),
-        deriveCurrencyCacheAddress(game),
+        deriveCurrencyCache(game).then(([address]) => address),
         deriveFactionRelationTrackerAddress(game),
         deriveRegionTrackerAddress(game),
     ]);
@@ -491,7 +453,7 @@ 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 validatedFleet = await validateIdleFleetRead(fleetAccount, fleet, game, actionLocation, 'warp lane');
     const exactSourceCandidates = sourceCandidates.flatMap((candidate, index) => {
         const account = reads[sourceOffset + index];
         return account !== undefined &&
@@ -517,7 +479,7 @@ async function resolveWarpLane(ctx, fleet, actionLocation, options) {
     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);
+    await validateCurrencyCache(currencyCacheAccount, game, 'warp lane');
     validateFactionRelationTrackerRead(factionRelationTrackerAccount, fleet, game, factionRelationTracker);
     validateRegionTrackerRead(regionTrackerAccount, fleet, game, regionTracker);
     if (sourceSystem === options.destinationSystem) {
@@ -547,7 +509,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 +537,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({
         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([
+                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}.`),
+                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.`),
+                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.'),
+            ])),
+        ],
         steps: [
             {
                 describes: description,
                 instruction: adaptWarpLaneInstruction({
+                    ...xp.accounts,
                     authorization: options.authorization,
                     character: resolved.character,
                     currencyCache: resolved.currencyCache,
@@ -634,47 +634,73 @@ export function planFleetSubwarp(ctx, fleet, options) {
 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.`;
+    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 createPlan({
         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.
@@ -704,14 +730,28 @@ export async function planFleetStopSubwarp(ctx, fleet, options) {
     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({
         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,
@@ -850,24 +890,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,
+        keyIndex: options.authorization.keyIndex,
+        character: characterAddress,
+        system: systemAddress,
+        starbasePlayer: starbasePlayerAddress,
+    };
+    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({
         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([
+                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}.`),
+            ])),
+            funding,
+        ],
         steps: [
             {
                 describes: description,
@@ -878,4 +965,10 @@ export async function planFleetDock(ctx, fleet, options) {
         summary: `Dock fleet ${fleet.name} at Starbase ${system.name}.`,
     });
 }
+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