@aephia/atlas-kit 0.6.0-next.13 → 0.6.0-next.130

package/dist/planning/execution.js

@@ -1,12 +1,44 @@
-import { hashGameShipConfigurations } from '../registry/ships.js';
+import { validateCurrencyCache } from '../internal/c4/currency-cache.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 { resolveResearchUnlock, validateResearchUnlock, } from '../internal/planning/research-unlock.js';
+import { CLOCK_ADDRESS } from '../internal/planning/faction-enrollment.js';
+import { decodeGameResearchUnlockRules } from '../internal/c4/game.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 { deriveCargoDefinitionsCacheAddress } from '../internal/c4/pda.js';
+import { getBase58Decoder, getBase64EncodedWireTransaction, getSignatureFromTransaction, isAddress, isTransactionModifyingSigner, isTransactionPartialSigner, isTransactionSendingSigner, signAndSendTransactionWithSigners, signTransactionWithSigners, } from '@solana/kit';
 import { InvalidActionInputError, SageSdkError } from '../client/errors.js';
 import { invalidateContextAddresses, readContextRawAccounts, } from '../client/reconciliation.js';
-import { assemblePlan, validateAssemblyPolicy, validatePlanAssemblyPolicy, validatePlan, } from './assembly.js';
+import { assembleValidatedPlanWithContext, requireWriteRpc, validateAssemblyPolicy, validatePlanAssemblyPolicy, validatePlan, } from './assembly.js';
+import { hashRecipeConfiguration, validateRecipeUsage, } from '../internal/planning/recipe-state.js';
+import { originalTokenBalance } from '../internal/planning/original-token.js';
 const DEFAULT_TIMEOUT_MS = 60_000;
 const DEFAULT_POLL_INTERVAL_MS = 500;
 const MAX_HOST_TIMER_MS = 2_147_483_647;
@@ -28,20 +60,26 @@ class SignerMismatchError extends InvalidActionInputError {
         this.unexpected = unexpected;
     }
 }
-class MissingWriteTransportError extends SageSdkError {
-    constructor() {
-        super('MISSING_WRITE_TRANSPORT', 'This SAGE context has no writeRpc transport, so it cannot execute a Plan. Pass the optional writeRpc transport when creating the context, then retry.');
-    }
-}
-class ActionPreconditionFailedError extends SageSdkError {
+export 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;
@@ -267,41 +305,239 @@ function assertPlanTransactionMessage(expected, actual) {
         invalid('signers', 'modified compiled transaction message', 'signers that preserve the assembled fee payer, instructions, programs, and account roles while optionally replacing only the transaction lifetime', 'Use a signer that signs the assembled Plan without changing its message, or reassemble a new Plan for the intended transaction before retrying.');
     }
 }
-function readFinalLastValidBlockHeight(transaction) {
-    if (!('lastValidBlockHeight' in transaction.lifetimeConstraint))
-        return null;
-    const value = transaction.lifetimeConstraint.lastValidBlockHeight;
-    if (typeof value !== 'bigint' || value < 0n || value > MAX_U64) {
-        invalid('signers', 'invalid final lastValidBlockHeight metadata', 'a final transaction lifetime with lastValidBlockHeight encoded as an unsigned 64-bit bigint', 'Use a signer that returns trustworthy blockhash lifetime metadata, or use an opaque sending signer whose lifetime cannot produce a definite-expiry claim.');
-    }
-    return value;
-}
-// Original Token Account layout: mint/authority at 0/32, initialized state at
-// 108, and u32 COption tags at 72/109/129. No capability decoder is imported.
+/** Whether the account still is the guarded original Token account, with at
+ * least the guarded balance for a `token-account` guard. */
 function matchesTokenAccount(account, expected) {
-    if (account.executable ||
-        account.owner !== 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' ||
-        account.data.length !== 165)
-        return false;
-    const bytes = new DataView(account.data.buffer, account.data.byteOffset, account.data.byteLength);
-    if ((expected.kind === 'token-account' &&
-        bytes.getBigUint64(64, true) < expected.minimumBalance) ||
-        bytes.getUint8(108) !== 1 ||
-        [72, 109, 129].some((offset) => bytes.getUint32(offset, true) > 1))
-        return false;
-    const decoder = getAddressDecoder();
-    return (decoder.decode(account.data.subarray(0, 32)) === expected.mint &&
-        decoder.decode(account.data.subarray(32, 64)) === expected.owner);
+    const balance = originalTokenBalance(account, expected.mint, expected.owner);
+    return (typeof balance === 'bigint' &&
+        (expected.kind !== 'token-account' || balance >= expected.minimumBalance));
 }
-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 !== 'research-unlock')
+            continue;
+        for (const address of [
+            guard.game,
+            guard.profile,
+            guard.system,
+            guard.starbasePlayer,
+            guard.currencyCache,
+            CLOCK_ADDRESS,
+        ])
+            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 +555,215 @@ 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 === 'research-unlock') {
+            try {
+                const game = byAddress.get(precondition.game);
+                if (precondition.game !== requireGameAddress(context) || !game)
+                    throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'The research unlock belongs to another or missing Game. Recreate it with the intended Game context.', { address: precondition.game });
+                const resolved = await resolveResearchUnlock(precondition);
+                if (resolved.character !== precondition.address ||
+                    resolved.starbasePlayer !== precondition.starbasePlayer ||
+                    resolved.currencyCache !== precondition.currencyCache)
+                    throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'The research unlock accounts are not canonical for this Game, Profile and System. Recreate the Plan with planUnlockResearchNode.');
+                await validateResearchUnlock(precondition, resolved, byAddress, decodeGameResearchUnlockRules(game, gameDecodes));
+            }
+            catch (error) {
+                const failed = error instanceof SageSdkError ? error.address : undefined;
+                throw new ActionPreconditionFailedError(precondition, byAddress.get(failed ?? precondition.address)?.slot, error instanceof SageSdkError
+                    ? error.message
+                    : 'Research prerequisites could not be validated. Refresh the Character, Starbase Player and Game definitions, then recreate the unlock Plan.', failed);
+            }
+            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 === 'currency-cache' ||
+            precondition.kind === 'movement-character' ||
+            precondition.kind === 'starbase-system' ||
+            precondition.kind === 'fleet-mining' ||
+            isFactionTradeGuard(precondition) ||
+            precondition.kind === 'recipe-state' ||
+            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 === 'currency-cache') {
+                    narrowed = precondition.game === requireGameAddress(context);
+                    if (narrowed)
+                        await validateCurrencyCache(account, precondition.game);
+                }
+                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 === 'recipe-state') {
+                    narrowed =
+                        (await hashRecipeConfiguration(account)) ===
+                            precondition.configHash;
+                    if (narrowed)
+                        validateRecipeUsage(account, precondition.requiredUses);
+                }
+                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 +771,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 =
@@ -358,35 +792,43 @@ async function checkPreconditions(context, preconditions, commitment) {
                 }
                 else {
                     validateWalletCargoCache(account, precondition.game, precondition.bump);
-                    const [canonical, bump] = await getProgramDerivedAddress({
-                        programAddress: account.owner,
-                        seeds: [
-                            new TextEncoder().encode('CargoDefinitionsCache'),
-                            getAddressEncoder().encode(precondition.game),
-                        ],
-                    });
+                    // validateWalletCargoCache requires the SAGE owner.
+                    const [canonical, bump] = await deriveCargoDefinitionsCacheAddress(precondition.game);
                     narrowed =
                         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) {
+export function commitmentReached(actual, requested) {
     if (actual === null)
         return false;
     const strength = {
@@ -511,7 +953,9 @@ async function confirmTransaction(writeRpc, signature, lastValidBlockHeight, opt
         }
     }
 }
-async function signAndSubmit(writeRpc, transaction, signers, sendingSigner, commitment, lifecycle) {
+async function signAndSubmit(writeRpc, transaction, contextSlot, signers, sendingSigner, commitment, lifecycle) {
+    // Capture RPC metadata before handing the transaction to any signer.
+    const { blockhash, lastValidBlockHeight: assembledHeight } = transaction.lifetimeConstraint;
     await lifecycle?.onBeforeSign();
     if (sendingSigner !== undefined) {
         let enteredOpaqueSender = false;
@@ -520,7 +964,6 @@ async function signAndSubmit(writeRpc, transaction, signers, sendingSigner, comm
             async signAndSendTransactions(transactions, config) {
                 for (const signed of transactions) {
                     assertPlanTransactionMessage(transaction, signed);
-                    readFinalLastValidBlockHeight(signed);
                 }
                 await lifecycle?.onBeforeOpaqueInvoke();
                 enteredOpaqueSender = true;
@@ -546,8 +989,13 @@ async function signAndSubmit(writeRpc, transaction, signers, sendingSigner, comm
     const signed = await signTransactionWithSigners(signingSigners, transaction);
     assertPlanTransactionMessage(transaction, signed);
     const signature = getSignatureFromTransaction(signed);
-    const lastValidBlockHeight = readFinalLastValidBlockHeight(signed);
-    await lifecycle?.onSigned(signature);
+    const lastValidBlockHeight = 'blockhash' in signed.lifetimeConstraint &&
+        signed.lifetimeConstraint.blockhash === blockhash
+        ? assembledHeight
+        : null;
+    await lifecycle?.onSigned(signature, lastValidBlockHeight === null
+        ? null
+        : Object.freeze({ lastValidBlockHeight, contextSlot }));
     await lifecycle?.onBeforeSubmit();
     try {
         const submittedSignature = await writeRpc
@@ -608,22 +1056,42 @@ export async function executePlanWithLifecycle(context, plan, options, lifecycle
     validatePlanAssemblyPolicy(plan, validated);
     const signers = matchSigners(plan, validated);
     const sendingSigner = resolveSendingSigner(signers);
-    const writeRpc = context.writeRpc;
-    if (writeRpc === undefined)
-        throw new MissingWriteTransportError();
-    await checkPreconditions(context, plan.preconditions, validated.commitment);
-    const transaction = await assemblePlan(context, plan, {
+    const writeRpc = requireWriteRpc(context, 'execute');
+    // 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, contextSlot } = await assembleValidatedPlanWithContext(writeRpc, plan, {
         feePayer: validated.feePayer.address,
         commitment: validated.commitment,
-        ...(validated.computeUnitLimit === undefined
-            ? {}
-            : { computeUnitLimit: validated.computeUnitLimit }),
-        ...(validated.priorityFeeMicroLamports === undefined
-            ? {}
-            : { priorityFeeMicroLamports: validated.priorityFeeMicroLamports }),
+        computeUnitLimit: validated.computeUnitLimit,
+        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);
+    const submission = await signAndSubmit(writeRpc, transaction, contextSlot, signers, sendingSigner, validated.commitment, lifecycle);
     if (submission.status === 'unknown')
         return submission;
     const result = await confirmTransaction(writeRpc, submission.signature, submission.lastValidBlockHeight, validated);