@aephia/atlas-kit 0.6.0-next.9 → 0.6.0-next.91

package/dist/planning/execution.js

@@ -1,7 +1,32 @@
-import { hashGameShipConfigurations } from '../registry/ships.js';
+import { revalidateDockFunding } from '../internal/planning/fleet-dock-funding.js';
+import { decodeDockingSequences } from '../registry/docking.js';
+import { revalidateMarketOrder, marketOrderFundingAddresses, } from '../internal/planning/local-market-order-funding.js';
+import { resolveFleetCrewTransfer } from '../internal/planning/fleet-crew-transfer.js';
+import { revalidateScanCompletion } from '../internal/planning/scan-completion.js';
+import { openSignalAddresses, validateOpenSignal, } from '../internal/planning/open-signal.js';
+import { revalidateDetect } from '../internal/planning/scan-detect.js';
+import { resolveFleetRespawn } from '../internal/planning/fleet-respawn.js';
+import { validateFleetAttackActors } from '../internal/planning/fleet-attack-xp.js';
+import { RENT_ADDRESS, readRent } from '../internal/planning/rent.js';
+import { getBase64Decoder, } from '@solana/kit';
+import { hashMovementCharacter } from '../internal/planning/movement-character.js';
+import { validateFleetDockingPolicy } from '../internal/planning/fleet-docking.js';
+import { validateStarbaseSystem } from '../internal/planning/starbase-system.js';
+import { revalidateCharacterRegistration, isEmptySystemAccount, } from '../internal/planning/character-registration.js';
+import { validateFleetArrivalIntent } from '../internal/planning/fleet-arrival.js';
+import { isRuntimeGuard, revalidateRuntimeGuards, } from '../internal/planning/runtime-guards.js';
+import { isFactionTradeGuard } from '../internal/planning/faction-trade-guards.js';
+import { resolveShipImportFunding, validateShipImportFunding, } from '../internal/planning/ship-import-funding.js';
+import { matchesFleetMiningState } from '../internal/planning/mining-stop.js';
+import { requireGameAddress } from '../internal/game-context.js';
+import { matchesFactionTradeState } from '../internal/planning/faction-trade-state.js';
+import { resolveFleetShipAssembly, validateFleetShipAssembly, } from '../internal/planning/fleet-ship-assembly.js';
+import { resolveFleetCreation, validateFleetCreation, } from '../internal/planning/fleet-creation.js';
+import { validateTokenMint } from '../internal/planning/token-mint.js';
+import { hashGameShipConfigurations, decodeGameShipAssemblyCatalog, } from '../registry/ships.js';
 import { validateGameForCharacterRegistration } from '../registry/onboarding.js';
 import { hashAccountState } from '../internal/planning/account-state.js';
-import { hashGameCargoConfigurations } from '../registry/cargo.js';
+import { hashGameCargoConfigurationGuards } from '../registry/cargo.js';
 import { validateWalletCargoCache } from '../internal/c4/wallet-cargo-cache.js';
 import { getAddressEncoder, getProgramDerivedAddress, getAddressDecoder, getBase58Decoder, getBase64EncodedWireTransaction, getSignatureFromTransaction, isAddress, isTransactionModifyingSigner, isTransactionPartialSigner, isTransactionSendingSigner, signAndSendTransactionWithSigners, signTransactionWithSigners, } from '@solana/kit';
 import { InvalidActionInputError, SageSdkError } from '../client/errors.js';
@@ -36,12 +61,23 @@ class MissingWriteTransportError extends SageSdkError {
 class ActionPreconditionFailedError extends SageSdkError {
     describes;
     observedSlot;
-    constructor(precondition, observedSlot) {
-        super('ACTION_PRECONDITION_FAILED', `The account state required by this Plan changed at ${precondition.address}: ${precondition.describes} Refresh the affected game state and create a new Plan before retrying.`, { address: precondition.address });
+    constructor(precondition, observedSlot, cause, address = precondition.address) {
+        super('ACTION_PRECONDITION_FAILED', `The account state required by this Plan changed at ${address}: ${cause ?? precondition.describes} Refresh the affected game state and create a new Plan before retrying.`, { address });
         this.describes = precondition.describes;
         this.observedSlot = observedSlot;
     }
 }
+/** The cause a wrapped guard failure may carry: only a validator's own
+ * precondition cause and remedy for the guarded address. Adapter, provider and
+ * unknown failures yield `undefined`, so the wrapper falls back to the guard's
+ * generic description and never concatenates inner exception text. */
+function guardCause(precondition, error) {
+    return error instanceof SageSdkError &&
+        error.code === 'ACTION_PRECONDITION_FAILED' &&
+        (error.address === undefined || error.address === precondition.address)
+        ? error.message
+        : undefined;
+}
 class TransactionExpiredError extends SageSdkError {
     signature;
     lastValidBlockHeight;
@@ -293,15 +329,219 @@ function matchesTokenAccount(account, expected) {
     return (decoder.decode(account.data.subarray(0, 32)) === expected.mint &&
         decoder.decode(account.data.subarray(32, 64)) === expected.owner);
 }
-async function checkPreconditions(context, preconditions, commitment) {
-    const addresses = [...new Set(preconditions.map(({ address }) => address))];
+function checkRegistrationFunding(registrations, fee) {
+    const balances = new Map();
+    for (const registration of registrations) {
+        const previous = balances.get(registration.funder);
+        if (previous === undefined || registration.observedLamports < previous)
+            balances.set(registration.funder, registration.observedLamports);
+    }
+    if (fee && balances.has(fee.payer))
+        balances.set(fee.payer, balances.get(fee.payer) - fee.lamports);
+    for (const registration of registrations) {
+        const balance = balances.get(registration.funder);
+        if (balance < registration.requiredLamports)
+            throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'Character registration funding cannot cover the ordered upfront storage and applicable transaction fee. Fund the wallet separately and recreate the Plan; a later Character refund cannot fund an earlier allocation.', { address: registration.funder });
+        balances.set(registration.funder, balance - registration.netDebit);
+    }
+    if (fee)
+        for (const registration of registrations) {
+            const balance = balances.get(registration.funder);
+            if (balance !== 0n && balance < registration.minimumBalance)
+                throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'Character registration leaves the funder below its empty-System-account rent minimum. Leave zero or a rent-exempt balance after storage and fees, then recreate the Plan.', { address: registration.funder });
+        }
+}
+async function checkPreconditions(context, allPreconditions, steps, commitment) {
+    for (const guard of allPreconditions) {
+        if (guard.kind === 'fleet-crew-transfer') {
+            try {
+                await resolveFleetCrewTransfer(context, guard, guard, commitment);
+            }
+            catch (error) {
+                throw new ActionPreconditionFailedError(guard, undefined, error instanceof SageSdkError
+                    ? error.message
+                    : 'Crew transfer prerequisites could not be verified. Refresh crew state and recreate the Plan.');
+            }
+        }
+        if (guard.kind === 'scan-completion')
+            await revalidateScanCompletion(context, guard, commitment);
+        if (guard.kind === 'scan-detect')
+            await revalidateDetect(context, guard, commitment);
+        if (guard.kind === 'fleet-attack') {
+            try {
+                await validateFleetAttackActors(context, guard);
+            }
+            catch (error) {
+                throw new ActionPreconditionFailedError(guard, undefined, guardCause(guard, error) ??
+                    'The attacking or defending Fleet or Character could not be verified. Refresh both Fleets and their Characters, then recreate the Plan before signing.');
+            }
+        }
+    }
+    for (const guard of allPreconditions) {
+        if (guard.kind !== 'fleet-respawn')
+            continue;
+        try {
+            const current = await resolveFleetRespawn(context, { ...guard, fleet: guard.address }, guard, commitment);
+            const planned = steps[0].instruction;
+            const fresh = current.instruction;
+            if (planned.programAddress !== fresh.programAddress ||
+                planned.data?.length !== fresh.data?.length ||
+                fresh.data?.some((v, i) => planned.data?.[i] !== v) ||
+                planned.accounts?.length !== fresh.accounts?.length ||
+                fresh.accounts?.some((a, i) => planned.accounts?.[i]?.address !== a.address ||
+                    planned.accounts?.[i]?.role !== a.role))
+                throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'Recovery instruction accounts changed. Recreate and inspect the recovery Plan before signing.');
+        }
+        catch (error) {
+            throw new ActionPreconditionFailedError(guard, undefined, error instanceof SageSdkError
+                ? error.message
+                : 'Recovery prerequisites could not be validated. Refresh the Fleet and recreate the Plan.');
+        }
+    }
+    const checkedXp = new Set();
+    const freshGameVersions = new Map();
+    const registrationFunding = [];
+    const initializations = new Map();
+    for (const guard of allPreconditions) {
+        if (guard.kind !== 'character-registration')
+            continue;
+        registrationFunding.push(await revalidateCharacterRegistration(context, guard, commitment, freshGameVersions, initializations));
+    }
+    checkRegistrationFunding(registrationFunding);
+    for (const guard of allPreconditions) {
+        if (guard.kind !== 'fleet-arrival')
+            continue;
+        try {
+            const current = await validateFleetArrivalIntent(context, guard.intent, freshGameVersions);
+            for (const xp of allPreconditions) {
+                if (xp.kind !== 'xp-runtime' ||
+                    xp.intent.game !== current.xp.intent.game ||
+                    xp.intent.character !== current.xp.intent.character ||
+                    xp.intent.structure !== current.xp.intent.structure ||
+                    (xp.intent.profile !== undefined &&
+                        xp.intent.profile !== current.intent.profile))
+                    continue;
+                if (['xpBudget', 'xpBudgetConfig', 'xpAccrual'].some((key) => xp.accounts[key] !== current.xp.accounts[key]))
+                    throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'Arrival XP runtime changed. Refresh the Fleet and recreate the Plan.');
+                checkedXp.add(xp);
+            }
+            if (current.character !== guard.character ||
+                current.regionTracker !== guard.regionTracker)
+                throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'Arrival account links changed. Refresh the Fleet and recreate the Plan.');
+        }
+        catch (error) {
+            throw new ActionPreconditionFailedError(guard, undefined, error instanceof SageSdkError
+                ? error.message
+                : 'Arrival prerequisites could not be validated. Refresh the Fleet and recreate the Plan.');
+        }
+    }
+    await revalidateRuntimeGuards(context, allPreconditions
+        .filter(isRuntimeGuard)
+        .filter((guard) => !checkedXp.has(guard)), freshGameVersions);
+    const preconditions = allPreconditions.filter((guard) => !isRuntimeGuard(guard) &&
+        guard.kind !== 'fleet-attack' &&
+        guard.kind !== 'fleet-arrival' &&
+        guard.kind !== 'character-registration' &&
+        guard.kind !== 'scan-detect' &&
+        guard.kind !== 'scan-completion' &&
+        guard.kind !== 'fleet-respawn' &&
+        guard.kind !== 'fleet-crew-transfer');
+    const fleetCreationAccounts = new Map();
+    const fleetAssemblyAccounts = new Map();
+    const importFundingAccounts = new Map();
+    const assemblyGames = new Set();
+    const assemblyCatalogs = new Map();
+    const requiredAddresses = new Set(preconditions.map(({ address }) => address));
+    for (const guard of preconditions) {
+        if (guard.kind === 'fleet-dock-funding' && guard.status === 'available') {
+            for (const address of [
+                guard.profile,
+                guard.starbasePlayer,
+                guard.system,
+                guard.game,
+                RENT_ADDRESS,
+            ])
+                requiredAddresses.add(address);
+        }
+        if (guard.kind === 'fleet-docking-policy')
+            requiredAddresses.add(guard.ownership);
+        if (guard.kind === 'local-market-order' && guard.status === 'available') {
+            for (const address of [
+                guard.character,
+                guard.starbasePlayer,
+                ...marketOrderFundingAddresses(guard.profile, allPreconditions),
+            ])
+                requiredAddresses.add(address);
+        }
+        if (guard.kind === 'scan-signal-open') {
+            for (const address of openSignalAddresses(guard))
+                requiredAddresses.add(address);
+        }
+        if (guard.kind !== 'fleet-create')
+            continue;
+        const resolved = await resolveFleetCreation(guard);
+        if (resolved.fleet !== guard.address)
+            throw new ActionPreconditionFailedError(guard, undefined, 'The Fleet address does not match this Game, Profile and exact label. Recreate the Fleet creation Plan from its intended label.');
+        fleetCreationAccounts.set(guard, resolved);
+        for (const address of [
+            resolved.game,
+            resolved.profile,
+            resolved.system,
+            resolved.character,
+            resolved.profileFaction,
+            resolved.starbasePlayer,
+            resolved.fleet,
+            resolved.rent,
+            resolved.clock,
+        ])
+            requiredAddresses.add(address);
+    }
+    for (const guard of preconditions) {
+        if (guard.kind !== 'fleet-add-ship')
+            continue;
+        const resolved = await resolveFleetShipAssembly(guard);
+        fleetAssemblyAccounts.set(guard, resolved);
+        assemblyGames.add(resolved.game);
+        for (const address of [
+            resolved.game,
+            resolved.profile,
+            resolved.system,
+            resolved.character,
+            resolved.profileFaction,
+            resolved.starbasePlayer,
+            resolved.fleet,
+            resolved.rent,
+            resolved.clock,
+        ])
+            requiredAddresses.add(address);
+    }
+    for (const guard of preconditions) {
+        if (guard.kind !== 'ship-import-funding')
+            continue;
+        let resolved;
+        try {
+            resolved = await resolveShipImportFunding(guard);
+        }
+        catch {
+            throw new ActionPreconditionFailedError(guard, undefined, 'The ship import target does not match its Game, Profile and System. Refresh the canonical StarbasePlayer and prepare a new import.');
+        }
+        importFundingAccounts.set(guard, resolved);
+        for (const address of [
+            resolved.profile,
+            resolved.character,
+            resolved.starbasePlayer,
+            resolved.rent,
+        ])
+            requiredAddresses.add(address);
+    }
+    const addresses = [...requiredAddresses];
     const accounts = await readContextRawAccounts(context, addresses, {
         commitment,
     });
     const byAddress = new Map(addresses.map((address, index) => [address, accounts[index]]));
     const cargoIdsByGame = new Map();
     for (const guard of preconditions) {
-        if (guard.kind !== 'game-cargo-config')
+        if (guard.kind !== 'game-cargo-bytes-config')
             continue;
         const ids = cargoIdsByGame.get(guard.address) ?? [];
         ids.push(guard.cargoId);
@@ -319,23 +559,181 @@ async function checkPreconditions(context, preconditions, commitment) {
     // Invocation-local only: every execution attempt still reads and decodes fresh state.
     const cargoHashesByGame = new Map();
     const validatedGames = new Set();
-    for (const precondition of preconditions) {
+    // One exact decode per fresh Game row, shared by every Game guard below.
+    const gameDecodes = new Map();
+    const profileFunding = new Map();
+    const fundedTargets = new Set();
+    const recordFunding = (guard, funding) => {
+        // Repeated guards for one action are assertions, not additional debits.
+        // Every guard still validates its own ceiling before reaching here.
+        const target = `${guard.kind}:${guard.address}`;
+        if (fundedTargets.has(target))
+            return;
+        fundedTargets.add(target);
+        const current = profileFunding.get(guard.profile);
+        profileFunding.set(guard.profile, {
+            debit: (current?.debit ?? 0n) + funding.profileDebit,
+            reserve: funding.profileReserve,
+            guard,
+        });
+    };
+    const fleetFailure = (guard, error) => {
+        // Only SDK diagnostics from this bounded validation batch are exposed.
+        // Never stringify provider/codec objects or retain their inner causes.
+        if (error instanceof SageSdkError &&
+            error.address !== undefined &&
+            requiredAddresses.has(error.address))
+            return new ActionPreconditionFailedError(guard, byAddress.get(error.address)?.slot, error.message, error.address);
+        return new ActionPreconditionFailedError(guard, undefined, 'Fleet prerequisites could not be validated. Refresh the related accounts and replan with a supported binding version.');
+    };
+    // A docking Plan from another deployment is reported as such before any
+    // freshness guard, whatever the saved guard order.
+    for (const precondition of preconditions)
+        if ((precondition.kind === 'fleet-dock-funding' ||
+            precondition.kind === 'fleet-docking-policy') &&
+            precondition.game !== requireGameAddress(context))
+            throw fleetFailure(precondition, new SageSdkError('ACTION_PRECONDITION_FAILED', precondition.kind === 'fleet-dock-funding'
+                ? `The docking Plan belongs to Game ${precondition.game}, but the context uses Game ${requireGameAddress(context)}. Recreate it with the intended Game context.`
+                : 'The docking faction policy belongs to another Game. Recreate the Plan with the intended Game context.', { address: precondition.address }));
+    // Dependent docking estimates run after every other freshness guard, so an
+    // exact account-state or policy diagnostic wins whatever the saved order.
+    const ordered = [
+        ...preconditions.filter((g) => g.kind !== 'fleet-dock-funding'),
+        ...preconditions.filter((g) => g.kind === 'fleet-dock-funding'),
+    ];
+    for (const precondition of ordered) {
         const account = byAddress.get(precondition.address);
+        if (precondition.kind === 'fleet-dock-funding') {
+            try {
+                const funding = revalidateDockFunding(precondition, byAddress, precondition.status === 'available'
+                    ? decodeDockingSequences(byAddress.get(precondition.game), gameDecodes)
+                    : undefined);
+                if (funding)
+                    recordFunding(precondition, funding);
+            }
+            catch (error) {
+                throw fleetFailure(precondition, error);
+            }
+            continue;
+        }
+        if (precondition.kind === 'local-market-order') {
+            try {
+                if (precondition.game !== requireGameAddress(context))
+                    throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'The order belongs to another Game. Recreate it with the intended Game context.');
+                revalidateMarketOrder(precondition, byAddress, allPreconditions);
+            }
+            catch (error) {
+                const failedAddress = error instanceof SageSdkError ? error.address : undefined;
+                throw new ActionPreconditionFailedError(precondition, byAddress.get(failedAddress ?? precondition.address)?.slot, error instanceof SageSdkError
+                    ? error.message
+                    : 'The Local Market debit bounds could not be verified. Refresh its funding accounts and recreate the order Plan.', failedAddress);
+            }
+            continue;
+        }
+        if (precondition.kind === 'scan-signal-open') {
+            if (precondition.game !== requireGameAddress(context))
+                throw new ActionPreconditionFailedError(precondition, undefined, 'This signal setup belongs to a different configured Game. Refetch and recreate the Plan using the intended Game context.');
+            try {
+                recordFunding(precondition, await validateOpenSignal(precondition, byAddress, precondition.authorityHash));
+            }
+            catch (error) {
+                throw fleetFailure(precondition, error);
+            }
+            continue;
+        }
+        if (precondition.kind === 'ship-import-funding') {
+            try {
+                const funding = validateShipImportFunding(precondition, importFundingAccounts.get(precondition), byAddress, precondition.maximumProfileDebit);
+                recordFunding(precondition, funding);
+            }
+            catch (error) {
+                throw fleetFailure(precondition, error);
+            }
+            continue;
+        }
+        if (precondition.kind === 'fleet-add-ship') {
+            try {
+                const game = byAddress.get(precondition.game);
+                let catalog = assemblyCatalogs.get(precondition.game);
+                if (!catalog && game) {
+                    catalog = decodeGameShipAssemblyCatalog(game, gameDecodes);
+                    assemblyCatalogs.set(precondition.game, catalog);
+                }
+                const funding = await validateFleetShipAssembly(precondition, fleetAssemblyAccounts.get(precondition), byAddress, precondition, catalog);
+                recordFunding(precondition, funding);
+            }
+            catch (error) {
+                throw fleetFailure(precondition, error);
+            }
+            continue;
+        }
+        if (precondition.kind === 'fleet-create') {
+            try {
+                const funding = await validateFleetCreation(precondition, fleetCreationAccounts.get(precondition), byAddress, precondition.maximumProfileDebit);
+                recordFunding(precondition, funding);
+            }
+            catch (error) {
+                throw fleetFailure(precondition, error);
+            }
+            continue;
+        }
+        if (precondition.kind === 'fleet-docking-policy') {
+            try {
+                await validateFleetDockingPolicy(account, byAddress.get(precondition.ownership), precondition);
+            }
+            catch (error) {
+                throw fleetFailure(precondition, error);
+            }
+            continue;
+        }
         let narrowed = true;
+        let cause;
         if (precondition.kind === 'token-account')
             narrowed =
                 account !== undefined && matchesTokenAccount(account, precondition);
-        if (precondition.kind === 'game-ship-config' ||
+        if (precondition.kind === 'movement-character' ||
+            precondition.kind === 'starbase-system' ||
+            precondition.kind === 'fleet-mining' ||
+            isFactionTradeGuard(precondition) ||
+            precondition.kind === 'token-mint' ||
+            precondition.kind === 'game-ship-config' ||
             precondition.kind === 'game-account' ||
-            precondition.kind === 'game-cargo-config' ||
+            precondition.kind === 'game-cargo-bytes-config' ||
             precondition.kind === 'cargo-cache') {
             try {
                 if (!account)
                     narrowed = false;
+                else if (precondition.kind === 'movement-character') {
+                    narrowed =
+                        precondition.game === requireGameAddress(context) &&
+                            (await hashMovementCharacter(account, precondition)) ===
+                                precondition.stateHash;
+                }
+                else if (precondition.kind === 'starbase-system') {
+                    narrowed = precondition.game === requireGameAddress(context);
+                    if (narrowed)
+                        await validateStarbaseSystem(account, precondition);
+                }
+                else if (precondition.kind === 'fleet-mining') {
+                    narrowed =
+                        precondition.game === requireGameAddress(context) &&
+                            (await matchesFleetMiningState(account, precondition));
+                }
+                else if (isFactionTradeGuard(precondition)) {
+                    narrowed = await matchesFactionTradeState(account, precondition);
+                }
+                else if (precondition.kind === 'token-mint') {
+                    narrowed = validateTokenMint(account) === precondition.decimals;
+                }
                 else if (precondition.kind === 'game-ship-config') {
                     let hashes = shipHashesByGame.get(precondition.address);
                     if (!hashes) {
-                        hashes = await hashGameShipConfigurations(account, shipIdsByGame.get(precondition.address));
+                        let catalog = assemblyCatalogs.get(precondition.address);
+                        if (!catalog && assemblyGames.has(precondition.address)) {
+                            catalog = decodeGameShipAssemblyCatalog(account, gameDecodes);
+                            assemblyCatalogs.set(precondition.address, catalog);
+                        }
+                        hashes = await hashGameShipConfigurations(account, shipIdsByGame.get(precondition.address), catalog, gameDecodes);
                         shipHashesByGame.set(precondition.address, hashes);
                     }
                     narrowed =
@@ -343,14 +741,20 @@ async function checkPreconditions(context, preconditions, commitment) {
                 }
                 else if (precondition.kind === 'game-account') {
                     if (!validatedGames.has(account.address)) {
-                        validateGameForCharacterRegistration(account);
+                        if (assemblyGames.has(precondition.address)) {
+                            if (!assemblyCatalogs.has(precondition.address))
+                                assemblyCatalogs.set(precondition.address, decodeGameShipAssemblyCatalog(account, gameDecodes));
+                        }
+                        else
+                            validateGameForCharacterRegistration(account, gameDecodes);
                         validatedGames.add(account.address);
                     }
                 }
-                else if (precondition.kind === 'game-cargo-config') {
+                else if (precondition.kind === 'game-cargo-bytes-config') {
                     let hashes = cargoHashesByGame.get(precondition.address);
                     if (!hashes) {
-                        hashes = await hashGameCargoConfigurations(account, cargoIdsByGame.get(precondition.address));
+                        const ids = cargoIdsByGame.get(precondition.address);
+                        hashes = await hashGameCargoConfigurationGuards(account, ids, gameDecodes);
                         cargoHashesByGame.set(precondition.address, hashes);
                     }
                     narrowed =
@@ -369,22 +773,35 @@ async function checkPreconditions(context, preconditions, commitment) {
                         canonical === account.address && bump === precondition.bump;
                 }
             }
-            catch {
+            catch (error) {
                 narrowed = false;
+                cause = guardCause(precondition, error);
             }
         }
         if (!narrowed ||
             (precondition.kind === 'token-account-or-absent' &&
                 account !== undefined &&
                 !matchesTokenAccount(account, precondition)) ||
+            (precondition.kind === 'system-account-or-absent' &&
+                account !== undefined &&
+                (account.owner !== '11111111111111111111111111111111' ||
+                    account.executable ||
+                    account.data.length !== 0)) ||
             (precondition.kind === 'account-absent' && account !== undefined) ||
             (precondition.kind === 'account-state' &&
                 (account === undefined ||
                     (await hashAccountState(account.owner, account.data)) !==
                         precondition.dataHash))) {
-            throw new ActionPreconditionFailedError(precondition, account?.slot);
+            throw new ActionPreconditionFailedError(precondition, account?.slot, cause);
         }
     }
+    for (const [profile, funding] of profileFunding) {
+        // Validation above guarantees a fresh Profile from the same finite batch.
+        const account = byAddress.get(profile);
+        if (account.lamports < funding.reserve + funding.debit)
+            throw new ActionPreconditionFailedError(funding.guard, account.slot, 'The Profile cannot cover the combined Profile storage debits while preserving its rent reserve. Fund the Profile explicitly, then recreate and inspect the Plans.', profile);
+    }
+    return registrationFunding;
 }
 function commitmentReached(actual, requested) {
     if (actual === null)
@@ -611,7 +1028,14 @@ export async function executePlanWithLifecycle(context, plan, options, lifecycle
     const writeRpc = context.writeRpc;
     if (writeRpc === undefined)
         throw new MissingWriteTransportError();
-    await checkPreconditions(context, plan.preconditions, validated.commitment);
+    // Guard order is not trusted: funding follows instruction order, including hydrated Plans.
+    const ordered = [...plan.preconditions].sort((a, b) => {
+        const index = (guard) => guard.kind === 'character-registration'
+            ? plan.steps.findIndex((step) => step.instruction.accounts?.[2]?.address === guard.address)
+            : -1;
+        return index(a) - index(b);
+    });
+    const registrationFunding = await checkPreconditions(context, ordered, plan.steps, validated.commitment);
     const transaction = await assemblePlan(context, plan, {
         feePayer: validated.feePayer.address,
         commitment: validated.commitment,
@@ -622,6 +1046,25 @@ export async function executePlanWithLifecycle(context, plan, options, lifecycle
             ? {}
             : { priorityFeeMicroLamports: validated.priorityFeeMicroLamports }),
     });
+    if (registrationFunding.length > 0) {
+        if (typeof writeRpc.getFeeForMessage !== 'function')
+            throw new SageSdkError('MISSING_WRITE_TRANSPORT', 'The writeRpc transport has no callable getFeeForMessage method, so Character registration cannot check current transaction fees before signing. Update the custom writeRpc transport to implement the required SageWriteRpc getFeeForMessage method, then retry.');
+        const payer = validated.feePayer.address;
+        const { value: fee } = await writeRpc
+            .getFeeForMessage(getBase64Decoder().decode(transaction.messageBytes), { commitment: validated.commitment })
+            .send();
+        if (typeof fee !== 'bigint' || fee < 0n)
+            throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'Current transaction fee could not be determined. Refresh the blockhash and recreate the registration Plan before signing.', { address: payer });
+        if (!registrationFunding.some((funding) => funding.funder === payer)) {
+            const [account, rent] = await readContextRawAccounts(context, [payer, RENT_ADDRESS], { commitment: validated.commitment });
+            if (!account || !isEmptySystemAccount(account) || !rent)
+                throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'Registration fee payer must be an existing empty System wallet with current Rent available. Select and fund it separately.', { address: payer });
+            const remaining = account.lamports - fee;
+            if (remaining < 0n || (remaining > 0n && remaining < readRent(rent)(0)))
+                throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'Registration fee payer cannot pay the current fee and retain zero or a rent-exempt balance. Fund it separately.', { address: payer });
+        }
+        checkRegistrationFunding(registrationFunding, { payer, lamports: fee });
+    }
     await lifecycle?.onPrepared(sendingSigner === undefined ? 'observable' : 'opaque');
     const submission = await signAndSubmit(writeRpc, transaction, signers, sendingSigner, validated.commitment, lifecycle);
     if (submission.status === 'unknown')