@aephia/atlas-kit 0.6.0-next.17 → 0.6.0-next.171

package/dist/fleets/actions/deployment-storage.js

@@ -0,0 +1,297 @@
+import { isAddress } from '@solana/kit';
+import { InvalidActionInputError, SageSdkError } from '../../client/errors.js';
+import { readContextRawAccounts } from '../../client/reconciliation.js';
+import { requireGameAddress } from '../../internal/game-context.js';
+import { attachJsonSerialization } from '../../internal/json.js';
+import { characterAccountDefinition } from '../../internal/c4/character.js';
+import { fleetAccountDefinition } from '../../internal/c4/fleet.js';
+import { deriveFleetCreationAddress, emptyDockedFleetSize, } from '../../internal/c4/fleet-creation.js';
+import { decodeCanonicalStarbasePlayer, starbasePlayerSize, withDisbandedFleet, withHangarEntry, } from '../../internal/c4/fleet-disband.js';
+import { MAX_COMMANDERS_AND_TITANS_PER_FLEET, MAX_TITANS_PER_FLEET, fleetCapacityPoints, shipSizeName, shipSizeRank, } from '../../internal/c4/fleet-ship-assembly.js';
+import { decodeCanonicalFleet } from '../../internal/c4/fleet-storage.js';
+import { starbasePlayerAccountDefinition } from '../../internal/c4/starbase.js';
+import { validateFleetCreationLabel } from '../../internal/planning/fleet-creation.js';
+import { RENT_ADDRESS, readRent } from '../../internal/planning/rent.js';
+import { readFreshGameShipAssemblyCatalog } from '../../registry/ships.js';
+const SYSTEM_PROGRAM = '11111111111111111111111111111111';
+function readInput(input) {
+    const bad = () => {
+        throw new InvalidActionInputError('input', input, 'starbasePlayer, optional disband and label, ships as { shipId: u16, amount: 1n through 255n }[] with at least one entry, and optional u16 cargoIds', 'Describe the proposed deployment with addresses, ship configuration ids and cargo ids only, then estimate again.');
+    };
+    if (typeof input !== 'object' || input === null)
+        return bad();
+    const value = input;
+    const allowed = ['starbasePlayer', 'disband', 'label', 'ships', 'cargoIds'];
+    const u16 = (id) => typeof id === 'number' && Number.isInteger(id) && id >= 0 && id <= 65535;
+    if (Object.keys(value).some((key) => !allowed.includes(key)) ||
+        typeof value.starbasePlayer !== 'string' ||
+        !isAddress(value.starbasePlayer) ||
+        (value.disband !== undefined &&
+            (typeof value.disband !== 'string' || !isAddress(value.disband))) ||
+        !Array.isArray(value.ships) ||
+        value.ships.length === 0 ||
+        !value.ships.every((ship) => typeof ship === 'object' &&
+            ship !== null &&
+            Object.keys(ship).every((key) => key === 'shipId' || key === 'amount') &&
+            u16(ship.shipId) &&
+            typeof ship.amount === 'bigint' &&
+            ship.amount >= 1n &&
+            ship.amount <= 255n) ||
+        (value.cargoIds !== undefined &&
+            (!Array.isArray(value.cargoIds) || !value.cargoIds.every(u16))))
+        return bad();
+    if (value.label !== undefined)
+        validateFleetCreationLabel(value.label);
+    return value;
+}
+function refuse(message) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', message);
+}
+/**
+ * Estimates the Profile storage funding a proposed Fleet deployment needs
+ * before any of it runs: optionally disbanding a Docked Fleet, creating an
+ * empty Fleet, adding ship configurations in order (with their components) and
+ * loading its initial cargo hold. Each stage reports the accounts it settles,
+ * their sizes and rent minimums, and an upper bound on its Profile debit.
+ *
+ * Verified against the program's behaviour: each stage sets every resized
+ * account to the rent minimum of its new size, withdrawing a shortfall from
+ * the Profile. A disband grows the StarbasePlayer by a hangar entry per ship id
+ * and a cargo line per cargo id it lacks. Creation funds the empty Fleet less
+ * any lamports already at its address. Each assembly adds a ship line and the
+ * configuration's component lines to the Fleet, and a hangar entry to the
+ * StarbasePlayer when it has none for that configuration; it settles the
+ * StarbasePlayer's rent even when its size is unchanged. Loading cargo adds a
+ * cargo hold line per new cargo id; loading crew resizes nothing, so it has no
+ * stage. Observed balances count for the first stage that touches an account;
+ * later stages assume it was left at its rent minimum. The disbanded Fleet's
+ * refund, lines that empty and any other freed storage are never credited.
+ *
+ * Unmet Character or StarbasePlayer requirements (a free Fleet slot, maximum
+ * ship size, research, Fleet size, components) are listed, not enforced, so a
+ * roster can be sized before it is eligible. A roster no Character can field
+ * (above the Game's Fleet size, or too many Commanders or Titans) is refused.
+ * Hull availability, transaction fees, the Profile's own rent reserve and a
+ * Character resynchronization are not included. Plan each real stage with its
+ * planner after the previous one confirms.
+ *
+ * @example
+ * ```ts
+ * import { estimateFleetDeploymentStorage } from '@aephia/atlas-kit/fleets/actions';
+ *
+ * declare const ctx: SageContext;
+ * declare const starbasePlayer: Address;
+ * declare const oldFleet: Address;
+ * const estimate = await estimateFleetDeploymentStorage(ctx, {
+ *   starbasePlayer,
+ *   disband: oldFleet,
+ *   label: 'Miner 6',
+ *   ships: [{ shipId: 1301, amount: 1n }],
+ *   cargoIds: [7560],
+ * });
+ * for (const stage of estimate.stages) console.log(stage.kind, stage.profileDebit);
+ * for (const missing of estimate.unmetPrerequisites) console.log(missing.message);
+ * console.log(`Profile needs ${estimate.totalProfileDebit} lamports above its reserve`);
+ * ```
+ */
+export async function estimateFleetDeploymentStorage(ctx, input) {
+    const { starbasePlayer, disband, label, ships, cargoIds = [], } = readInput(input);
+    const game = requireGameAddress(ctx);
+    const [playerRaw, rentRaw, disbandRaw] = await readContextRawAccounts(ctx, [
+        starbasePlayer,
+        RENT_ADDRESS,
+        ...(disband === undefined ? [] : [disband]),
+    ]);
+    if (!playerRaw)
+        refuse(`StarbasePlayer ${starbasePlayer} does not exist. Register at the Starbase where the Fleet will be created, then estimate again.`);
+    const player = starbasePlayerAccountDefinition.decode(playerRaw);
+    const profile = player.playerProfile;
+    const fleetAddress = label === undefined
+        ? undefined
+        : await deriveFleetCreationAddress(game, profile, label);
+    const [{ catalog }, [characterRaw, targetRaw]] = await Promise.all([
+        readFreshGameShipAssemblyCatalog(ctx),
+        readContextRawAccounts(ctx, [
+            player.character,
+            ...(fleetAddress === undefined ? [] : [fleetAddress]),
+        ]),
+    ]);
+    if (!characterRaw)
+        refuse(`Character ${player.character} of the StarbasePlayer does not exist. Register the Character, then estimate again.`);
+    const character = characterAccountDefinition.decode(characterRaw);
+    if (character.game !== game || character.playerProfile !== profile)
+        refuse(`The StarbasePlayer's Character belongs to another Game or Profile than the configured Game ${game} and Profile ${profile}. Select a StarbasePlayer of this Game, then estimate again.`);
+    if (!rentRaw)
+        refuse('The Rent sysvar is unavailable. Check the configured RPC endpoint, then estimate again.');
+    const rent = readRent(rentRaw);
+    const stages = [];
+    const unmet = [];
+    // The StarbasePlayer only grows in this estimate: lines a stage empties are
+    // kept, so freed storage is never credited.
+    let playerValue = decodeCanonicalStarbasePlayer(playerRaw, 'Refresh a valid StarbasePlayer before estimating a Fleet deployment.');
+    let playerSize = playerRaw.data.length;
+    let playerBalance = playerRaw.lamports;
+    const resizePlayer = (next) => {
+        const size = starbasePlayerSize(next);
+        const minimum = rent(size);
+        const account = Object.freeze({
+            account: 'starbasePlayer',
+            address: starbasePlayer,
+            sizeBefore: playerSize,
+            sizeAfter: size,
+            rentMinimum: minimum,
+        });
+        const debit = minimum > playerBalance ? minimum - playerBalance : 0n;
+        playerValue = next;
+        playerSize = size;
+        playerBalance = minimum;
+        return { account, debit };
+    };
+    let freedSlot = 0;
+    if (disband !== undefined) {
+        if (!disbandRaw)
+            refuse(`Fleet ${disband} does not exist. Select an owned Fleet Docked at this Starbase to disband, then estimate again.`);
+        const fleet = fleetAccountDefinition.decode(disbandRaw);
+        if (fleet.game !== game ||
+            fleet.ownerProfile !== profile ||
+            fleet.state.kind !== 'docked' ||
+            fleet.state.system !== player.system)
+            refuse(`Fleet ${disband} is not owned by the StarbasePlayer's Profile and Docked at its Starbase. Dock it there or estimate without disbanding it.`);
+        const { account, debit } = resizePlayer(withDisbandedFleet(decodeCanonicalFleet(disbandRaw), playerValue));
+        stages.push(Object.freeze({
+            kind: 'disband',
+            fleet: disband,
+            accounts: Object.freeze([account]),
+            profileDebit: debit,
+        }));
+        freedSlot = 1;
+    }
+    const values = character.modifiers.values;
+    if (character.counts.fleets - freedSlot >= values.fleetConcurrency)
+        unmet.push({
+            kind: 'fleet-slot',
+            stage: stages.length,
+            message: `The Character uses ${String(character.counts.fleets - freedSlot)} of ${String(values.fleetConcurrency)} Fleet slots${freedSlot ? ' after the disband' : ''}. Disband another Fleet or unlock research that raises Fleet concurrency.`,
+        });
+    if (targetRaw &&
+        (targetRaw.executable ||
+            targetRaw.owner !== SYSTEM_PROGRAM ||
+            targetRaw.data.length !== 0))
+        refuse(`The Fleet address for label ${String(label)} (${String(fleetAddress)}) already holds state. Choose a different label, then estimate again.`);
+    const fleetShips = new Map();
+    const components = new Map();
+    const cargoHold = new Map();
+    let fleetSize = emptyDockedFleetSize();
+    let fleetBalance = targetRaw?.lamports ?? 0n;
+    const resizeFleet = (sizeBefore) => {
+        const size = emptyDockedFleetSize({ fleetShips, components, cargoHold });
+        const minimum = rent(size);
+        const account = Object.freeze({
+            account: 'fleet',
+            address: fleetAddress,
+            sizeBefore,
+            sizeAfter: size,
+            rentMinimum: minimum,
+        });
+        const debit = minimum > fleetBalance ? minimum - fleetBalance : 0n;
+        fleetSize = size;
+        fleetBalance = minimum;
+        return { account, debit };
+    };
+    const created = resizeFleet(0);
+    stages.push(Object.freeze({
+        kind: 'create',
+        accounts: Object.freeze([created.account]),
+        profileDebit: created.debit,
+    }));
+    const classes = [0, 0, 0, 0, 0, 0, 0, 0];
+    const held = new Map(playerValue.cargoPod.amounts);
+    for (const { shipId, amount } of ships) {
+        const stage = stages.length;
+        const row = catalog.rows.find((candidate) => candidate.id === shipId);
+        if (!row)
+            throw new InvalidActionInputError('ships', shipId, 'a ship configuration id in the current Game ship definitions', `Ship configuration ${String(shipId)} is not in the current Game ship definitions. Select a defined configuration, then estimate again.`);
+        const size = shipSizeName(row.sizeClass);
+        if (row.sizeClass > shipSizeRank(values.maxShipSize))
+            unmet.push({
+                kind: 'ship-size',
+                stage,
+                message: `Ship configuration ${String(shipId)} is ${size}, above the Character's maximum ship size ${values.maxShipSize}. Unlock research that raises the maximum ship size.`,
+            });
+        const missing = row.researchRequirements.filter((tag) => !values.researchTags.includes(tag));
+        if (missing.length > 0)
+            unmet.push({
+                kind: 'research',
+                stage,
+                message: `Ship configuration ${String(shipId)} requires research tags [${missing.join(', ')}] the Character lacks. Unlock the research nodes that grant them.`,
+            });
+        classes[row.sizeClass] = classes[row.sizeClass] + Number(amount);
+        const points = fleetCapacityPoints(classes);
+        if (points > catalog.maxFleetSize)
+            throw new InvalidActionInputError('ships', input.ships, `a roster within the Game's ${String(catalog.maxFleetSize)}-point Fleet limit`, `The roster uses ${String(points)} Fleet points by ship configuration ${String(shipId)}, above the Game's ${String(catalog.maxFleetSize)}-point Fleet limit. Reduce the roster, then estimate again.`);
+        if (classes[7] > MAX_TITANS_PER_FLEET ||
+            classes[6] + classes[7] > MAX_COMMANDERS_AND_TITANS_PER_FLEET)
+            throw new InvalidActionInputError('ships', input.ships, `at most ${String(MAX_TITANS_PER_FLEET)} Titan and ${String(MAX_COMMANDERS_AND_TITANS_PER_FLEET)} Commanders and Titans together`, 'A Fleet holds at most one Titan, and at most two Commanders and Titans together. Split the roster across Fleets, then estimate again.');
+        if (points > values.fleetSize)
+            unmet.push({
+                kind: 'fleet-size',
+                stage,
+                message: `The roster uses ${String(points)} Fleet points after ship configuration ${String(shipId)}, above the Character's Fleet size ${String(values.fleetSize)}. Unlock Fleet-size research or reduce the roster.`,
+            });
+        const short = [];
+        for (const [cargoId, required] of row.componentRequirements) {
+            const moved = BigInt(required) * amount;
+            const available = held.get(cargoId) ?? 0n;
+            if (available < moved)
+                short.push(`${String(moved)} of cargo ${String(cargoId)} (holds ${String(available)})`);
+            held.set(cargoId, available > moved ? available - moved : 0n);
+            components.set(cargoId, (components.get(cargoId) ?? 0n) + moved);
+        }
+        if (short.length > 0)
+            unmet.push({
+                kind: 'components',
+                stage,
+                message: `Ship configuration ${String(shipId)} needs components the StarbasePlayer does not hold: ${short.join(', ')}. Buy, craft or move them to this StarbasePlayer.`,
+            });
+        fleetShips.set(shipId, (fleetShips.get(shipId) ?? 0n) + amount);
+        const fleet = resizeFleet(fleetSize);
+        // Assembly settles the StarbasePlayer's rent even when its hangar already
+        // holds this configuration, so its balance advances on every assembly.
+        const player = resizePlayer(withHangarEntry(playerValue, shipId));
+        stages.push(Object.freeze({
+            kind: 'add-ships',
+            shipId,
+            amount,
+            accounts: Object.freeze([fleet.account, player.account]),
+            profileDebit: fleet.debit + player.debit,
+        }));
+    }
+    const loaded = [...new Set(cargoIds)];
+    if (loaded.length > 0) {
+        for (const cargoId of loaded)
+            cargoHold.set(cargoId, cargoHold.get(cargoId) ?? 0n);
+        const fleet = resizeFleet(fleetSize);
+        stages.push(Object.freeze({
+            kind: 'load-cargo',
+            cargoIds: Object.freeze(loaded),
+            accounts: Object.freeze([fleet.account]),
+            profileDebit: fleet.debit,
+        }));
+    }
+    return Object.freeze(attachJsonSerialization({
+        stages: Object.freeze(stages),
+        totalProfileDebit: stages.reduce((total, stage) => total + stage.profileDebit, 0n),
+        unmetPrerequisites: Object.freeze(unmet.map((p) => Object.freeze(p))),
+        profile,
+        character: player.character,
+        observedSlot: playerRaw.slot,
+        rent: Object.freeze({
+            lamportsPerByteYear: rent.rentLamportsPerByteYear,
+            exemptionThreshold: rent.rentExemptionThreshold,
+        }),
+        profileUnit: 'lamports',
+        transactionFees: 'excluded',
+        characterResync: 'excluded',
+    }));
+}
+//# sourceMappingURL=deployment-storage.js.map

package/dist/fleets/actions/deployment-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-storage.js","sourceRoot":"","sources":["../../../src/fleets/actions/deployment-storage.ts"],"names":[],"mappings":"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"}

package/dist/fleets/actions/disband.d.ts

@@ -0,0 +1,42 @@
+import type { Address } from '@solana/kit';
+import type { SageContext } from '../../client/contracts.js';
+import type { PlanAuthorization } from '../../internal/planning/authorization-adapter.js';
+import type { Plan } from '../../planning/index.js';
+/** Explicit address-only authorization for disbanding an owned Docked Fleet.
+ * @example
+ * ```ts
+ * declare const profile: Address, authority: Address;
+ * const options: PlanFleetDisbandOptions = { authorization: { profile, authority, keyIndex: 0 } };
+ * ```
+ */
+export interface PlanFleetDisbandOptions {
+    readonly authorization: PlanAuthorization;
+}
+/** Plans disbanding an owned Docked Fleet, the game's only way to take a Fleet
+ * apart. Verified against the program's behaviour: the Fleet's ships return to
+ * the StarbasePlayer's hangar where it is Docked, its crew to that
+ * StarbasePlayer, and its fuel, ammo, cargo hold and components merge into the
+ * StarbasePlayer's cargo. The Character's Fleet slot is freed and the Fleet
+ * closes, refunding its rent to the Profile. To replace a composition, disband,
+ * confirm, then plan `planCreateFleet` and `planAddShipToFleet` from fresh
+ * state; disband and creation for the same Character cannot be combined.
+ *
+ * The Fleet must be a canonical owned player Fleet, not rented, Docked at a
+ * Starbase where the Character has a current StarbasePlayer of its faction,
+ * fully repaired, with no warp or scan cooldown running. The program also
+ * needs full AP and SP, which recover on timers and stay chain-authoritative.
+ * Uses a direct Profile AUTH key or a manageFleet key scoped to SAGE or the
+ * Fleet. New hangar entries and cargo lines grow the StarbasePlayer, and the
+ * program funds that growth from the Profile vault; that debit is bounded and
+ * rechecked before signing, but it is not an atomic on-chain spending cap.
+ * Any change to the Fleet after planning refuses the Plan. Simulate before
+ * signing, then read the StarbasePlayer back after confirmation.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext, fleet: Address, profile: Address, authority: Address;
+ * const plan = await planFleetDisband(ctx, fleet, { authorization: { profile, authority, keyIndex: 0 } });
+ * console.log(plan.describe());
+ * ```
+ */
+export declare function planFleetDisband(ctx: SageContext, fleet: Address, input: PlanFleetDisbandOptions): Promise<Plan>;
+//# sourceMappingURL=disband.d.ts.map

package/dist/fleets/actions/disband.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disband.d.ts","sourceRoot":"","sources":["../../../src/fleets/actions/disband.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAO7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kDAAkD,CAAC;AAS1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAGpD;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;CAC3C;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAiFf"}

package/dist/fleets/actions/disband.js

@@ -0,0 +1,107 @@
+import { InvalidActionInputError, SageSdkError } from '../../client/errors.js';
+import { readContextRawAccounts } from '../../client/reconciliation.js';
+import { requireGameAddress } from '../../internal/game-context.js';
+import { fleetAccountDefinition } from '../../internal/c4/fleet.js';
+import { disbandFleetInstruction } from '../../internal/c4/fleet-disband.js';
+import { accountStatePrecondition } from '../../internal/planning/account-state.js';
+import { readDirectOptions } from '../../internal/planning/direct-options.js';
+import { readDisbandStorageAction } from '../../internal/planning/disband-storage-actions.js';
+import { disbandSemantics } from '../../internal/planning/fleet-disband-guard.js';
+import { resolveFleetDisband, validateFleetDisband, } from '../../internal/planning/fleet-disband.js';
+import { planStorageFunding } from '../../internal/planning/storage-actions.js';
+import { buildPlannerPlan } from '../../planning/plan-construction.js';
+function options(input) {
+    const { authorization } = readDirectOptions(input, ['authorization'], () => {
+        throw new InvalidActionInputError('options', input, 'authorization only; direct authority, Profile and u16 keyIndex', 'Pass address-only disband options. Certificates are unsupported; use a direct Profile key.');
+    });
+    return { authorization };
+}
+/** Plans disbanding an owned Docked Fleet, the game's only way to take a Fleet
+ * apart. Verified against the program's behaviour: the Fleet's ships return to
+ * the StarbasePlayer's hangar where it is Docked, its crew to that
+ * StarbasePlayer, and its fuel, ammo, cargo hold and components merge into the
+ * StarbasePlayer's cargo. The Character's Fleet slot is freed and the Fleet
+ * closes, refunding its rent to the Profile. To replace a composition, disband,
+ * confirm, then plan `planCreateFleet` and `planAddShipToFleet` from fresh
+ * state; disband and creation for the same Character cannot be combined.
+ *
+ * The Fleet must be a canonical owned player Fleet, not rented, Docked at a
+ * Starbase where the Character has a current StarbasePlayer of its faction,
+ * fully repaired, with no warp or scan cooldown running. The program also
+ * needs full AP and SP, which recover on timers and stay chain-authoritative.
+ * Uses a direct Profile AUTH key or a manageFleet key scoped to SAGE or the
+ * Fleet. New hangar entries and cargo lines grow the StarbasePlayer, and the
+ * program funds that growth from the Profile vault; that debit is bounded and
+ * rechecked before signing, but it is not an atomic on-chain spending cap.
+ * Any change to the Fleet after planning refuses the Plan. Simulate before
+ * signing, then read the StarbasePlayer back after confirmation.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext, fleet: Address, profile: Address, authority: Address;
+ * const plan = await planFleetDisband(ctx, fleet, { authorization: { profile, authority, keyIndex: 0 } });
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planFleetDisband(ctx, fleet, input) {
+    const { authorization } = options(input);
+    const game = requireGameAddress(ctx);
+    const [fleetRaw] = await readContextRawAccounts(ctx, [fleet]);
+    if (!fleetRaw || fleetRaw.executable)
+        throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'The selected Fleet is missing or executable. Refresh a valid owned Fleet and replan the disband.', { address: fleet });
+    const docked = fleetAccountDefinition.decode(fleetRaw).state;
+    if (docked.kind !== 'docked')
+        throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'Only a Docked Fleet can disband. Dock it at a Starbase where the Character has a current StarbasePlayer and replan.', { address: fleet });
+    const intent = {
+        game,
+        profile: authorization.profile,
+        authority: authorization.authority,
+        keyIndex: authorization.keyIndex,
+        fleet,
+        system: docked.system,
+    };
+    const resolved = await resolveFleetDisband(intent);
+    const addresses = [
+        resolved.profile,
+        resolved.character,
+        resolved.profileFaction,
+        resolved.system,
+        resolved.starbasePlayer,
+        resolved.rent,
+        resolved.clock,
+    ];
+    const raw = await readContextRawAccounts(ctx, addresses);
+    const accounts = new Map(addresses.map((address, index) => [address, raw[index]]));
+    accounts.set(fleet, fleetRaw);
+    const { fleet: data } = await validateFleetDisband(intent, resolved, accounts);
+    const instruction = disbandFleetInstruction({
+        ...intent,
+        character: resolved.character,
+        starbasePlayer: resolved.starbasePlayer,
+    });
+    const storage = planStorageFunding({
+        action: readDisbandStorageAction(instruction, accounts),
+        accounts,
+        label: 'Fleet disband',
+    });
+    const ships = data.fleetShips
+        .map(({ shipId, quantity }) => `${String(quantity)} of configuration ${String(shipId)}`)
+        .join(', ');
+    const summary = `Disband Fleet ${data.name} (${fleet}) at StarbasePlayer ${resolved.starbasePlayer}: ${ships || 'no ships'} return to its hangar, ${String(data.crewCount)} crew return to it, and the Fleet's fuel, ammo, cargo hold and components merge into its cargo. The Character's Fleet slot is freed, and the Fleet closes, refunding its ${String(fleetRaw.lamports)}-lamport balance to Profile ${intent.profile}. ${storage.disclosure} The program also needs full AP and SP when the instruction runs. Transaction fees are separate. Simulate before signing; the chain stays authoritative.`;
+    return buildPlannerPlan({
+        kind: 'fleets.disband',
+        summary,
+        preconditions: [
+            await accountStatePrecondition(fleetRaw, `Fleet ${data.name} keeps its ships, crew, cargo, Docked state, repair and cooldowns as planned.`),
+            storage.guard,
+        ],
+        steps: [
+            {
+                describes: summary,
+                instruction,
+                signers: [intent.authority],
+                semantics: disbandSemantics(instruction),
+            },
+        ],
+    });
+}
+//# sourceMappingURL=disband.js.map

package/dist/fleets/actions/disband.js.map

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

package/dist/fleets/actions/dock-bounds.d.ts

@@ -0,0 +1,38 @@
+import type { Address } from '../../client/contracts.js';
+import type { Plan } from '../../planning/index.js';
+import { type DockBoundsUnavailableReason } from '../../internal/planning/fleet-dock-funding-guard.js';
+/** Conservative gross Profile storage debit for qualified ordinary docking.
+ * Surplus and refunds are not credited; unavailable never implies zero cost.
+ * @example
+ * ```ts
+ * declare const bounds: FleetDockDebitBounds;
+ * if (bounds.status === 'available') console.log(bounds.maximumProfileDebit);
+ * ```
+ */
+export type FleetDockDebitBounds = {
+    readonly status: 'unavailable';
+    readonly reason: DockBoundsUnavailableReason | 'not-fleet-dock' | 'multiple-fleet-docks' | 'combined-plan';
+    toJSON(): unknown;
+} | {
+    readonly status: 'available';
+    readonly maximumProfileDebit: bigint;
+    readonly profile: Address;
+    readonly fleet: Address;
+    readonly starbasePlayer: Address;
+    readonly profileUnit: 'lamports';
+    readonly maximumFleetGrowthBytes: 40;
+    readonly transactionFees: 'excluded';
+    toJSON(): unknown;
+};
+/** Inspects the persisted docking ceiling without network I/O. Inspect individual
+ * Plans before combining distinct Fleets. Fresh pre-sign checks are not an atomic
+ * on-chain spending cap; state can change before landing.
+ * @example
+ * ```ts
+ * declare const plan: Plan;
+ * const bounds = getFleetDockDebitBounds(plan);
+ * if (bounds.status === 'available') console.log(bounds.maximumProfileDebit);
+ * ```
+ */
+export declare function getFleetDockDebitBounds(plan: Plan): FleetDockDebitBounds;
+//# sourceMappingURL=dock-bounds.d.ts.map

package/dist/fleets/actions/dock-bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dock-bounds.d.ts","sourceRoot":"","sources":["../../../src/fleets/actions/dock-bounds.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEzD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,qDAAqD,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IACE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,EACX,2BAA2B,GAC3B,gBAAgB,GAChB,sBAAsB,GACtB,eAAe,CAAC;IACpB,MAAM,IAAI,OAAO,CAAC;CACnB,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,uBAAuB,EAAE,EAAE,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC;IACrC,MAAM,IAAI,OAAO,CAAC;CACnB,CAAC;AAEN;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG,oBAAoB,CA6CxE"}

package/dist/fleets/actions/dock-bounds.js

@@ -0,0 +1,46 @@
+import { attachJsonSerialization } from '../../internal/json.js';
+import { InvalidActionInputError } from '../../client/errors.js';
+import { isPlanInstance } from '../../planning/plan-instances.js';
+import { MAXIMUM_DOCK_GROWTH_BYTES, } from '../../internal/planning/fleet-dock-funding-guard.js';
+/** Inspects the persisted docking ceiling without network I/O. Inspect individual
+ * Plans before combining distinct Fleets. Fresh pre-sign checks are not an atomic
+ * on-chain spending cap; state can change before landing.
+ * @example
+ * ```ts
+ * declare const plan: Plan;
+ * const bounds = getFleetDockDebitBounds(plan);
+ * if (bounds.status === 'available') console.log(bounds.maximumProfileDebit);
+ * ```
+ */
+export function getFleetDockDebitBounds(plan) {
+    if (!isPlanInstance(plan))
+        throw new InvalidActionInputError('plan', plan, 'a genuine Plan from a planning factory', 'Create or hydrate the Plan through this SDK before reading its debit bounds.');
+    const guards = plan.preconditions.filter((g) => g.kind === 'fleet-dock-funding');
+    if (guards.length !== 1)
+        return Object.freeze(attachJsonSerialization({
+            status: 'unavailable',
+            reason: guards.length === 0 ? 'not-fleet-dock' : 'multiple-fleet-docks',
+        }));
+    if (plan.steps.length !== 1)
+        return Object.freeze(attachJsonSerialization({
+            status: 'unavailable',
+            reason: 'combined-plan',
+        }));
+    const guard = guards[0];
+    if (guard.status === 'unavailable')
+        return Object.freeze(attachJsonSerialization({
+            status: 'unavailable',
+            reason: guard.reason,
+        }));
+    return Object.freeze(attachJsonSerialization({
+        status: 'available',
+        maximumProfileDebit: guard.maximumProfileDebit,
+        profile: guard.profile,
+        fleet: guard.address,
+        starbasePlayer: guard.starbasePlayer,
+        profileUnit: 'lamports',
+        maximumFleetGrowthBytes: MAXIMUM_DOCK_GROWTH_BYTES,
+        transactionFees: 'excluded',
+    }));
+}
+//# sourceMappingURL=dock-bounds.js.map

package/dist/fleets/actions/dock-bounds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dock-bounds.js","sourceRoot":"","sources":["../../../src/fleets/actions/dock-bounds.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EACL,yBAAyB,GAE1B,MAAM,qDAAqD,CAAC;AAgC7D;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAU;IAChD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;QACvB,MAAM,IAAI,uBAAuB,CAC/B,MAAM,EACN,IAAI,EACJ,wCAAwC,EACxC,8EAA8E,CAC/E,CAAC;IACJ,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CACtC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,oBAAoB,CACvC,CAAC;IACF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QACrB,OAAO,MAAM,CAAC,MAAM,CAClB,uBAAuB,CAAC;YACtB,MAAM,EAAE,aAAa;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,sBAAsB;SAC/D,CAAC,CACZ,CAAC;IACJ,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QACzB,OAAO,MAAM,CAAC,MAAM,CAClB,uBAAuB,CAAC;YACtB,MAAM,EAAE,aAAa;YACrB,MAAM,EAAE,eAAe;SACf,CAAC,CACZ,CAAC;IACJ,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;IACzB,IAAI,KAAK,CAAC,MAAM,KAAK,aAAa;QAChC,OAAO,MAAM,CAAC,MAAM,CAClB,uBAAuB,CAAC;YACtB,MAAM,EAAE,aAAa;YACrB,MAAM,EAAE,KAAK,CAAC,MAAM;SACZ,CAAC,CACZ,CAAC;IACJ,OAAO,MAAM,CAAC,MAAM,CAClB,uBAAuB,CAAC;QACtB,MAAM,EAAE,WAAW;QACnB,mBAAmB,EAAE,KAAK,CAAC,mBAAmB;QAC9C,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,KAAK,EAAE,KAAK,CAAC,OAAO;QACpB,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,WAAW,EAAE,UAAU;QACvB,uBAAuB,EAAE,yBAAyB;QAClD,eAAe,EAAE,UAAU;KACnB,CAAC,CACZ,CAAC;AACJ,CAAC"}