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

package/dist/internal/planning/fleet-creation.js

@@ -0,0 +1,108 @@
+import { InvalidActionInputError, SageSdkError } from '../../client/errors.js';
+import { deriveFleetCreationAddress, emptyDockedFleetSize, } from '../c4/fleet-creation.js';
+import { profileAccountDefinition, characterAccountDefinition, findCharacterPda, } from '../c4/identity.js';
+import { profileFactionAccountDefinition, deriveProfileFactionAddress, } from '../c4/profile-faction.js';
+import { starbasePlayerAccountDefinition, deriveStarbasePlayerAddress, } from '../c4/starbase.js';
+import { starSystemAccountDefinition, deriveStarSystemAddress, } from '../c4/world.js';
+import { PROFILE_SCOPE, SAGE_SCOPE } from '../c4/profile-permissions.js';
+import { CLOCK_ADDRESS, readClock } from './faction-enrollment.js';
+import { RENT_ADDRESS, readRent } from './rent.js';
+export function validateFleetCreationLabel(label) {
+    if (typeof label !== 'string' ||
+        label.trim().length === 0 ||
+        label.includes('\0') ||
+        new TextDecoder('utf-8', { ignoreBOM: true }).decode(new TextEncoder().encode(label)) !== label ||
+        new TextEncoder().encode(label).length > 64)
+        throw new InvalidActionInputError('options.label', label, 'a nonblank, valid UTF-8 Fleet label of at most 64 bytes without NUL', 'Choose a valid Fleet label. Accepted whitespace is preserved in the canonical Fleet address.');
+}
+export async function resolveFleetCreation(input) {
+    const intent = { ...input };
+    validateFleetCreationLabel(intent.label);
+    const [character, profileFaction, fleet] = await Promise.all([
+        findCharacterPda(intent.profile, intent.game),
+        deriveProfileFactionAddress(intent.profile),
+        deriveFleetCreationAddress(intent.game, intent.profile, intent.label),
+    ]);
+    return {
+        game: intent.game,
+        profile: intent.profile,
+        authority: intent.authority,
+        system: intent.system,
+        character,
+        profileFaction,
+        fleet,
+        starbasePlayer: await deriveStarbasePlayerAddress(intent.system, character),
+        rent: RENT_ADDRESS,
+        clock: CLOCK_ADDRESS,
+    };
+}
+function fail(address, message) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', message, { address });
+}
+export async function validateFleetCreation(input, resolved, accounts, maximumProfileDebit) {
+    const intent = { ...input };
+    const required = (address, name) => {
+        const raw = accounts.get(address);
+        if (!raw)
+            fail(address, `${name} ${address} is missing. Create or select the required account, then replan Fleet creation.`);
+        if (raw.address !== address || raw.executable)
+            fail(address, `${name} ${address} has a contradictory address or is executable. Refresh valid account state before creating a Fleet.`);
+        return raw;
+    };
+    const profileRaw = required(resolved.profile, 'Profile');
+    const profile = profileAccountDefinition.decode(profileRaw);
+    const character = characterAccountDefinition.decode(required(resolved.character, 'Character'));
+    const faction = profileFactionAccountDefinition.decode(required(resolved.profileFaction, 'ProfileFaction'));
+    const system = starSystemAccountDefinition.decode(required(resolved.system, 'Star System'));
+    const player = starbasePlayerAccountDefinition.decode(required(resolved.starbasePlayer, 'StarbasePlayer'));
+    if (character.game !== intent.game ||
+        character.playerProfile !== intent.profile)
+        fail(resolved.character, 'The Character belongs to a different Game or Profile. Refresh the canonical Character and replan Fleet creation.');
+    if (faction.profile !== intent.profile)
+        fail(resolved.profileFaction, 'The faction membership belongs to a different Profile. Refresh the canonical membership before creating a Fleet.');
+    if (system.game !== intent.game ||
+        (await deriveStarSystemAddress(system.game, system.systemId)) !==
+            intent.system ||
+        !system.starbase)
+        fail(resolved.system, 'The selected System is not canonical for this Game or has no Starbase. Choose a valid Starbase System and replan.');
+    if (player.playerProfile !== intent.profile ||
+        player.character !== resolved.character ||
+        player.system !== intent.system ||
+        player.faction !== faction.faction)
+        fail(resolved.starbasePlayer, 'The StarbasePlayer has a different Profile, Character, System or faction relationship. Refresh the canonical StarbasePlayer and replan.');
+    if (faction.faction === 'unaligned' ||
+        system.starbase.owner !== faction.faction)
+        fail(resolved.system, 'This planner supports an existing own-faction StarbasePlayer only. Select an own-faction Starbase; other diplomacy or access routes require separate supported planning.');
+    if (character.counts.fleets >= character.modifiers.values.fleetConcurrency)
+        fail(resolved.character, 'The Character has no available Fleet slots in its current stored capacity. Free a Fleet slot or refresh changed Character modifiers, then replan.');
+    const target = accounts.get(resolved.fleet);
+    if (target &&
+        (target.address !== resolved.fleet ||
+            target.executable ||
+            target.owner !== '11111111111111111111111111111111' ||
+            target.data.length !== 0))
+        fail(resolved.fleet, 'The canonical Fleet target already contains state or has a conflicting owner. Reuse the existing Fleet or choose a different label and replan.');
+    const rent = readRent(required(resolved.rent, 'Rent sysvar'));
+    const now = readClock(required(resolved.clock, 'Clock sysvar'));
+    const fleetRent = rent(emptyDockedFleetSize());
+    const balance = target?.lamports ?? 0n;
+    const profileDebit = balance < fleetRent ? fleetRent - balance : 0n;
+    if (maximumProfileDebit !== undefined && profileDebit > maximumProfileDebit)
+        fail(resolved.profile, 'Fleet creation now requires a larger Profile debit than this Plan approved. Replan and inspect the updated rent shortfall before signing.');
+    const profileReserve = rent(profileRaw.data.length);
+    if (profileRaw.lamports < profileReserve + profileDebit)
+        fail(resolved.profile, 'The Profile lacks the Fleet rent shortfall while preserving its own rent reserve. Fund the Profile or Fleet target explicitly, then replan.');
+    const key = profile.keys[intent.keyIndex];
+    if (!key || key.address !== intent.authority)
+        fail(resolved.profile, 'The selected direct Profile key is absent or belongs to another authority. Select the current key index for this authority and replan.');
+    if (key.expiresAtRaw >= 0n && key.expiresAtRaw < now)
+        fail(resolved.profile, 'The selected Profile key has expired. Renew it or select a current direct key and replan Fleet creation.');
+    const auth = key.scope === PROFILE_SCOPE && (key.permissionsRaw & 1n) !== 0n;
+    const manages = key.scope === SAGE_SCOPE && (key.permissionsRaw & (1n << 18n)) !== 0n;
+    if (!auth && !manages)
+        fail(resolved.profile, 'The selected key cannot manage Fleets. Use a direct Profile AUTH key or a SAGE manageFleet key and replan.');
+    if (profileDebit > 0n && !auth && (key.permissionsRaw & (1n << 63n)) === 0n)
+        fail(resolved.profile, 'The selected manageFleet key cannot fund the Fleet from the Profile vault. Explicitly prefund the target or choose an authorized vault-funding key, then replan; drainSolVault grants vault withdrawal authority.');
+    return { profileDebit, profileReserve, fleetRent };
+}
+//# sourceMappingURL=fleet-creation.js.map

package/dist/internal/planning/fleet-creation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-creation.js","sourceRoot":"","sources":["../../../src/internal/planning/fleet-creation.ts"],"names":[],"mappings":"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"}

package/dist/internal/planning/fleet-crew-guard.d.ts

@@ -0,0 +1,28 @@
+import { AccountRole, type Address } from '@solana/kit';
+import type { PlanPrecondition, PlanStep } from '../../planning/index.js';
+export interface FleetCrewGuard {
+    readonly kind: 'fleet-crew-transfer';
+    readonly direction: 'load' | 'unload';
+    readonly address: Address;
+    readonly game: Address;
+    readonly profile: Address;
+    readonly authority: Address;
+    readonly system: Address;
+    readonly starbasePlayer: Address;
+    readonly keyIndex: number;
+    readonly count: number;
+    readonly systemSequenceId: bigint;
+    readonly describes: string;
+    readonly dataHash?: never;
+}
+export declare function crewTransferInstruction(g: Omit<FleetCrewGuard, 'kind' | 'systemSequenceId' | 'describes'>): {
+    programAddress: Address<"C4SAgeKLgb3pTLWhVr6NRwWyYFuTR7ZeSXFrzoLwfMzF">;
+    accounts: {
+        address: Address;
+        role: AccountRole;
+    }[];
+    data: Uint8Array<ArrayBuffer>;
+};
+/** Ordinary crew transfers stand alone: later instructions cannot bypass fresh balance checks. */
+export declare function validateCrewTransferInstructions(steps: readonly PlanStep[], guards: readonly PlanPrecondition[]): void;
+//# sourceMappingURL=fleet-crew-guard.d.ts.map

package/dist/internal/planning/fleet-crew-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-crew-guard.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/fleet-crew-guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAQxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAC1E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;CAC3B;AACD,wBAAgB,uBAAuB,CACrC,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,kBAAkB,GAAG,WAAW,CAAC;;;;;;;EAyBnE;AACD,kGAAkG;AAClG,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAClC,IAAI,CAqCN"}

package/dist/internal/planning/fleet-crew-guard.js

@@ -0,0 +1,47 @@
+import { AccountRole } from '@solana/kit';
+import { SAGE_PROGRAM_ADDRESS, PLAYER_PROFILE_PROGRAM_ADDRESS, LOAD_FLEET_CREW_DISCRIMINATOR, UNLOAD_FLEET_CREW_DISCRIMINATOR, } from '../c4/runtime-bindings.js';
+import { InvalidActionInputError } from '../../client/errors.js';
+export function crewTransferInstruction(g) {
+    return {
+        programAddress: SAGE_PROGRAM_ADDRESS,
+        accounts: [
+            { address: g.authority, role: AccountRole.READONLY_SIGNER },
+            { address: g.profile, role: AccountRole.WRITABLE },
+            { address: SAGE_PROGRAM_ADDRESS, role: AccountRole.READONLY },
+            { address: PLAYER_PROFILE_PROGRAM_ADDRESS, role: AccountRole.READONLY },
+            { address: g.address, role: AccountRole.WRITABLE },
+            { address: g.game, role: AccountRole.READONLY },
+            { address: g.system, role: AccountRole.READONLY },
+            { address: g.starbasePlayer, role: AccountRole.WRITABLE },
+        ],
+        // Pinned ordinary crew payload: discriminator, u16 count, u16 key index.
+        data: Uint8Array.of(...(g.direction === 'load'
+            ? LOAD_FLEET_CREW_DISCRIMINATOR
+            : UNLOAD_FLEET_CREW_DISCRIMINATOR), g.count & 255, g.count >>> 8, g.keyIndex & 255, g.keyIndex >>> 8),
+    };
+}
+/** Ordinary crew transfers stand alone: later instructions cannot bypass fresh balance checks. */
+export function validateCrewTransferInstructions(steps, guards) {
+    const selected = guards.filter((g) => g.kind === 'fleet-crew-transfer');
+    const transfers = steps.filter(({ instruction: i }) => i.programAddress === SAGE_PROGRAM_ADDRESS &&
+        [LOAD_FLEET_CREW_DISCRIMINATOR, UNLOAD_FLEET_CREW_DISCRIMINATOR].some((d) => d.every((v, n) => i.data?.[n] === v)));
+    if (!selected.length && !transfers.length)
+        return;
+    const bad = () => {
+        throw new InvalidActionInputError('crewTransfer', undefined, 'one standalone ordinary crew transfer and its exact matching safeguard', 'Recreate the crew transfer Plan; execute each transfer separately and refresh crew balances before preparing another action.');
+    };
+    if (steps.length !== 1 || selected.length !== 1 || transfers.length !== 1)
+        bad();
+    const g = selected[0];
+    const step = transfers[0];
+    const expected = crewTransferInstruction(g), actual = step.instruction;
+    if (step.signers.length !== 1 ||
+        step.signers[0] !== g.authority ||
+        actual.accounts?.length !== expected.accounts.length ||
+        expected.accounts.some((a, n) => actual.accounts?.[n]?.address !== a.address ||
+            actual.accounts[n]?.role !== a.role) ||
+        actual.data?.length !== expected.data.length ||
+        expected.data.some((v, n) => actual.data?.[n] !== v))
+        bad();
+}
+//# sourceMappingURL=fleet-crew-guard.js.map

package/dist/internal/planning/fleet-crew-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-crew-guard.js","sourceRoot":"","sources":["../../../src/internal/planning/fleet-crew-guard.ts"],"names":[],"mappings":"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"}

package/dist/internal/planning/fleet-crew-transfer.d.ts

@@ -0,0 +1,7 @@
+import { type Commitment } from '@solana/kit';
+import type { SageContext } from '../../client/contracts.js';
+import type { FleetCrewGuard } from './fleet-crew-guard.js';
+export type FleetCrewIntent = Pick<FleetCrewGuard, 'address' | 'game' | 'profile' | 'authority' | 'keyIndex' | 'direction' | 'count'>;
+/** Fresh count predicates and canonical relationships, shared by planning and execution. */
+export declare function resolveFleetCrewTransfer(ctx: SageContext, intent: FleetCrewIntent, expected?: FleetCrewGuard, commitment?: Commitment): Promise<Pick<FleetCrewGuard, 'system' | 'starbasePlayer' | 'systemSequenceId'>>;
+//# sourceMappingURL=fleet-crew-transfer.d.ts.map

package/dist/internal/planning/fleet-crew-transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-crew-transfer.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/fleet-crew-transfer.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAGV,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAyBnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,IAAI,CAChC,cAAc,EACZ,SAAS,GACT,MAAM,GACN,SAAS,GACT,WAAW,GACX,UAAU,GACV,WAAW,GACX,OAAO,CACV,CAAC;AAOF,4FAA4F;AAC5F,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,eAAe,EACvB,QAAQ,CAAC,EAAE,cAAc,EACzB,UAAU,GAAE,UAAwB,GACnC,OAAO,CACR,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,gBAAgB,GAAG,kBAAkB,CAAC,CACvE,CAqKA"}

package/dist/internal/planning/fleet-crew-transfer.js

@@ -0,0 +1,131 @@
+import { isOffCurveAddress, getProgramDerivedAddress, getAddressEncoder, getU16Encoder, } from '@solana/kit';
+import { SAGE_PROGRAM_ADDRESS } from '../c4/runtime-bindings.js';
+import { SageSdkError } from '../../client/errors.js';
+import { readContextRawAccounts } from '../../client/reconciliation.js';
+import { requireGameAddress } from '../game-context.js';
+import { readFreshGameShipDefinitionSequence } from '../../registry/ships.js';
+import { fleetAccountDefinition, deriveFleetAddress } from '../c4/fleet.js';
+import { findCharacterPda, characterAccountDefinition, profileAccountDefinition, } from '../c4/identity.js';
+import { deriveStarbasePlayerAddress, starbasePlayerAccountDefinition, } from '../c4/starbase.js';
+import { deriveStarSystemAddress, starSystemAccountDefinition, } from '../c4/world.js';
+import { deriveFleetCrewBindingAddress, fleetCrewBindingAccountDefinition, } from '../c4/fleet-crew-binding.js';
+import { PROFILE_SCOPE } from '../c4/profile-permissions.js';
+import { CLOCK_ADDRESS, readClock } from './faction-enrollment.js';
+function fail(message) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', `${message} Refresh the owned Docked Fleet and Starbase crew, then recreate the crew transfer Plan.`);
+}
+/** Fresh count predicates and canonical relationships, shared by planning and execution. */
+export async function resolveFleetCrewTransfer(ctx, intent, expected, commitment = 'confirmed') {
+    if (requireGameAddress(ctx) !== intent.game ||
+        isOffCurveAddress(intent.authority))
+        fail('Crew transfer requires this deployment and an on-curve direct Profile authority.');
+    const [fleetRaw] = await readContextRawAccounts(ctx, [intent.address], {
+        commitment,
+    });
+    if (!fleetRaw || fleetRaw.address !== intent.address || fleetRaw.executable)
+        fail('The selected Fleet is missing, executable or has a contradictory address.');
+    const fleet = fleetAccountDefinition.decode(fleetRaw);
+    if (fleet.game !== intent.game ||
+        fleet.ownerProfile !== intent.profile ||
+        (await deriveFleetAddress(fleet)) !== intent.address ||
+        fleet.npcFactionId !== 0 ||
+        fleet.subProfile !== '11111111111111111111111111111111')
+        fail('Crew transfer supports only a canonical directly owned player Fleet without a subprofile.');
+    if (fleet.state.kind !== 'docked')
+        fail('Crew can be transferred only while the Fleet is Docked.');
+    if (fleet.rentedCrew !== 0)
+        fail('Rented crew transfers are not supported by this ordinary-crew route. Manage the rental through a supported game client first.');
+    const systemAddress = fleet.state.system;
+    const [characterAddress, bindingAddress] = await Promise.all([
+        findCharacterPda(intent.profile, intent.game),
+        deriveFleetCrewBindingAddress(intent.address),
+    ]);
+    const [playerAddress, [rosterAddress]] = await Promise.all([
+        deriveStarbasePlayerAddress(systemAddress, characterAddress),
+        getProgramDerivedAddress({
+            programAddress: SAGE_PROGRAM_ADDRESS,
+            seeds: [
+                new TextEncoder().encode('CrewRoster'),
+                getAddressEncoder().encode(characterAddress),
+                getU16Encoder().encode(0),
+            ],
+        }),
+    ]);
+    const addresses = [
+        intent.profile,
+        characterAddress,
+        systemAddress,
+        playerAddress,
+        bindingAddress,
+        rosterAddress,
+        CLOCK_ADDRESS,
+    ];
+    const [rows, shipSequence] = await Promise.all([
+        readContextRawAccounts(ctx, addresses, { commitment }),
+        readFreshGameShipDefinitionSequence(ctx, { commitment }),
+    ]);
+    if (rows.length !== addresses.length ||
+        rows.some((raw, i) => raw && (raw.address !== addresses[i] || raw.executable)))
+        fail('Crew transfer reads contain missing positions, contradictory addresses or executable accounts.');
+    const accounts = new Map(addresses.map((a, i) => [a, rows[i]]));
+    const required = (a) => accounts.get(a) ?? fail(`Required crew transfer account ${a} is missing.`);
+    const profile = profileAccountDefinition.decode(required(intent.profile));
+    const character = characterAccountDefinition.decode(required(characterAddress));
+    const system = starSystemAccountDefinition.decode(required(systemAddress));
+    const player = starbasePlayerAccountDefinition.decode(required(playerAddress));
+    if (character.game !== intent.game ||
+        character.playerProfile !== intent.profile ||
+        system.game !== intent.game ||
+        (await deriveStarSystemAddress(system.game, system.systemId)) !==
+            systemAddress ||
+        !system.starbase ||
+        player.playerProfile !== intent.profile ||
+        player.character !== characterAddress ||
+        player.system !== systemAddress ||
+        player.faction !== fleet.faction)
+        fail('The Character, System or StarbasePlayer does not match the canonical Game and Profile relationships.');
+    if (fleet.state.systemSeqId !== system.sequenceId ||
+        player.sequenceId !== system.sequenceId ||
+        (expected &&
+            (expected.system !== systemAddress ||
+                expected.starbasePlayer !== playerAddress ||
+                expected.systemSequenceId !== system.sequenceId)))
+        fail('The docking System or Starbase generation changed. Reconcile docking through the game before transferring crew.');
+    if (fleet.shipDefinitionsSeqId !== shipSequence)
+        fail('Fleet stats use stale ship definitions. Refresh the Fleet through a supported game client before checking crew capacity.');
+    if (accounts.get(rosterAddress))
+        fail('This Character has an individual-crew roster. This planner supports only ordinary crew with no page-0 roster; use the supported game client for roster-aware transfers.');
+    const binding = accounts.get(bindingAddress);
+    if (binding && !fleetCrewBindingAccountDefinition.decode(binding).isNeutral)
+        fail('The Fleet has a populated or unsupported crew binding. Use roster-aware transfer through a supported game client.');
+    const now = readClock(required(CLOCK_ADDRESS));
+    const key = profile.keys[intent.keyIndex];
+    if (!key ||
+        key.address !== intent.authority ||
+        (key.expiresAtRaw >= 0n && key.expiresAtRaw < now) ||
+        key.scope !== PROFILE_SCOPE ||
+        (key.permissionsRaw & 1n) === 0n)
+        fail('Crew transfer requires a current direct Profile AUTH key. Select the correct key index; restricted or delegated crew permissions are not qualified.');
+    const capacity = fleet.stats.misc.requiredCrew + fleet.stats.misc.passengerCapacity;
+    if (player.busyCrew > player.totalCrew)
+        fail('Starbase busy crew exceeds its total crew; reconcile the Starbase state before transferring.');
+    if (intent.direction === 'load') {
+        if (player.totalCrew - player.busyCrew < intent.count)
+            fail('The Starbase has too few available crew; finish their current assignments or reduce the requested count.');
+        if (fleet.crewCount + intent.count > capacity ||
+            fleet.crewCount + intent.count > 65535)
+            fail('The requested crew exceed the Fleet required-crew plus passenger capacity; reduce the count.');
+    }
+    else {
+        if (fleet.crewCount < intent.count)
+            fail('The Fleet has fewer crew aboard than requested; reduce the unload count.');
+        if (player.totalCrew + intent.count > 4294967295)
+            fail('The Starbase total crew would exceed its stored limit; select a smaller count.');
+    }
+    return {
+        system: systemAddress,
+        starbasePlayer: playerAddress,
+        systemSequenceId: system.sequenceId,
+    };
+}
+//# sourceMappingURL=fleet-crew-transfer.js.map

package/dist/internal/planning/fleet-crew-transfer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-crew-transfer.js","sourceRoot":"","sources":["../../../src/internal/planning/fleet-crew-transfer.ts"],"names":[],"mappings":"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"}

package/dist/internal/planning/fleet-dock-funding-guard.d.ts

@@ -0,0 +1,42 @@
+import { type Address } from '@solana/kit';
+import type { PlanPrecondition, PlanStep } from '../../planning/index.js';
+import type { RuntimeWire } from './runtime-guards.js';
+export declare const MAXIMUM_DOCK_GROWTH_BYTES = 40;
+declare const REASONS: readonly ["unsupported-account-layout", "unsupported-fleet-state", "noncanonical-account-encoding", "stale-definition-sequences", "stale-starbase-sequence", "pending-recovery", "active-stimulants", "funding-state-unavailable", "accounts-below-rent-reserve", "profile-below-storage-ceiling"];
+export type DockBoundsUnavailableReason = (typeof REASONS)[number];
+export type DockFundingAmounts = {
+    readonly status: 'unavailable';
+    readonly reason: DockBoundsUnavailableReason;
+} | {
+    readonly status: 'available';
+    readonly maximumProfileDebit: bigint;
+    readonly fleetDataLengthBytes: number;
+    readonly rentLamportsPerByteYear: bigint;
+    readonly rentExemptionThreshold: number;
+    readonly shipSequenceId: number;
+    readonly cargoSequenceId: number;
+    readonly starbaseSequenceId: bigint;
+};
+export interface DockFundingIntent {
+    readonly address: Address;
+    readonly game: Address;
+    readonly profile: Address;
+    readonly authority: Address;
+    readonly certificate: Address;
+    readonly keyIndex: number;
+    readonly character: Address;
+    readonly system: Address;
+    readonly starbasePlayer: Address;
+}
+export type FleetDockFundingGuard = DockFundingIntent & DockFundingAmounts & {
+    readonly kind: 'fleet-dock-funding';
+    readonly describes: string;
+    readonly dataHash?: never;
+};
+export declare function dockGrowthDebit(rate: bigint, threshold: number, length: number): bigint;
+export declare function normalizeFleetDockFundingGuard(value: Record<string, unknown>, wire?: boolean): FleetDockFundingGuard;
+export declare function dockFundingGuardToJSON(guard: FleetDockFundingGuard): RuntimeWire<FleetDockFundingGuard>;
+/** Requires one exact funding assertion for each current docking instruction. */
+export declare function validateFleetDockFundingGuards(steps: readonly PlanStep[], guards: readonly PlanPrecondition[]): void;
+export {};
+//# sourceMappingURL=fleet-dock-funding-guard.d.ts.map

package/dist/internal/planning/fleet-dock-funding-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-dock-funding-guard.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/fleet-dock-funding-guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,OAAO,EACb,MAAM,aAAa,CAAC;AAMrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAE1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,QAAA,MAAM,OAAO,oSAWH,CAAC;AACX,MAAM,MAAM,2BAA2B,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;AACnE,MAAM,MAAM,kBAAkB,GAC1B;IACE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;CAC9C,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC,CAAC;AACN,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC;AACD,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,GACnD,kBAAkB,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;CAC3B,CAAC;AACJ,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,MAAM,CAKR;AACD,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,UAAQ,GACX,qBAAqB,CA4GvB;AACD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,qBAAqB,GAC3B,WAAW,CAAC,qBAAqB,CAAC,CAOpC;AAqBD,iFAAiF;AACjF,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAClC,IAAI,CAgFN"}

package/dist/internal/planning/fleet-dock-funding-guard.js

@@ -0,0 +1,225 @@
+import { isAddress, isSignerRole, isWritableRole, } from '@solana/kit';
+import { InvalidActionInputError, SageSdkError } from '../../client/errors.js';
+import { IDLE_TO_DOCKED_DISCRIMINATOR, SAGE_PROGRAM_ADDRESS, } from '../c4/runtime-bindings.js';
+import { rentMinimumBalance } from './rent.js';
+export const MAXIMUM_DOCK_GROWTH_BYTES = 40;
+const REASONS = [
+    'unsupported-account-layout',
+    'unsupported-fleet-state',
+    'noncanonical-account-encoding',
+    'stale-definition-sequences',
+    'stale-starbase-sequence',
+    'pending-recovery',
+    'active-stimulants',
+    'funding-state-unavailable',
+    'accounts-below-rent-reserve',
+    'profile-below-storage-ceiling',
+];
+export function dockGrowthDebit(rate, threshold, length) {
+    return (rentMinimumBalance(rate, threshold, length + MAXIMUM_DOCK_GROWTH_BYTES) -
+        rentMinimumBalance(rate, threshold, length));
+}
+export function normalizeFleetDockFundingGuard(value, wire = false) {
+    const bad = () => {
+        throw new InvalidActionInputError('fleet-dock-funding', value, 'the exact current docking intent, Rent quote and gross storage ceiling', 'Recreate the docking Plan; do not alter its saved qualification or debit fields.');
+    };
+    const row = { ...value };
+    const addresses = [
+        'address',
+        'game',
+        'profile',
+        'authority',
+        'certificate',
+        'character',
+        'system',
+        'starbasePlayer',
+    ];
+    const quote = [
+        'maximumProfileDebit',
+        'fleetDataLengthBytes',
+        'rentLamportsPerByteYear',
+        'rentExemptionThreshold',
+        'shipSequenceId',
+        'cargoSequenceId',
+        'starbaseSequenceId',
+    ];
+    const keys = [
+        'kind',
+        ...addresses,
+        'keyIndex',
+        'status',
+        'describes',
+        ...(row.status === 'available' ? quote : ['reason']),
+    ];
+    if (keys.some((k) => !Object.hasOwn(row, k)) ||
+        Object.keys(row).some((k) => !keys.includes(k)))
+        bad();
+    for (const k of addresses)
+        if (typeof row[k] !== 'string' || !isAddress(row[k]))
+            bad();
+    if (row.kind !== 'fleet-dock-funding' ||
+        typeof row.describes !== 'string' ||
+        !row.describes.trim() ||
+        !Number.isInteger(row.keyIndex) ||
+        row.keyIndex < 0 ||
+        row.keyIndex > 65535)
+        bad();
+    if (row.status === 'available') {
+        for (const k of [
+            'maximumProfileDebit',
+            'rentLamportsPerByteYear',
+            'starbaseSequenceId',
+        ]) {
+            if (wire) {
+                if (typeof row[k] !== 'string' || !/^(0|[1-9][0-9]*)$/.test(row[k]))
+                    bad();
+                row[k] = BigInt(row[k]);
+            }
+            if (typeof row[k] !== 'bigint' ||
+                row[k] < 0n ||
+                row[k] > 0xffffffffffffffffn)
+                bad();
+        }
+        for (const k of [
+            'fleetDataLengthBytes',
+            'shipSequenceId',
+            'cargoSequenceId',
+        ])
+            if (!Number.isInteger(row[k]) ||
+                row[k] < 0 ||
+                row[k] > 0xffffffff)
+                bad();
+        if (row.fleetDataLengthBytes < 685 ||
+            typeof row.rentExemptionThreshold !== 'number' ||
+            !Number.isFinite(row.rentExemptionThreshold) ||
+            row.rentExemptionThreshold < 0)
+            bad();
+        try {
+            if (row.maximumProfileDebit !==
+                dockGrowthDebit(row.rentLamportsPerByteYear, row.rentExemptionThreshold, row.fleetDataLengthBytes))
+                bad();
+        }
+        catch {
+            bad();
+        }
+    }
+    else if (row.status !== 'unavailable' ||
+        !REASONS.includes(row.reason))
+        bad();
+    return Object.freeze(row);
+}
+export function dockFundingGuardToJSON(guard) {
+    return Object.fromEntries(Object.entries(guard).map(([key, value]) => [
+        key,
+        typeof value === 'bigint' ? String(value) : value,
+    ]));
+}
+/** Pinned IdleToDocked account order (qualification #825), for diagnostics. */
+const DOCK_ACCOUNT_LABELS = [
+    'authority',
+    'Profile',
+    'key certificate',
+    'Profile program',
+    'Fleet',
+    'Star System',
+    'StarbasePlayer',
+    'Game',
+    'faction relation tracker',
+    'faction standing slot',
+    'faction config slot',
+    'System ownership',
+    'owner faction slot',
+];
+const SEQUENCE_REMEDY = 'Run the steps as separate confirmed transactions, for example with createPlanSequence and executePlanSequence, and refresh the docking Plan after the other step confirms.';
+const PROFILE_REMEDY = 'Refresh funding and recreate a qualified docking Plan, or run the steps as separate confirmed transactions with createPlanSequence and executePlanSequence.';
+/** Requires one exact funding assertion for each current docking instruction. */
+export function validateFleetDockFundingGuards(steps, guards) {
+    const selected = guards.filter((g) => g.kind === 'fleet-dock-funding');
+    const docks = steps.flatMap((step, index) => step.instruction.programAddress === SAGE_PROGRAM_ADDRESS &&
+        IDLE_TO_DOCKED_DISCRIMINATOR.every((v, n) => step.instruction.data?.[n] === v)
+        ? [{ step, index }]
+        : []);
+    const fail = () => {
+        throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'Docking requires its exact instruction-bound Profile storage safeguard. Refresh the Fleet and recreate the docking Plan before signing.');
+    };
+    if (selected.length !== docks.length)
+        fail();
+    for (const { step, index: requiringStepIndex } of docks) {
+        const a = step.instruction.accounts;
+        const matches = selected.filter((g) => g.address === a[4].address);
+        if (matches.length !== 1)
+            fail();
+        const g = matches[0];
+        const data = step.instruction.data;
+        if (g.profile !== a[1].address ||
+            g.authority !== a[0].address ||
+            g.certificate !== a[2].address ||
+            g.system !== a[5].address ||
+            g.starbasePlayer !== a[6].address ||
+            g.game !== a[7].address ||
+            g.keyIndex !== (data[8] | (data[9] << 8)) ||
+            step.signers.length !== 1 ||
+            step.signers[0] !== g.authority)
+            fail();
+        for (const address of [g.address, g.character, g.system, g.starbasePlayer])
+            if (!guards.some((v) => v.kind === 'account-state' && v.address === address))
+                fail();
+        // Transaction compilation merges privileges across instructions, so the
+        // qualified quote holds only if no other step can change what docking
+        // reads or writes. Protection follows the dock's own account roles: its
+        // writable accounts admit no other reference, and its readonly inputs admit
+        // no other writer. The signing authority is not a qualification input, and
+        // an available quote shares its Profile through the per-Profile funding
+        // check, so only an unavailable quote isolates the Profile.
+        a.forEach((meta, position) => {
+            if (isSignerRole(meta.role))
+                return;
+            const profile = position === 1;
+            if (profile && g.status === 'available')
+                return;
+            const exclusive = isWritableRole(meta.role);
+            const conflictingStepIndex = steps.findIndex((other, index) => index !== requiringStepIndex &&
+                other.instruction.accounts?.some((candidate) => candidate.address === meta.address &&
+                    (exclusive || isWritableRole(candidate.role))));
+            if (conflictingStepIndex < 0)
+                return;
+            throw new DockAccountReferenceConflictError({
+                resource: meta.address,
+                // validateFleetDockingGuards pins the 13-account layout.
+                accountLabel: DOCK_ACCOUNT_LABELS[position],
+                verb: exclusive ? 'referencing' : 'writing',
+                condition: profile
+                    ? ' while docking storage bounds are unavailable'
+                    : '',
+                remedy: profile ? PROFILE_REMEDY : SEQUENCE_REMEDY,
+                requiringStepIndex,
+                conflictingStepIndex,
+                requiringStepDescription: step.describes,
+                conflictingStepDescription: steps[conflictingStepIndex].describes,
+            });
+        });
+    }
+}
+/** Account-reference conflicts do not assert a declared semantic invalidation. */
+class DockAccountReferenceConflictError extends SageSdkError {
+    conflictKind = 'references';
+    resource;
+    accountLabel;
+    requiringStepIndex;
+    conflictingStepIndex;
+    requiringStepDescription;
+    conflictingStepDescription;
+    remedy;
+    constructor(options) {
+        const { resource, accountLabel, requiringStepIndex, conflictingStepIndex, requiringStepDescription, conflictingStepDescription, remedy, condition, verb, } = options;
+        super('INCOMPATIBLE_PLAN_COMPOSITION', `Plan step ${String(requiringStepIndex)} ("${requiringStepDescription}") cannot share a transaction with step ${String(conflictingStepIndex)} ("${conflictingStepDescription}") ${verb} the same ${accountLabel} (${resource})${condition}. ${remedy}`);
+        this.resource = resource;
+        this.accountLabel = accountLabel;
+        this.requiringStepIndex = requiringStepIndex;
+        this.conflictingStepIndex = conflictingStepIndex;
+        this.requiringStepDescription = requiringStepDescription;
+        this.conflictingStepDescription = conflictingStepDescription;
+        this.remedy = remedy;
+    }
+}
+//# sourceMappingURL=fleet-dock-funding-guard.js.map