@aephia/atlas-kit 0.6.0-next.6 → 0.6.0-next.61

package/dist/planning/index.js

@@ -1,6 +1,18 @@
+import { validateCompletionInstructions, scanCompletionDiscriminators, } from '../internal/planning/scan-completion-guard.js';
+import { validateOpenSignalInstructions } from '../internal/planning/open-signal-guard.js';
+import { validateDetectInstructions, } from '../internal/planning/scan-detect-guard.js';
+import { validateRespawnInstructions } from '../internal/planning/respawn-guards.js';
+import { validateFleetAttackInstructions, } from '../internal/planning/fleet-attack-xp.js';
+import { validateMovementXpInstructions } from '../internal/planning/movement-xp-guard.js';
+import { validateStarbaseSystemInstructions, validateStarbaseSystemGuards, } from '../internal/planning/starbase-system-guard.js';
+import { validateCharacterRegistrationInstructions } from '../internal/planning/character-registration-guard.js';
+import { normalizeArrivalGuard, arrivalGuardToJSON, validateArrivalInstructions, } from '../internal/planning/arrival-guards.js';
+import { isRuntimeGuard, normalizeRuntimeGuard, runtimeGuardToJSON, validateRuntimeInstructions, } from '../internal/planning/runtime-guards.js';
+import { isTradeBuyGuard, isTradeSellGuard, isTradeMeterGuard, isFactionTradeGuard, } from '../internal/planning/faction-trade-guards.js';
 import { AccountRole, getBase64Decoder, getBase64Encoder, isAddress, isWritableRole, } from '@solana/kit';
-import { InvalidActionInputError } from '../client/errors.js';
+import { InvalidActionInputError, SageSdkError } from '../client/errors.js';
 import { deepFreeze } from '../internal/immutable-tree.js';
+import { validateMiningStopInstructions } from '../internal/planning/mining-stop.js';
 import { validatePlanComposition } from './composition.js';
 import { isPlanInstance, registerPlanInstance } from './plan-instances.js';
 const PLAN_BRAND = Symbol('AephiaSagePlan');
@@ -159,10 +171,564 @@ function normalizeSemanticFact(value, field) {
     }
     return invalid(`${field}.kind`, semantic.kind, 'one of exclusive, requires, invalidates, or transition');
 }
-function normalizePrecondition(value, field, version = 4) {
+function normalizePrecondition(value, field) {
     const precondition = readRecord(value, field);
-    if (version === 4 &&
-        ['token-account', 'game-cargo-config', 'cargo-cache'].includes(String(precondition.kind))) {
+    if (precondition.kind === 'fleet-arrival')
+        return normalizeArrivalGuard(precondition, field);
+    if (isRuntimeGuard(precondition))
+        return normalizeRuntimeGuard(precondition, field);
+    if (precondition.kind === 'character-registration') {
+        assertKeys(precondition, field, [
+            'kind',
+            'address',
+            'game',
+            'profile',
+            'profileDataHash',
+            'funder',
+            'xpBudget',
+            'xpBudgetConfig',
+            'maximumFunderDebit',
+            'characterSize',
+            'initializationHash',
+            'characterLamports',
+            'budgetLamports',
+            'describes',
+        ]);
+        if (typeof precondition.characterSize !== 'number' ||
+            !Number.isSafeInteger(precondition.characterSize) ||
+            precondition.characterSize < 423)
+            invalid(`${field}.characterSize`, precondition.characterSize, 'a qualified Character allocation of at least 423 bytes');
+        for (const key of ['characterLamports', 'budgetLamports'])
+            if (typeof precondition[key] !== 'bigint' || precondition[key] < 0n)
+                invalid(`${field}.${key}`, precondition[key], 'a nonnegative bigint');
+        const maximumFunderDebit = precondition.maximumFunderDebit;
+        if (typeof maximumFunderDebit !== 'bigint' || maximumFunderDebit < 0n)
+            invalid(`${field}.maximumFunderDebit`, maximumFunderDebit, 'a nonnegative bigint');
+        return Object.freeze({
+            kind: 'character-registration',
+            address: readAddress(precondition.address, `${field}.address`),
+            game: readAddress(precondition.game, `${field}.game`),
+            profile: readAddress(precondition.profile, `${field}.profile`),
+            profileDataHash: readDataHash(precondition.profileDataHash, `${field}.profileDataHash`),
+            funder: readAddress(precondition.funder, `${field}.funder`),
+            xpBudget: readAddress(precondition.xpBudget, `${field}.xpBudget`),
+            xpBudgetConfig: readAddress(precondition.xpBudgetConfig, `${field}.xpBudgetConfig`),
+            maximumFunderDebit,
+            characterLamports: precondition.characterLamports,
+            budgetLamports: precondition.budgetLamports,
+            characterSize: precondition.characterSize,
+            initializationHash: readDataHash(precondition.initializationHash, `${field}.initializationHash`),
+            describes: readString(precondition.describes, `${field}.describes`),
+        });
+    }
+    if (precondition.kind === 'ship-import-funding') {
+        assertKeys(precondition, field, [
+            'kind',
+            'address',
+            'game',
+            'profile',
+            'system',
+            'shipId',
+            'maximumProfileDebit',
+            'describes',
+        ]);
+        const shipId = precondition.shipId;
+        if (typeof shipId !== 'number' ||
+            !Number.isInteger(shipId) ||
+            shipId < 0 ||
+            shipId > 65535)
+            invalid(`${field}.shipId`, shipId, 'an unsigned u16 ship configuration ID');
+        const maximumProfileDebit = precondition.maximumProfileDebit;
+        if (typeof maximumProfileDebit !== 'bigint' || maximumProfileDebit < 0n)
+            invalid(`${field}.maximumProfileDebit`, maximumProfileDebit, 'a nonnegative bigint');
+        return Object.freeze({
+            kind: 'ship-import-funding',
+            address: readAddress(precondition.address, `${field}.address`),
+            game: readAddress(precondition.game, `${field}.game`),
+            profile: readAddress(precondition.profile, `${field}.profile`),
+            system: readAddress(precondition.system, `${field}.system`),
+            shipId,
+            maximumProfileDebit,
+            describes: readString(precondition.describes, `${field}.describes`),
+        });
+    }
+    if (precondition.kind === 'fleet-attack') {
+        assertKeys(precondition, field, [
+            'kind',
+            'address',
+            'defender',
+            'game',
+            'profile',
+            'defenderProfile',
+            'instructionKey',
+            'describes',
+        ]);
+        return Object.freeze({
+            kind: 'fleet-attack',
+            address: readAddress(precondition.address, `${field}.address`),
+            defender: readAddress(precondition.defender, `${field}.defender`),
+            game: readAddress(precondition.game, `${field}.game`),
+            profile: readAddress(precondition.profile, `${field}.profile`),
+            defenderProfile: readAddress(precondition.defenderProfile, `${field}.defenderProfile`),
+            instructionKey: readString(precondition.instructionKey, `${field}.instructionKey`),
+            describes: readString(precondition.describes, `${field}.describes`),
+        });
+    }
+    if (precondition.kind === 'movement-character') {
+        assertKeys(precondition, field, [
+            'kind',
+            'address',
+            'game',
+            'profile',
+            'stateHash',
+            'describes',
+        ]);
+        return Object.freeze({
+            kind: 'movement-character',
+            address: readAddress(precondition.address, `${field}.address`),
+            game: readAddress(precondition.game, `${field}.game`),
+            profile: readAddress(precondition.profile, `${field}.profile`),
+            stateHash: readDataHash(precondition.stateHash, `${field}.stateHash`),
+            describes: readString(precondition.describes, `${field}.describes`),
+        });
+    }
+    if (precondition.kind === 'starbase-system') {
+        assertKeys(precondition, field, ['kind', 'address', 'game', 'starbaseSequenceId', 'describes'], ['requireCss']);
+        if (precondition.requireCss !== undefined &&
+            precondition.requireCss !== true)
+            invalid(`${field}.requireCss`, precondition.requireCss, 'true when CSS access is required, otherwise omitted');
+        const sequence = precondition.starbaseSequenceId;
+        if (typeof sequence !== 'bigint' ||
+            sequence < 0n ||
+            sequence > 18446744073709551615n)
+            invalid(`${field}.starbaseSequenceId`, sequence, 'an unsigned u64 Starbase sequence');
+        return Object.freeze({
+            kind: 'starbase-system',
+            address: readAddress(precondition.address, `${field}.address`),
+            game: readAddress(precondition.game, `${field}.game`),
+            starbaseSequenceId: sequence,
+            ...(precondition.requireCss === undefined
+                ? {}
+                : { requireCss: true }),
+            describes: readString(precondition.describes, `${field}.describes`),
+        });
+    }
+    if (precondition.kind === 'fleet-mining') {
+        assertKeys(precondition, field, [
+            'kind',
+            'address',
+            'game',
+            'profile',
+            'asteroid',
+            'describes',
+        ]);
+        return Object.freeze({
+            kind: 'fleet-mining',
+            address: readAddress(precondition.address, `${field}.address`),
+            game: readAddress(precondition.game, `${field}.game`),
+            profile: readAddress(precondition.profile, `${field}.profile`),
+            asteroid: readAddress(precondition.asteroid, `${field}.asteroid`),
+            describes: readString(precondition.describes, `${field}.describes`),
+        });
+    }
+    if (isFactionTradeGuard(precondition)) {
+        const kind = precondition.kind;
+        assertKeys(precondition, field, [
+            'kind',
+            'address',
+            'game',
+            'factionId',
+            'describes',
+            'schemaVersion',
+            ...(isTradeBuyGuard(precondition)
+                ? ['cargoId', 'floorRaw']
+                : isTradeSellGuard(precondition)
+                    ? ['atlasOutCapPerEpochRaw', 'epochLengthSeconds']
+                    : []),
+        ]);
+        const unsigned = (key, max = 65535) => {
+            const n = precondition[key];
+            if (typeof n !== 'number' || !Number.isInteger(n) || n < 0 || n > max)
+                invalid(`${field}.${key}`, n, `an unsigned ${max === 255 ? 'u8' : 'u16'} integer`);
+            return n;
+        };
+        const integer = (key, signed = false) => {
+            const n = precondition[key];
+            const min = signed ? -(1n << 63n) : 0n;
+            const max = signed ? (1n << 63n) - 1n : (1n << 64n) - 1n;
+            if (typeof n !== 'bigint' || n < min || n > max)
+                invalid(`${field}.${key}`, n, signed ? 'an i64 bigint' : 'a u64 bigint');
+            return n;
+        };
+        const common = {
+            address: readAddress(precondition.address, `${field}.address`),
+            game: readAddress(precondition.game, `${field}.game`),
+            factionId: unsigned('factionId'),
+            schemaVersion: unsigned('schemaVersion', 255),
+            describes: readString(precondition.describes, `${field}.describes`),
+        };
+        if (isTradeBuyGuard(precondition))
+            return Object.freeze({
+                kind,
+                ...common,
+                cargoId: unsigned('cargoId'),
+                floorRaw: integer('floorRaw'),
+            });
+        if (isTradeSellGuard(precondition))
+            return Object.freeze({
+                kind,
+                ...common,
+                atlasOutCapPerEpochRaw: integer('atlasOutCapPerEpochRaw'),
+                epochLengthSeconds: integer('epochLengthSeconds', true),
+            });
+        return Object.freeze({ kind, ...common });
+    }
+    if (precondition.kind === 'fleet-add-ship') {
+        assertKeys(precondition, field, [
+            'kind',
+            'address',
+            'game',
+            'profile',
+            'authority',
+            'system',
+            'shipId',
+            'amount',
+            'keyIndex',
+            'configHash',
+            'maximumProfileDebit',
+            'describes',
+        ]);
+        const keyIndex = precondition.keyIndex;
+        if (typeof keyIndex !== 'number' ||
+            !Number.isInteger(keyIndex) ||
+            keyIndex < 0 ||
+            keyIndex > 65535)
+            invalid(`${field}.keyIndex`, keyIndex, 'an integer from 0 through 65535');
+        const shipId = precondition.shipId;
+        if (typeof shipId !== 'number' ||
+            !Number.isInteger(shipId) ||
+            shipId < 0 ||
+            shipId > 65535)
+            invalid(`${field}.shipId`, shipId, 'a u16 ship configuration ID');
+        const amount = precondition.amount;
+        if (typeof amount !== 'bigint' || amount < 1n || amount > 255n)
+            invalid(`${field}.amount`, amount, 'a whole ship quantity from 1n through 255n');
+        const maximumProfileDebit = precondition.maximumProfileDebit;
+        if (typeof maximumProfileDebit !== 'bigint' || maximumProfileDebit < 0n)
+            invalid(`${field}.maximumProfileDebit`, maximumProfileDebit, 'a nonnegative bigint');
+        return Object.freeze({
+            kind: 'fleet-add-ship',
+            address: readAddress(precondition.address, `${field}.address`),
+            game: readAddress(precondition.game, `${field}.game`),
+            profile: readAddress(precondition.profile, `${field}.profile`),
+            authority: readAddress(precondition.authority, `${field}.authority`),
+            system: readAddress(precondition.system, `${field}.system`),
+            keyIndex,
+            shipId,
+            amount,
+            maximumProfileDebit,
+            configHash: readDataHash(precondition.configHash, `${field}.configHash`),
+            describes: readString(precondition.describes, `${field}.describes`),
+        });
+    }
+    if (precondition.kind === 'scan-completion') {
+        const addresses = [
+            'address',
+            'game',
+            'signal',
+            'profile',
+            'character',
+            'authority',
+            'policy',
+            'loot',
+            'xpBudget',
+            'xpConfig',
+        ];
+        assertKeys(precondition, field, [
+            'kind',
+            'operation',
+            ...addresses,
+            'keyIndex',
+            'status',
+            'expectedSequence',
+            'configHash',
+            'describes',
+        ]);
+        if (typeof precondition.operation !== 'string' ||
+            !Object.hasOwn(scanCompletionDiscriminators, precondition.operation))
+            invalid(field, precondition.operation, 'a supported scan lifecycle operation');
+        const keyIndex = precondition.keyIndex, status = precondition.status, sequence = precondition.expectedSequence;
+        if (typeof keyIndex !== 'number' ||
+            !Number.isInteger(keyIndex) ||
+            keyIndex < 0 ||
+            keyIndex > 65535)
+            invalid(field, keyIndex, 'a u16 key index');
+        if (typeof status !== 'number' ||
+            !Number.isInteger(status) ||
+            status < 1 ||
+            status > 6)
+            invalid(field, status, 'a current nonempty signal state');
+        if (typeof sequence !== 'bigint' ||
+            sequence < 0n ||
+            sequence > 18446744073709551615n)
+            invalid(field, sequence, 'a u64 sequence');
+        const parsed = Object.fromEntries(addresses.map((k) => [k, readAddress(precondition[k], `${field}.${k}`)]));
+        return Object.freeze({
+            kind: 'scan-completion',
+            operation: precondition.operation,
+            ...parsed,
+            keyIndex,
+            status,
+            expectedSequence: sequence,
+            configHash: readDataHash(precondition.configHash, field),
+            describes: readString(precondition.describes, field),
+        });
+    }
+    if (precondition.kind === 'scan-detect') {
+        assertKeys(precondition, field, [
+            'kind',
+            'address',
+            'game',
+            'profile',
+            'authority',
+            'character',
+            'signal',
+            'pattern',
+            'policy',
+            'loot',
+            'tracker',
+            'keyIndex',
+            'patternId',
+            'focus',
+            'expectedSequence',
+            'policyRevision',
+            'profileRevision',
+            'configHash',
+            'describes',
+        ]);
+        const numbers = {};
+        for (const [key, max] of [
+            ['keyIndex', 65535],
+            ['patternId', 65535],
+            ['focus', 4],
+            ['policyRevision', 4294967295],
+            ['profileRevision', 4294967295],
+        ]) {
+            const value = precondition[key];
+            if (typeof value !== 'number' ||
+                !Number.isInteger(value) ||
+                value < 0 ||
+                value > max)
+                invalid(`${field}.${key}`, value, `an integer from zero through ${max}`);
+            numbers[key] = value;
+        }
+        const sequence = precondition.expectedSequence;
+        if (typeof sequence !== 'bigint' ||
+            sequence < 0n ||
+            sequence > 18446744073709551615n)
+            invalid(`${field}.expectedSequence`, sequence, 'a u64 bigint');
+        return Object.freeze({
+            kind: 'scan-detect',
+            address: readAddress(precondition.address, field),
+            game: readAddress(precondition.game, field),
+            profile: readAddress(precondition.profile, field),
+            authority: readAddress(precondition.authority, field),
+            character: readAddress(precondition.character, field),
+            signal: readAddress(precondition.signal, field),
+            pattern: readAddress(precondition.pattern, field),
+            policy: readAddress(precondition.policy, field),
+            loot: readAddress(precondition.loot, field),
+            tracker: readAddress(precondition.tracker, field),
+            keyIndex: numbers.keyIndex,
+            patternId: numbers.patternId,
+            focus: numbers.focus,
+            policyRevision: numbers.policyRevision,
+            profileRevision: numbers.profileRevision,
+            expectedSequence: sequence,
+            configHash: readDataHash(precondition.configHash, field),
+            describes: readString(precondition.describes, field),
+        });
+    }
+    if (precondition.kind === 'fleet-respawn') {
+        assertKeys(precondition, field, [
+            'kind',
+            'address',
+            'game',
+            'profile',
+            'authority',
+            'system',
+            'keyIndex',
+            'phase',
+            'fleetHash',
+            'maximumRecoveryFee',
+            'maximumProfileDebit',
+            'describes',
+        ]);
+        const keyIndex = precondition.keyIndex;
+        if (typeof keyIndex !== 'number' ||
+            !Number.isInteger(keyIndex) ||
+            keyIndex < 0 ||
+            keyIndex > 65535)
+            invalid(`${field}.keyIndex`, keyIndex, 'a u16 key index');
+        const phase = precondition.phase;
+        if (phase !== 'start' && phase !== 'complete')
+            invalid(`${field}.phase`, phase, 'start or complete');
+        const maximumRecoveryFee = precondition.maximumRecoveryFee, maximumProfileDebit = precondition.maximumProfileDebit;
+        for (const value of [maximumRecoveryFee, maximumProfileDebit])
+            if (typeof value !== 'bigint' || value < 0n || value > (1n << 64n) - 1n)
+                invalid(field, value, 'a nonnegative u64 funding ceiling');
+        return Object.freeze({
+            kind: 'fleet-respawn',
+            address: readAddress(precondition.address, field),
+            game: readAddress(precondition.game, field),
+            profile: readAddress(precondition.profile, field),
+            authority: readAddress(precondition.authority, field),
+            system: readAddress(precondition.system, field),
+            keyIndex,
+            phase,
+            fleetHash: readDataHash(precondition.fleetHash, field),
+            maximumRecoveryFee: maximumRecoveryFee,
+            maximumProfileDebit: maximumProfileDebit,
+            describes: readString(precondition.describes, field),
+        });
+    }
+    if (precondition.kind === 'scan-signal-open') {
+        assertKeys(precondition, field, [
+            'kind',
+            'address',
+            'game',
+            'fleet',
+            'profile',
+            'authority',
+            'character',
+            'keyIndex',
+            'authorityHash',
+            'maximumProfileDebit',
+            'describes',
+        ]);
+        const keyIndex = precondition.keyIndex;
+        if (typeof keyIndex !== 'number' ||
+            !Number.isInteger(keyIndex) ||
+            keyIndex < 0 ||
+            keyIndex > 65535)
+            invalid(field, keyIndex, 'a u16 key index');
+        const maximumProfileDebit = precondition.maximumProfileDebit;
+        if (typeof maximumProfileDebit !== 'bigint' ||
+            maximumProfileDebit < 0n ||
+            maximumProfileDebit > 0xffffffffffffffffn)
+            invalid(field, maximumProfileDebit, 'a nonnegative u64 funding ceiling');
+        return Object.freeze({
+            kind: 'scan-signal-open',
+            authorityHash: readDataHash(precondition.authorityHash, field),
+            address: readAddress(precondition.address, field),
+            game: readAddress(precondition.game, field),
+            fleet: readAddress(precondition.fleet, field),
+            profile: readAddress(precondition.profile, field),
+            authority: readAddress(precondition.authority, field),
+            character: readAddress(precondition.character, field),
+            keyIndex,
+            maximumProfileDebit,
+            describes: readString(precondition.describes, field),
+        });
+    }
+    if (precondition.kind === 'fleet-create') {
+        assertKeys(precondition, field, [
+            'kind',
+            'address',
+            'game',
+            'profile',
+            'authority',
+            'system',
+            'keyIndex',
+            'label',
+            'maximumProfileDebit',
+            'describes',
+        ]);
+        const keyIndex = precondition.keyIndex;
+        if (typeof keyIndex !== 'number' ||
+            !Number.isSafeInteger(keyIndex) ||
+            keyIndex < 0 ||
+            keyIndex > 65_535)
+            invalid(`${field}.keyIndex`, keyIndex, 'an integer from 0 through 65535');
+        const label = readString(precondition.label, `${field}.label`);
+        const bytes = new TextEncoder().encode(label);
+        if (label.trim().length === 0 ||
+            label.includes('\0') ||
+            bytes.length > 64 ||
+            new TextDecoder('utf-8', { ignoreBOM: true }).decode(bytes) !== label)
+            invalid(`${field}.label`, label, 'a nonblank, NUL-free Unicode label of at most 64 UTF-8 bytes');
+        const maximumProfileDebit = precondition.maximumProfileDebit;
+        if (typeof maximumProfileDebit !== 'bigint' || maximumProfileDebit < 0n)
+            invalid(`${field}.maximumProfileDebit`, maximumProfileDebit, 'a nonnegative bigint');
+        return Object.freeze({
+            kind: 'fleet-create',
+            address: readAddress(precondition.address, `${field}.address`),
+            game: readAddress(precondition.game, `${field}.game`),
+            profile: readAddress(precondition.profile, `${field}.profile`),
+            authority: readAddress(precondition.authority, `${field}.authority`),
+            system: readAddress(precondition.system, `${field}.system`),
+            keyIndex,
+            label,
+            maximumProfileDebit,
+            describes: readString(precondition.describes, `${field}.describes`),
+        });
+    }
+    if (precondition.kind === 'system-account-or-absent') {
+        assertKeys(precondition, field, ['kind', 'address', 'describes']);
+        return Object.freeze({
+            kind: 'system-account-or-absent',
+            address: readAddress(precondition.address, `${field}.address`),
+            describes: readString(precondition.describes, `${field}.describes`),
+        });
+    }
+    if (precondition.kind === 'token-mint') {
+        assertKeys(precondition, field, [
+            'kind',
+            'address',
+            'decimals',
+            'describes',
+        ]);
+        const decimals = precondition.decimals;
+        if (typeof decimals !== 'number' ||
+            !Number.isInteger(decimals) ||
+            decimals < 0 ||
+            decimals > 255)
+            invalid(`${field}.decimals`, decimals, 'an unsigned u8 mint decimals value');
+        return Object.freeze({
+            kind: 'token-mint',
+            address: readAddress(precondition.address, `${field}.address`),
+            decimals,
+            describes: readString(precondition.describes, `${field}.describes`),
+        });
+    }
+    if (precondition.kind === 'game-ship-config') {
+        assertKeys(precondition, field, [
+            'kind',
+            'address',
+            'shipId',
+            'configHash',
+            'describes',
+        ]);
+        const id = precondition.shipId;
+        if (typeof id !== 'number' || !Number.isInteger(id) || id < 0 || id > 65535)
+            invalid(`${field}.shipId`, id, 'a u16 ship configuration ID');
+        return Object.freeze({
+            kind: 'game-ship-config',
+            address: readAddress(precondition.address, `${field}.address`),
+            shipId: id,
+            configHash: readDataHash(precondition.configHash, `${field}.configHash`),
+            describes: readString(precondition.describes, `${field}.describes`),
+        });
+    }
+    if (precondition.kind === 'game-account') {
+        assertKeys(precondition, field, ['kind', 'address', 'describes']);
+        return Object.freeze({
+            kind: 'game-account',
+            address: readAddress(precondition.address, `${field}.address`),
+            describes: readString(precondition.describes, `${field}.describes`),
+        });
+    }
+    if (['game-cargo-bytes-config', 'token-account', 'cargo-cache'].includes(String(precondition.kind))) {
         const base = {
             address: readAddress(precondition.address, `${field}.address`),
             describes: readString(precondition.describes, `${field}.describes`),
@@ -189,7 +755,7 @@ function normalizePrecondition(value, field, version = 4) {
                 minimumBalance: amount,
             });
         }
-        if (precondition.kind === 'game-cargo-config') {
+        if (precondition.kind === 'game-cargo-bytes-config') {
             assertKeys(precondition, field, [
                 'kind',
                 'address',
@@ -205,7 +771,7 @@ function normalizePrecondition(value, field, version = 4) {
                 invalid(`${field}.cargoId`, id, 'a u16 cargo ID');
             return Object.freeze({
                 ...base,
-                kind: 'game-cargo-config',
+                kind: precondition.kind,
                 cargoId: id,
                 configHash: readDataHash(precondition.configHash, `${field}.configHash`),
             });
@@ -230,7 +796,7 @@ function normalizePrecondition(value, field, version = 4) {
             bump,
         });
     }
-    if (precondition.kind === 'token-account-or-absent' && version >= 3) {
+    if (precondition.kind === 'token-account-or-absent') {
         assertKeys(precondition, field, [
             'kind',
             'address',
@@ -246,7 +812,7 @@ function normalizePrecondition(value, field, version = 4) {
             describes: readString(precondition.describes, `${field}.describes`),
         });
     }
-    if (precondition.kind === 'account-absent' && version !== 1) {
+    if (precondition.kind === 'account-absent') {
         assertKeys(precondition, field, ['kind', 'address', 'describes']);
         return Object.freeze({
             kind: 'account-absent',
@@ -255,13 +821,7 @@ function normalizePrecondition(value, field, version = 4) {
         });
     }
     if (precondition.kind !== 'account-state') {
-        invalid(`${field}.kind`, precondition.kind, version === 4
-            ? 'one of account-state, account-absent, token-account-or-absent, token-account, game-cargo-config, or cargo-cache'
-            : version === 3
-                ? 'one of account-state, account-absent, or token-account-or-absent'
-                : version === 2
-                    ? 'one of account-state or account-absent'
-                    : 'the value account-state');
+        invalid(`${field}.kind`, precondition.kind, 'a supported current Plan guard; recreate the Plan using the current capability planner');
     }
     assertKeys(precondition, field, ['kind', 'address', 'dataHash', 'describes']);
     return Object.freeze({
@@ -297,64 +857,70 @@ function instructionToJSON(instruction) {
     return deepFreeze(value);
 }
 function planToJSON(plan) {
-    const hasSemantics = plan.steps.some((step) => (step.semantics?.length ?? 0) > 0);
-    const hasAbsentPrecondition = plan.preconditions.some(({ kind }) => kind === 'account-absent');
-    const common = {
+    return deepFreeze({
+        v: 23,
         kind: plan.kind,
         summary: plan.summary,
         affected: [...plan.affected],
         requiredSigners: [...plan.requiredSigners],
-    };
-    const steps = plan.steps.map((step) => ({
-        instruction: instructionToJSON(step.instruction),
-        describes: step.describes,
-        ...((step.semantics?.length ?? 0) > 0
-            ? { semantics: step.semantics.map((semantic) => ({ ...semantic })) }
-            : {}),
-        signers: [...step.signers],
-    }));
-    if (plan.preconditions.some(({ kind }) => kind === 'token-account' ||
-        kind === 'game-cargo-config' ||
-        kind === 'cargo-cache')) {
-        return deepFreeze({
-            v: 4,
-            ...common,
-            steps,
-            preconditions: plan.preconditions.map((guard) => guard.kind === 'token-account'
-                ? { ...guard, minimumBalance: String(guard.minimumBalance) }
-                : { ...guard }),
-        });
-    }
-    if (plan.preconditions.some(({ kind }) => kind === 'token-account-or-absent')) {
-        return deepFreeze({
-            v: 3,
-            ...common,
-            steps,
-            preconditions: plan.preconditions.map((guard) => ({
-                ...guard,
-            })),
-        });
-    }
-    if (hasSemantics || hasAbsentPrecondition) {
-        return deepFreeze({
-            v: 2,
-            ...common,
-            steps,
-            preconditions: plan.preconditions.map((guard) => ({
-                ...guard,
-            })),
-        });
-    }
-    return deepFreeze({
-        v: 1,
-        ...common,
-        steps,
-        preconditions: plan.preconditions.map((precondition) => ({
-            kind: 'account-state',
-            address: precondition.address,
-            dataHash: precondition.dataHash,
-            describes: precondition.describes,
+        steps: plan.steps.map((step) => ({
+            instruction: instructionToJSON(step.instruction),
+            describes: step.describes,
+            ...((step.semantics?.length ?? 0) > 0
+                ? { semantics: step.semantics.map((semantic) => ({ ...semantic })) }
+                : {}),
+            signers: [...step.signers],
         })),
+        preconditions: plan.preconditions.map((guard) => {
+            if (guard.kind === 'scan-detect' || guard.kind === 'scan-completion')
+                return { ...guard, expectedSequence: String(guard.expectedSequence) };
+            if (guard.kind === 'fleet-arrival')
+                return arrivalGuardToJSON(guard);
+            if (guard.kind === 'fleet-respawn')
+                return {
+                    ...guard,
+                    maximumRecoveryFee: String(guard.maximumRecoveryFee),
+                    maximumProfileDebit: String(guard.maximumProfileDebit),
+                };
+            if (isRuntimeGuard(guard))
+                return runtimeGuardToJSON(guard);
+            if (isTradeBuyGuard(guard))
+                return { ...guard, floorRaw: String(guard.floorRaw) };
+            if (isTradeSellGuard(guard))
+                return {
+                    ...guard,
+                    atlasOutCapPerEpochRaw: String(guard.atlasOutCapPerEpochRaw),
+                    epochLengthSeconds: String(guard.epochLengthSeconds),
+                };
+            if (guard.kind === 'fleet-add-ship')
+                return {
+                    ...guard,
+                    amount: String(guard.amount),
+                    maximumProfileDebit: String(guard.maximumProfileDebit),
+                };
+            if (guard.kind === 'character-registration')
+                return {
+                    ...guard,
+                    maximumFunderDebit: String(guard.maximumFunderDebit),
+                    characterLamports: String(guard.characterLamports),
+                    budgetLamports: String(guard.budgetLamports),
+                };
+            if (guard.kind === 'scan-signal-open' ||
+                guard.kind === 'fleet-create' ||
+                guard.kind === 'ship-import-funding')
+                return {
+                    ...guard,
+                    maximumProfileDebit: String(guard.maximumProfileDebit),
+                };
+            if (guard.kind === 'starbase-system')
+                return {
+                    ...guard,
+                    starbaseSequenceId: String(guard.starbaseSequenceId),
+                };
+            if (guard.kind === 'token-account')
+                return { ...guard, minimumBalance: String(guard.minimumBalance) };
+            return { ...guard };
+        }),
     });
 }
 /** Creates an inert branded Plan while deriving every aggregate field.
@@ -376,6 +942,12 @@ export function createPlan(input) {
     assertKeys(value, 'plan', ['kind', 'summary', 'steps', 'preconditions']);
     const steps = Object.freeze(readArray(value.steps, 'plan.steps').map((step, index) => normalizeStep(step, `plan.steps[${String(index)}]`)));
     const preconditions = Object.freeze(readArray(value.preconditions, 'plan.preconditions').map((precondition, index) => normalizePrecondition(precondition, `plan.preconditions[${String(index)}]`)));
+    validateShipImportFundingComposition(preconditions);
+    validateStarbaseSystemGuards(steps, preconditions);
+    validateDetectInstructions(steps, preconditions);
+    validateCompletionInstructions(steps, preconditions);
+    validateRespawnInstructions(steps, preconditions);
+    validateOpenSignalInstructions(steps, preconditions);
     const descriptions = Object.freeze(steps.map((step) => step.describes));
     const plan = {
         kind: readString(value.kind, 'plan.kind'),
@@ -422,7 +994,7 @@ function sameAddresses(actual, encoded) {
  *
  * @example
  * ```ts
- * declare const wire: PlanJsonV1 | PlanJsonV2 | PlanJsonV3 | PlanJsonV4;
+ * declare const wire: PlanJson;
  * const plan = planFromJSON(wire);
  * console.log(plan.describe());
  * ```
@@ -438,29 +1010,106 @@ export function planFromJSON(json) {
         'affected',
         'requiredSigners',
     ]);
-    if (value.v !== 1 && value.v !== 2 && value.v !== 3 && value.v !== 4) {
-        invalid('planJson.v', value.v, 'the Plan wire version 1, 2, 3, or 4');
-    }
-    const version = value.v;
-    if (version === 4 && Array.isArray(value.preconditions)) {
-        value.preconditions = value.preconditions.map((entry) => {
-            const guard = readRecord(entry, 'precondition');
-            if (guard.kind !== 'token-account')
-                return guard;
-            if (typeof guard.minimumBalance !== 'string' ||
-                !/^(0|[1-9][0-9]*)$/.test(guard.minimumBalance))
-                invalid('minimumBalance', guard.minimumBalance, 'a canonical unsigned decimal string');
-            return { ...guard, minimumBalance: BigInt(guard.minimumBalance) };
-        });
+    if (value.v !== 23) {
+        throw new InvalidActionInputError('planJson.v', value.v, 'the current Plan wire version 23', 'Recreate the Plan using the current capability planner; do not change its saved version or migrate its guards.');
     }
+    value.preconditions = readArray(value.preconditions, 'planJson.preconditions').map((entry) => {
+        const guard = readRecord(entry, 'precondition');
+        if (guard.kind === 'scan-detect' || guard.kind === 'scan-completion') {
+            if (typeof guard.expectedSequence !== 'string' ||
+                !/^(0|[1-9][0-9]*)$/.test(guard.expectedSequence))
+                invalid('expectedSequence', guard.expectedSequence, 'a canonical unsigned decimal string');
+            return { ...guard, expectedSequence: BigInt(guard.expectedSequence) };
+        }
+        if (guard.kind === 'fleet-arrival')
+            return normalizeArrivalGuard(guard, 'precondition', true);
+        if (isRuntimeGuard(guard))
+            return normalizeRuntimeGuard(guard, 'precondition', true);
+        if (isTradeBuyGuard(guard) || isTradeSellGuard(guard)) {
+            const keys = isTradeBuyGuard(guard)
+                ? ['floorRaw']
+                : ['atlasOutCapPerEpochRaw', 'epochLengthSeconds'];
+            const decoded = { ...guard };
+            for (const key of keys) {
+                const raw = guard[key];
+                const pattern = key === 'epochLengthSeconds'
+                    ? /^(0|[1-9][0-9]*|-[1-9][0-9]*)$/
+                    : /^(0|[1-9][0-9]*)$/;
+                if (typeof raw !== 'string' || !pattern.test(raw))
+                    invalid(key, raw, 'a canonical decimal string');
+                decoded[key] = BigInt(raw);
+            }
+            return decoded;
+        }
+        if (guard.kind === 'fleet-add-ship') {
+            for (const field of ['amount', 'maximumProfileDebit'])
+                if (typeof guard[field] !== 'string' ||
+                    !/^(0|[1-9][0-9]*)$/.test(guard[field]))
+                    invalid(field, guard[field], 'a canonical unsigned decimal string');
+            return {
+                ...guard,
+                amount: BigInt(guard.amount),
+                maximumProfileDebit: BigInt(guard.maximumProfileDebit),
+            };
+        }
+        if (guard.kind === 'character-registration') {
+            for (const key of ['characterLamports', 'budgetLamports'])
+                if (typeof guard[key] !== 'string' ||
+                    !/^(0|[1-9][0-9]*)$/.test(guard[key]))
+                    invalid(key, guard[key], 'a canonical unsigned decimal string');
+            if (typeof guard.maximumFunderDebit !== 'string' ||
+                !/^(0|[1-9][0-9]*)$/.test(guard.maximumFunderDebit))
+                invalid('maximumFunderDebit', guard.maximumFunderDebit, 'a canonical unsigned decimal string');
+            return {
+                ...guard,
+                maximumFunderDebit: BigInt(guard.maximumFunderDebit),
+                characterLamports: BigInt(guard.characterLamports),
+                budgetLamports: BigInt(guard.budgetLamports),
+            };
+        }
+        if (guard.kind === 'fleet-respawn') {
+            for (const key of ['maximumRecoveryFee', 'maximumProfileDebit'])
+                if (typeof guard[key] !== 'string' ||
+                    !/^(0|[1-9][0-9]*)$/.test(guard[key]))
+                    invalid(key, guard[key], 'a canonical unsigned decimal string');
+            return {
+                ...guard,
+                maximumRecoveryFee: BigInt(guard.maximumRecoveryFee),
+                maximumProfileDebit: BigInt(guard.maximumProfileDebit),
+            };
+        }
+        if (guard.kind === 'scan-signal-open' ||
+            guard.kind === 'fleet-create' ||
+            guard.kind === 'ship-import-funding') {
+            if (typeof guard.maximumProfileDebit !== 'string' ||
+                !/^(0|[1-9][0-9]*)$/.test(guard.maximumProfileDebit))
+                invalid('maximumProfileDebit', guard.maximumProfileDebit, 'a canonical unsigned decimal string');
+            return {
+                ...guard,
+                maximumProfileDebit: BigInt(guard.maximumProfileDebit),
+            };
+        }
+        if (guard.kind === 'starbase-system') {
+            if (typeof guard.starbaseSequenceId !== 'string' ||
+                !/^(0|[1-9][0-9]*)$/.test(guard.starbaseSequenceId))
+                invalid('starbaseSequenceId', guard.starbaseSequenceId, 'a canonical unsigned decimal string');
+            return { ...guard, starbaseSequenceId: BigInt(guard.starbaseSequenceId) };
+        }
+        if (guard.kind !== 'token-account')
+            return guard;
+        if (typeof guard.minimumBalance !== 'string' ||
+            !/^(0|[1-9][0-9]*)$/.test(guard.minimumBalance))
+            invalid('minimumBalance', guard.minimumBalance, 'a canonical unsigned decimal string');
+        return { ...guard, minimumBalance: BigInt(guard.minimumBalance) };
+    });
     const steps = readArray(value.steps, 'planJson.steps').map((candidate, index) => {
         const field = `planJson.steps[${String(index)}]`;
         const step = readRecord(candidate, field);
-        assertKeys(step, field, ['instruction', 'describes', 'signers'], version !== 1 ? ['semantics'] : []);
+        assertKeys(step, field, ['instruction', 'describes', 'signers'], ['semantics']);
         return {
             instruction: readWireInstruction(step.instruction, `${field}.instruction`),
             describes: readString(step.describes, `${field}.describes`),
-            ...(version !== 1 && step.semantics !== undefined
+            ...(step.semantics !== undefined
                 ? {
                     semantics: readArray(step.semantics, `${field}.semantics`).map((semantic, semanticIndex) => normalizeSemanticFact(semantic, `${field}.semantics[${String(semanticIndex)}]`)),
                 }
@@ -468,7 +1117,7 @@ export function planFromJSON(json) {
             signers: readArray(step.signers, `${field}.signers`).map((signer, signerIndex) => readAddress(signer, `${field}.signers[${String(signerIndex)}]`)),
         };
     });
-    const preconditions = readArray(value.preconditions, 'planJson.preconditions').map((candidate, index) => normalizePrecondition(candidate, `planJson.preconditions[${String(index)}]`, version));
+    const preconditions = readArray(value.preconditions, 'planJson.preconditions').map((candidate, index) => normalizePrecondition(candidate, `planJson.preconditions[${String(index)}]`));
     const affected = readArray(value.affected, 'planJson.affected').map((candidate, index) => readAddress(candidate, `planJson.affected[${String(index)}]`));
     const requiredSigners = readArray(value.requiredSigners, 'planJson.requiredSigners').map((candidate, index) => readAddress(candidate, `planJson.requiredSigners[${String(index)}]`));
     const plan = createPlan({
@@ -477,6 +1126,10 @@ export function planFromJSON(json) {
         steps,
         preconditions,
     });
+    validateStarbaseSystemInstructions(plan.steps, plan.preconditions);
+    validateMovementXpInstructions(plan.steps, plan.preconditions);
+    validateFleetAttackInstructions(plan.steps, plan.preconditions);
+    validateCharacterRegistrationInstructions(plan.steps, plan.preconditions);
     if (!sameAddresses(plan.affected, affected)) {
         invalid('planJson.affected', value.affected, 'the first-seen union of writable instruction account addresses');
     }
@@ -493,6 +1146,49 @@ function assertPlan(value, index) {
 function combinedSummary(steps) {
     return steps.map((step) => step.describes).join(' ');
 }
+function validateShipImportFundingComposition(guards) {
+    const targets = new Map();
+    for (const guard of guards) {
+        if (guard.kind !== 'ship-import-funding')
+            continue;
+        const identity = `${guard.game}:${guard.profile}:${guard.system}:${String(guard.shipId)}`;
+        const previous = targets.get(guard.address);
+        if (previous !== undefined && previous !== identity)
+            throw new SageSdkError('INCOMPATIBLE_PLAN_COMPOSITION', 'Ship imports retain conflicting identities or different configurations for one StarbasePlayer. Use separate confirmed imports, then refresh inventory and replan; prefunding cannot be shared across independently estimated storage growth.');
+        targets.set(guard.address, identity);
+    }
+}
+function validateFactionGuardComposition(guards) {
+    const retained = new Map();
+    for (const guard of guards) {
+        if (!isFactionTradeGuard(guard))
+            continue;
+        const constraints = [
+            [
+                `${isTradeMeterGuard(guard) ? 'meter' : 'treasury'}:${guard.address}:identity`,
+                `${guard.game}:${String(guard.factionId)}`,
+            ],
+        ];
+        if (!isTradeMeterGuard(guard)) {
+            constraints.push(isTradeBuyGuard(guard)
+                ? [
+                    `${guard.address}:buy:${String(guard.cargoId)}`,
+                    String(guard.floorRaw),
+                ]
+                : [
+                    `${guard.address}:sell`,
+                    `${String(guard.atlasOutCapPerEpochRaw)}:${String(guard.epochLengthSeconds)}`,
+                ]);
+        }
+        constraints.push([`${guard.address}:schema`, String(guard.schemaVersion)]);
+        for (const [key, value] of constraints) {
+            const previous = retained.get(key);
+            if (previous !== undefined && previous !== value)
+                throw new SageSdkError('INCOMPATIBLE_PLAN_COMPOSITION', 'Faction Market Plans retain incompatible Treasury policy or shared account identity. Refresh the affected Markets and prepare compatible Plans, or use separate confirmed transactions.');
+            retained.set(key, value);
+        }
+    }
+}
 /** Combines one or more Plans with deterministic associative flattening.
  *
  * Semantic validation is eager. Conflict indices are relative to the flattened
@@ -513,11 +1209,24 @@ export function combinePlans(...plans) {
     plans.forEach(assertPlan);
     const steps = plans.flatMap((plan) => plan.steps);
     validatePlanComposition(steps);
+    const preconditions = plans.flatMap((plan) => plan.preconditions);
+    validateFactionGuardComposition(preconditions);
+    validateMiningStopInstructions(steps, preconditions);
+    validateStarbaseSystemInstructions(steps, preconditions);
+    validateCharacterRegistrationInstructions(steps, preconditions);
+    validateArrivalInstructions(steps, preconditions);
+    validateDetectInstructions(steps, preconditions);
+    validateCompletionInstructions(steps, preconditions);
+    validateRespawnInstructions(steps, preconditions);
+    validateOpenSignalInstructions(steps, preconditions);
+    validateRuntimeInstructions(steps, preconditions);
+    validateMovementXpInstructions(steps, preconditions);
+    validateFleetAttackInstructions(steps, preconditions);
     return createPlan({
         kind: 'combined',
         summary: combinedSummary(steps),
         steps,
-        preconditions: plans.flatMap((plan) => plan.preconditions),
+        preconditions,
     });
 }
 export { assemblePlan } from './assembly.js';