@aephia/atlas-kit 0.6.0-next.11 → 0.6.0-next.110

package/dist/internal/planning/starbase-system-guard.js

@@ -0,0 +1,93 @@
+import { AccountRole } from '@solana/kit';
+import { SageSdkError } from '../../client/errors.js';
+import { DEPOSIT_CARGO_TO_GAME_DISCRIMINATOR, WITHDRAW_CARGO_FROM_GAME_DISCRIMINATOR, ADD_SHIP_ESCROW_DISCRIMINATOR, getDepositCargoToGameInstructionDataDecoder, getWithdrawCargoFromGameInstructionDataDecoder, getAddShipEscrowInstructionDataDecoder, CANCEL_CRAFTING_PROCESS_DISCRIMINATOR, getCancelCraftingProcessInstructionDataDecoder, SAGE_PROGRAM_ADDRESS, } from '../c4/runtime-bindings.js';
+// Pure instruction metadata keeps the Plan factory independent of generated data decoders.
+function routeFor(instruction) {
+    if (instruction.programAddress !== SAGE_PROGRAM_ADDRESS)
+        return undefined;
+    const routes = [
+        {
+            discriminator: CANCEL_CRAFTING_PROCESS_DISCRIMINATOR,
+            decoder: 0,
+            count: 11,
+            game: 5,
+            system: 6,
+            css: false,
+            planner: 'planCancelCraftingProcess',
+        },
+        {
+            discriminator: DEPOSIT_CARGO_TO_GAME_DISCRIMINATOR,
+            decoder: 1,
+            count: 13,
+            game: 8,
+            system: 4,
+            css: true,
+            planner: 'planDepositCargoToGame',
+        },
+        {
+            discriminator: WITHDRAW_CARGO_FROM_GAME_DISCRIMINATOR,
+            decoder: 2,
+            count: 11,
+            game: 6,
+            system: 4,
+            css: false,
+            planner: 'planWithdrawCargoFromGame',
+        },
+        {
+            discriminator: ADD_SHIP_ESCROW_DISCRIMINATOR,
+            decoder: 3,
+            count: 14,
+            game: 11,
+            system: 7,
+            css: true,
+            planner: 'planDepositShipsToGame',
+        },
+    ];
+    return routes.find(({ discriminator }) => discriminator.every((byte, index) => instruction.data?.[index] === byte));
+}
+function fail(planner) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', `This Starbase action has an unsupported instruction layout or lacks its matching finite Starbase System safeguard. Recreate it with ${planner}; an exact account hash does not replace this safeguard.`);
+}
+/** Binds required guards to actual instruction accounts without pulling byte decoders into every action entry. */
+export function validateStarbaseSystemGuards(steps, preconditions) {
+    for (const { instruction } of steps) {
+        const route = routeFor(instruction);
+        if (!route)
+            continue;
+        const accounts = instruction.accounts;
+        if (accounts?.length !== route.count ||
+            accounts[route.game].role !== AccountRole.READONLY ||
+            accounts[route.system].role !== AccountRole.READONLY ||
+            !preconditions.some((guard) => guard.kind === 'starbase-system' &&
+                guard.address === accounts[route.system].address &&
+                guard.game === accounts[route.game].address &&
+                (!route.css || guard.requireCss === true)))
+            fail(route.planner);
+    }
+}
+/** Hydration and assembly additionally verify exact bytes with the pinned generated decoders. */
+export function validateStarbaseSystemInstructions(steps, preconditions) {
+    validateStarbaseSystemGuards(steps, preconditions);
+    const decoders = [
+        getCancelCraftingProcessInstructionDataDecoder,
+        getDepositCargoToGameInstructionDataDecoder,
+        getWithdrawCargoFromGameInstructionDataDecoder,
+        getAddShipEscrowInstructionDataDecoder,
+    ];
+    for (const { instruction } of steps) {
+        const route = routeFor(instruction);
+        if (!route)
+            continue;
+        let exactData = false;
+        try {
+            const [, size] = decoders[route.decoder]().read(instruction.data, 0);
+            exactData = size === instruction.data.length;
+        }
+        catch {
+            // Truncated instruction arguments are not a supported route.
+        }
+        if (!exactData)
+            fail(route.planner);
+    }
+}
+//# sourceMappingURL=starbase-system-guard.js.map

package/dist/internal/planning/starbase-system-guard.js.map

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

package/dist/internal/planning/starbase-system.d.ts

@@ -0,0 +1,15 @@
+import type { Address } from '@solana/kit';
+import type { RawAccount } from '../../client/contracts.js';
+type StarbaseSystemIntent = {
+    readonly address: Address;
+    readonly game: Address;
+    readonly starbaseSequenceId: bigint;
+    readonly requireCss?: boolean;
+};
+/** Checks finite System/Starbase identity and the action's station policy.
+ * `staleStarbaseGuidance` lets a planner add action-specific advice for a
+ * replaced Starbase; execution and other actions use the neutral default.
+ */
+export declare function validateStarbaseSystem(account: RawAccount, intent: StarbaseSystemIntent, staleStarbaseGuidance?: string): Promise<void>;
+export {};
+//# sourceMappingURL=starbase-system.d.ts.map

package/dist/internal/planning/starbase-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"starbase-system.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/starbase-system.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAO5D,KAAK,oBAAoB,GAAG;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAUF;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,oBAAoB,EAC5B,qBAAqB,SAA0E,GAC9F,OAAO,CAAC,IAAI,CAAC,CA+Bf"}

package/dist/internal/planning/starbase-system.js

@@ -0,0 +1,25 @@
+import { SageSdkError } from '../../client/errors.js';
+import { deriveStarSystemAddress, starSystemAccountDefinition, } from '../c4/world.js';
+function fail(address, reason) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', `${reason} Refresh the Star System and recreate the action Plan for its current Starbase.`, { address });
+}
+/** Checks finite System/Starbase identity and the action's station policy.
+ * `staleStarbaseGuidance` lets a planner add action-specific advice for a
+ * replaced Starbase; execution and other actions use the neutral default.
+ */
+export async function validateStarbaseSystem(account, intent, staleStarbaseGuidance = 'The Starbase was destroyed or replaced after this action was planned.') {
+    if (account.address !== intent.address || account.executable)
+        fail(intent.address, 'The Star System has an unexpected address or is executable instead of account state.');
+    const system = starSystemAccountDefinition.decode(account);
+    if (system.game !== intent.game ||
+        (await deriveStarSystemAddress(intent.game, system.systemId)) !==
+            intent.address)
+        fail(intent.address, `Star System ${intent.address} does not match the configured Game or canonical system-id PDA.`);
+    if (system.sequenceId !== intent.starbaseSequenceId)
+        fail(intent.address, `The Starbase sequence is stale at ${intent.starbaseSequenceId}, while Star System ${intent.address} is at sequence ${system.sequenceId}. ${staleStarbaseGuidance}`);
+    if (system.starbase === undefined)
+        fail(intent.address, `Star System ${intent.address} does not have an active Starbase.`);
+    if (intent.requireCss && system.starbase.maxLevel.kind !== 'css')
+        fail(intent.address, 'This wallet deposit requires a Central Space Station.');
+}
+//# sourceMappingURL=starbase-system.js.map

package/dist/internal/planning/starbase-system.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"starbase-system.js","sourceRoot":"","sources":["../../../src/internal/planning/starbase-system.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EACL,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,gBAAgB,CAAC;AASxB,SAAS,IAAI,CAAC,OAAgB,EAAE,MAAc;IAC5C,MAAM,IAAI,YAAY,CACpB,4BAA4B,EAC5B,GAAG,MAAM,iFAAiF,EAC1F,EAAE,OAAO,EAAE,CACZ,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAAmB,EACnB,MAA4B,EAC5B,qBAAqB,GAAG,uEAAuE;IAE/F,IAAI,OAAO,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU;QAC1D,IAAI,CACF,MAAM,CAAC,OAAO,EACd,sFAAsF,CACvF,CAAC;IACJ,MAAM,MAAM,GAAG,2BAA2B,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC3D,IACE,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI;QAC3B,CAAC,MAAM,uBAAuB,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC3D,MAAM,CAAC,OAAO;QAEhB,IAAI,CACF,MAAM,CAAC,OAAO,EACd,eAAe,MAAM,CAAC,OAAO,iEAAiE,CAC/F,CAAC;IACJ,IAAI,MAAM,CAAC,UAAU,KAAK,MAAM,CAAC,kBAAkB;QACjD,IAAI,CACF,MAAM,CAAC,OAAO,EACd,qCAAqC,MAAM,CAAC,kBAAkB,uBAAuB,MAAM,CAAC,OAAO,mBAAmB,MAAM,CAAC,UAAU,KAAK,qBAAqB,EAAE,CACpK,CAAC;IACJ,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS;QAC/B,IAAI,CACF,MAAM,CAAC,OAAO,EACd,eAAe,MAAM,CAAC,OAAO,oCAAoC,CAClE,CAAC;IACJ,IAAI,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,KAAK,KAAK;QAC9D,IAAI,CACF,MAAM,CAAC,OAAO,EACd,uDAAuD,CACxD,CAAC;AACN,CAAC"}

package/dist/internal/planning/token-mint.d.ts

@@ -0,0 +1,4 @@
+import type { RawAccount } from '../../client/contracts.js';
+/** Validate the finite original Token Mint facts used by wallet transfers. */
+export declare function validateTokenMint(account: RawAccount): number;
+//# sourceMappingURL=token-mint.d.ts.map

package/dist/internal/planning/token-mint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-mint.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/token-mint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CA2B7D"}

package/dist/internal/planning/token-mint.js

@@ -0,0 +1,15 @@
+import { SageSdkError } from '../../client/errors.js';
+/** Validate the finite original Token Mint facts used by wallet transfers. */
+export function validateTokenMint(account) {
+    if (account.executable ||
+        account.owner !== 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' ||
+        account.data.length !== 82)
+        throw new SageSdkError('ACTION_PRECONDITION_FAILED', `Mint ${account.address} must be a non-executable original Token Mint with exactly 82 bytes. Refresh the mint or select a supported original Token mint; Token-2022 is unsupported.`, { address: account.address });
+    const view = new DataView(account.data.buffer, account.data.byteOffset, account.data.byteLength);
+    if (view.getUint32(0, true) > 1 ||
+        view.getUint32(46, true) > 1 ||
+        view.getUint8(45) !== 1)
+        throw new SageSdkError('ACTION_PRECONDITION_FAILED', `Mint ${account.address} must be initialized with valid optional authority fields. Refresh the mint and prepare a new Plan.`, { address: account.address });
+    return view.getUint8(44);
+}
+//# sourceMappingURL=token-mint.js.map

package/dist/internal/planning/token-mint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-mint.js","sourceRoot":"","sources":["../../../src/internal/planning/token-mint.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB,CAAC,OAAmB;IACnD,IACE,OAAO,CAAC,UAAU;QAClB,OAAO,CAAC,KAAK,KAAK,6CAA6C;QAC/D,OAAO,CAAC,IAAI,CAAC,MAAM,KAAK,EAAE;QAE1B,MAAM,IAAI,YAAY,CACpB,4BAA4B,EAC5B,QAAQ,OAAO,CAAC,OAAO,6JAA6J,EACpL,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAC7B,CAAC;IACJ,MAAM,IAAI,GAAG,IAAI,QAAQ,CACvB,OAAO,CAAC,IAAI,CAAC,MAAM,EACnB,OAAO,CAAC,IAAI,CAAC,UAAU,EACvB,OAAO,CAAC,IAAI,CAAC,UAAU,CACxB,CAAC;IACF,IACE,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC;QAC3B,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC;QAC5B,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC;QAEvB,MAAM,IAAI,YAAY,CACpB,4BAA4B,EAC5B,QAAQ,OAAO,CAAC,OAAO,qGAAqG,EAC5H,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAC7B,CAAC;IACJ,OAAO,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC3B,CAAC"}

package/dist/internal/planning/trade-faction-market.d.ts

@@ -0,0 +1,20 @@
+import { type Address } from '@solana/kit';
+import { type PlanAuthorization, type AddressOnlyInstruction } from './authorization-adapter.js';
+/** Address-only adapter for one directional Faction Market trade. */
+export declare function adaptTradeFactionMarketInstruction(input: {
+    readonly authorization: PlanAuthorization;
+    readonly character: Address;
+    readonly game: Address;
+    readonly system: Address;
+    readonly starbasePlayer: Address;
+    readonly fleet: Address;
+    readonly factionMarket: Address;
+    readonly treasury: Address;
+    readonly factionStanding?: Address;
+    readonly factionConfig?: Address;
+    readonly factionEpochMeter?: Address;
+    readonly offerIndex: number;
+    readonly quantity: bigint;
+    readonly playerBuys: boolean;
+}): AddressOnlyInstruction;
+//# sourceMappingURL=trade-faction-market.d.ts.map

package/dist/internal/planning/trade-faction-market.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trade-faction-market.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/trade-faction-market.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,OAAO,EAGb,MAAM,aAAa,CAAC;AAMrB,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC5B,MAAM,4BAA4B,CAAC;AA8CpC,qEAAqE;AACrE,wBAAgB,kCAAkC,CAAC,KAAK,EAAE;IACxD,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B,GAAG,sBAAsB,CAyBzB"}

package/dist/internal/planning/trade-faction-market.js

@@ -0,0 +1,56 @@
+import { AccountRole, } from '@solana/kit';
+import { PLAYER_PROFILE_PROGRAM_ADDRESS, SAGE_PROGRAM_ADDRESS, getTradeFactionMarketInstructionDataEncoder, } from '../c4/runtime-bindings.js';
+import { validatePlanAuthorization, } from './authorization-adapter.js';
+const readonlyAccount = (address) => ({
+    address,
+    role: AccountRole.READONLY,
+});
+const writableAccount = (address) => ({
+    address,
+    role: AccountRole.WRITABLE,
+});
+const optionalReadonlyAccount = (address, program) => readonlyAccount(address ?? program);
+const optionalWritableAccount = (address, program) => address === undefined ? readonlyAccount(program) : writableAccount(address);
+function authorizationAccounts(input, program) {
+    validatePlanAuthorization(input.authorization);
+    return [
+        {
+            address: input.authorization.authority,
+            role: AccountRole.READONLY_SIGNER,
+        },
+        writableAccount(input.authorization.profile),
+        readonlyAccount(input.authorization.certificate ?? program),
+        readonlyAccount(PLAYER_PROFILE_PROGRAM_ADDRESS),
+    ];
+}
+function createAddressOnlyInstruction(programAddress, accounts, data) {
+    return Object.freeze({
+        programAddress,
+        accounts: Object.freeze(accounts.map((account) => Object.freeze(account))),
+        data,
+    });
+}
+/** Address-only adapter for one directional Faction Market trade. */
+export function adaptTradeFactionMarketInstruction(input) {
+    const programAddress = SAGE_PROGRAM_ADDRESS;
+    return createAddressOnlyInstruction(programAddress, [
+        ...authorizationAccounts(input, programAddress),
+        writableAccount(input.character),
+        readonlyAccount(input.game),
+        readonlyAccount(input.system),
+        writableAccount(input.starbasePlayer),
+        writableAccount(input.fleet),
+        writableAccount(input.factionMarket),
+        writableAccount(input.treasury),
+        readonlyAccount('11111111111111111111111111111111'),
+        optionalWritableAccount(input.factionStanding, programAddress),
+        optionalReadonlyAccount(input.factionConfig, programAddress),
+        optionalWritableAccount(input.factionEpochMeter, programAddress),
+    ], getTradeFactionMarketInstructionDataEncoder().encode({
+        keyIndex: input.authorization.keyIndex,
+        offerIndex: input.offerIndex,
+        quantity: input.quantity,
+        playerBuys: input.playerBuys,
+    }));
+}
+//# sourceMappingURL=trade-faction-market.js.map

package/dist/internal/planning/trade-faction-market.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trade-faction-market.js","sourceRoot":"","sources":["../../../src/internal/planning/trade-faction-market.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,GAIZ,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,8BAA8B,EAC9B,oBAAoB,EACpB,2CAA2C,GAC5C,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,yBAAyB,GAG1B,MAAM,4BAA4B,CAAC;AAEpC,MAAM,eAAe,GAAG,CAAC,OAAgB,EAAe,EAAE,CAAC,CAAC;IAC1D,OAAO;IACP,IAAI,EAAE,WAAW,CAAC,QAAQ;CAC3B,CAAC,CAAC;AACH,MAAM,eAAe,GAAG,CAAC,OAAgB,EAAe,EAAE,CAAC,CAAC;IAC1D,OAAO;IACP,IAAI,EAAE,WAAW,CAAC,QAAQ;CAC3B,CAAC,CAAC;AACH,MAAM,uBAAuB,GAAG,CAC9B,OAA4B,EAC5B,OAAgB,EAChB,EAAE,CAAC,eAAe,CAAC,OAAO,IAAI,OAAO,CAAC,CAAC;AACzC,MAAM,uBAAuB,GAAG,CAC9B,OAA4B,EAC5B,OAAgB,EAChB,EAAE,CACF,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;AAC9E,SAAS,qBAAqB,CAC5B,KAA2C,EAC3C,OAAgB;IAEhB,yBAAyB,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAC/C,OAAO;QACL;YACE,OAAO,EAAE,KAAK,CAAC,aAAa,CAAC,SAAS;YACtC,IAAI,EAAE,WAAW,CAAC,eAAe;SAClC;QACD,eAAe,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC;QAC5C,eAAe,CAAC,KAAK,CAAC,aAAa,CAAC,WAAW,IAAI,OAAO,CAAC;QAC3D,eAAe,CAAC,8BAA8B,CAAC;KAChD,CAAC;AACJ,CAAC;AACD,SAAS,4BAA4B,CACnC,cAAuB,EACvB,QAAgC,EAChC,IAAwB;IAExB,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,cAAc;QACd,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QAC1E,IAAI;KACL,CAAC,CAAC;AACL,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,kCAAkC,CAAC,KAelD;IACC,MAAM,cAAc,GAAG,oBAAoB,CAAC;IAC5C,OAAO,4BAA4B,CACjC,cAAc,EACd;QACE,GAAG,qBAAqB,CAAC,KAAK,EAAE,cAAc,CAAC;QAC/C,eAAe,CAAC,KAAK,CAAC,SAAS,CAAC;QAChC,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC;QAC3B,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC;QAC7B,eAAe,CAAC,KAAK,CAAC,cAAc,CAAC;QACrC,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC;QAC5B,eAAe,CAAC,KAAK,CAAC,aAAa,CAAC;QACpC,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC/B,eAAe,CAAC,kCAA6C,CAAC;QAC9D,uBAAuB,CAAC,KAAK,CAAC,eAAe,EAAE,cAAc,CAAC;QAC9D,uBAAuB,CAAC,KAAK,CAAC,aAAa,EAAE,cAAc,CAAC;QAC5D,uBAAuB,CAAC,KAAK,CAAC,iBAAiB,EAAE,cAAc,CAAC;KACjE,EACD,2CAA2C,EAAE,CAAC,MAAM,CAAC;QACnD,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC,QAAQ;QACtC,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,UAAU,EAAE,KAAK,CAAC,UAAU;KAC7B,CAAC,CACH,CAAC;AACJ,CAAC"}

package/dist/internal/planning/wallet-starbase.d.ts

@@ -0,0 +1,34 @@
+import type { Address } from '@solana/kit';
+import type { RawAccount } from '../../client/contracts.js';
+/** Rejects with the calling planner's wording and remedy. */
+type Fail = (message: string, address: Address) => never;
+/** Requires the fresh Profile, Character, Starbase Player and System of a
+ * wallet transfer to be decodable account state of the configured Game and
+ * authorization Profile, and the System to be canonical with an active
+ * Starbase (a Central Space Station when `requireCss`). Returns the decoded
+ * Profile and Starbase Player and the matching System guard. */
+export declare function validateWalletStarbase(accounts: {
+    readonly profile: RawAccount;
+    readonly character: RawAccount;
+    readonly player: RawAccount;
+    readonly system: RawAccount;
+}, facts: {
+    readonly game: Address;
+    readonly profile: Address;
+    readonly character: Address;
+    readonly system: Address;
+    readonly requireCss: boolean;
+}, fail: Fail): Promise<{
+    playerData: Readonly<import("../c4/starbase.js").StarbasePlayerAccountData>;
+    profileData: Readonly<import("../c4/identity.js").ProfileAccountData>;
+    systemGuard: {
+        describes: string;
+        requireCss?: true;
+        kind: "starbase-system";
+        address: import("../../client/contracts.js").Address;
+        game: Address;
+        starbaseSequenceId: bigint;
+    };
+}>;
+export {};
+//# sourceMappingURL=wallet-starbase.d.ts.map

package/dist/internal/planning/wallet-starbase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-starbase.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/wallet-starbase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAU5D,6DAA6D;AAC7D,KAAK,IAAI,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,KAAK,CAAC;AAEzD;;;;gEAIgE;AAChE,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE;IACR,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B,EACD,KAAK,EAAE;IACL,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B,EACD,IAAI,EAAE,IAAI;;;;;;;;;;;GAoCX"}

package/dist/internal/planning/wallet-starbase.js

@@ -0,0 +1,39 @@
+import { characterAccountDefinition } from '../c4/character.js';
+import { profileAccountDefinition } from '../c4/identity.js';
+import { starbasePlayerAccountDefinition } from '../c4/starbase.js';
+import { deriveStarSystemAddress, starSystemAccountDefinition, } from '../c4/world.js';
+import { validateStarbaseSystem } from './starbase-system.js';
+/** Requires the fresh Profile, Character, Starbase Player and System of a
+ * wallet transfer to be decodable account state of the configured Game and
+ * authorization Profile, and the System to be canonical with an active
+ * Starbase (a Central Space Station when `requireCss`). Returns the decoded
+ * Profile and Starbase Player and the matching System guard. */
+export async function validateWalletStarbase(accounts, facts, fail) {
+    for (const account of Object.values(accounts))
+        if (account.executable)
+            fail('A gameplay prerequisite is executable rather than account state.', account.address);
+    const profileData = profileAccountDefinition.decode(accounts.profile);
+    const characterData = characterAccountDefinition.decode(accounts.character);
+    const playerData = starbasePlayerAccountDefinition.decode(accounts.player);
+    const systemData = starSystemAccountDefinition.decode(accounts.system);
+    if (characterData.game !== facts.game ||
+        characterData.playerProfile !== facts.profile ||
+        playerData.playerProfile !== facts.profile ||
+        playerData.character !== facts.character ||
+        playerData.system !== facts.system ||
+        systemData.game !== facts.game ||
+        (await deriveStarSystemAddress(facts.game, systemData.systemId)) !==
+            facts.system)
+        fail('Fresh Character, Starbase Player and System must belong to the configured Game and authorized Profile.', accounts.player.address);
+    const systemGuard = {
+        kind: 'starbase-system',
+        address: accounts.system.address,
+        game: facts.game,
+        starbaseSequenceId: systemData.sequenceId,
+        ...(facts.requireCss ? { requireCss: true } : {}),
+        describes: `The canonical Star System retains its active Starbase and generation${facts.requireCss ? ' as a Central Space Station' : ''}; unrelated shared activity may change.`,
+    };
+    await validateStarbaseSystem(accounts.system, systemGuard);
+    return { playerData, profileData, systemGuard };
+}
+//# sourceMappingURL=wallet-starbase.js.map

package/dist/internal/planning/wallet-starbase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-starbase.js","sourceRoot":"","sources":["../../../src/internal/planning/wallet-starbase.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,+BAA+B,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EACL,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAK9D;;;;gEAIgE;AAChE,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,QAKC,EACD,KAMC,EACD,IAAU;IAEV,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;QAC3C,IAAI,OAAO,CAAC,UAAU;YACpB,IAAI,CACF,kEAAkE,EAClE,OAAO,CAAC,OAAO,CAChB,CAAC;IACN,MAAM,WAAW,GAAG,wBAAwB,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACtE,MAAM,aAAa,GAAG,0BAA0B,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC5E,MAAM,UAAU,GAAG,+BAA+B,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3E,MAAM,UAAU,GAAG,2BAA2B,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACvE,IACE,aAAa,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI;QACjC,aAAa,CAAC,aAAa,KAAK,KAAK,CAAC,OAAO;QAC7C,UAAU,CAAC,aAAa,KAAK,KAAK,CAAC,OAAO;QAC1C,UAAU,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS;QACxC,UAAU,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;QAClC,UAAU,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI;QAC9B,CAAC,MAAM,uBAAuB,CAAC,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;YAC9D,KAAK,CAAC,MAAM;QAEd,IAAI,CACF,wGAAwG,EACxG,QAAQ,CAAC,MAAM,CAAC,OAAO,CACxB,CAAC;IACJ,MAAM,WAAW,GAAG;QAClB,IAAI,EAAE,iBAA0B;QAChC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO;QAChC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,kBAAkB,EAAE,UAAU,CAAC,UAAU;QACzC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,SAAS,EAAE,uEAAuE,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,EAAE,yCAAyC;KACjL,CAAC;IACF,MAAM,sBAAsB,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3D,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;AAClD,CAAC"}

package/dist/internal/planning/xp-runtime.d.ts

@@ -0,0 +1,36 @@
+import type { Address, RawAccount, SageContext } from '../../client/contracts.js';
+import { readContextRawAccounts } from '../../client/reconciliation.js';
+/** Finite eligibility facts only; live XP banks and accrual never become hashes. */
+export interface XpRuntimeIntent {
+    readonly game: Address;
+    readonly gameVersion: 2;
+    readonly character?: Address;
+    readonly profile?: Address;
+    readonly structure?: Address;
+}
+export interface XpRuntimeAccounts {
+    readonly xpBudget?: Address;
+    readonly xpBudgetConfig?: Address;
+    readonly xpAccrual?: Address;
+}
+/** Canonical current-runtime accounts required while creating a Character. */
+export interface CharacterRegistrationXpRuntime {
+    readonly xpBudget: Address;
+    readonly xpBudgetConfig: Address;
+    readonly configAccount: RawAccount;
+    readonly budgetLamports: bigint;
+}
+/** Resolve creation targets after the caller has freshly validated Game 2 and its initializer. */
+export declare function resolveCharacterRegistrationXpRuntime(ctx: SageContext, input: {
+    readonly game: Address;
+    readonly character: Address;
+}, options?: Parameters<typeof readContextRawAccounts>[2]): Promise<CharacterRegistrationXpRuntime>;
+/** Resolve existing canonical XP accounts without migrating or creating anything.
+ * A supplied Game-version map belongs to one fresh validation pass, never a context.
+ */
+export declare function resolveXpRuntime(ctx: SageContext, input: Omit<XpRuntimeIntent, 'gameVersion'>, freshGameVersions?: Map<Address, number>, options?: Parameters<typeof readContextRawAccounts>[2]): Promise<{
+    readonly gameVersion: 2;
+    readonly intent: XpRuntimeIntent;
+    readonly accounts: XpRuntimeAccounts;
+}>;
+//# sourceMappingURL=xp-runtime.d.ts.map

package/dist/internal/planning/xp-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xp-runtime.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/xp-runtime.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAGxE,oFAAoF;AACpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,8EAA8E;AAC9E,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAoED,kGAAkG;AAClG,wBAAsB,qCAAqC,CACzD,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAAE,EAC9D,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC,CAAC,CAAC,GACrD,OAAO,CAAC,8BAA8B,CAAC,CAiCzC;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC,EAC3C,iBAAiB,CAAC,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,EACxC,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC,CAAC,CAAC,GACrD,OAAO,CAAC;IACT,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;CACtC,CAAC,CAgGD"}

package/dist/internal/planning/xp-runtime.js

@@ -0,0 +1,126 @@
+import { findCharacterPda } from '../c4/character.js';
+import { getAddressEncoder, getProgramDerivedAddress, } from '@solana/kit';
+import { CAREER_XP_BUDGET_DISCRIMINATOR, XP_BUDGET_CONFIG_DISCRIMINATOR, STRUCTURE_XP_ACCRUAL_DISCRIMINATOR, SAGE_PROGRAM_ADDRESS, getCareerXpBudgetDecoder, getXpBudgetConfigDecoder, getStructureXpAccrualDecoder, } from '../c4/runtime-bindings.js';
+import { SageSdkError } from '../../client/errors.js';
+import { readContextRawAccounts } from '../../client/reconciliation.js';
+import { readFreshGameRuntimeVersion } from '../../registry/xp-runtime.js';
+function fail(address, reason) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', `XP runtime account ${address} ${reason}. Refresh the account and prepare a new Plan; use the game client or operator's supported migration flow if XP is not initialized.`, { address });
+}
+function decode(account, address, decoder, discriminator) {
+    if (!account ||
+        account.address !== address ||
+        account.executable ||
+        account.owner !== SAGE_PROGRAM_ADDRESS ||
+        account.data.length !== decoder.fixedSize ||
+        !discriminator.every((byte, index) => account.data[index] === byte))
+        fail(address, 'is missing or has unsupported ownership, identity or layout');
+    // All XP codecs are fixed-size structs of integers, addresses and fixed arrays.
+    // Exact size and discriminator are checked before decoding provider-owned bytes.
+    return decoder.decode(account.data);
+}
+function validateBinding(value, address, game, bump, version) {
+    if (value.version !== version ||
+        value.bump !== bump ||
+        value.gameId !== game ||
+        value.reserved.some((byte) => byte !== 0))
+        fail(address, 'has an unsupported schema or does not match its canonical Game binding');
+}
+function derive(seed, addresses) {
+    return getProgramDerivedAddress({
+        programAddress: SAGE_PROGRAM_ADDRESS,
+        // Literal seeds match dev-sage 0.53.0 generated source; no trailing NUL.
+        seeds: [
+            new TextEncoder().encode(seed),
+            ...addresses.map((address) => getAddressEncoder().encode(address)),
+        ],
+    });
+}
+/** Resolve creation targets after the caller has freshly validated Game 2 and its initializer. */
+export async function resolveCharacterRegistrationXpRuntime(ctx, input, options) {
+    const [config, budget] = await Promise.all([
+        derive('XpBudgetConfig', [input.game]),
+        derive('CareerXpBudget', [input.game, input.character]),
+    ]);
+    const [configAccount, budgetAccount] = await readContextRawAccounts(ctx, [config[0], budget[0]], options);
+    const configValue = decode(configAccount, config[0], getXpBudgetConfigDecoder(), XP_BUDGET_CONFIG_DISCRIMINATOR);
+    validateBinding(configValue, config[0], input.game, config[1], 1);
+    if (budgetAccount !== undefined &&
+        (budgetAccount.executable ||
+            budgetAccount.owner !== '11111111111111111111111111111111' ||
+            budgetAccount.data.length !== 0))
+        fail(budget[0], 'already exists while its canonical Character is absent; reconcile the partial registration before retrying');
+    return {
+        xpBudget: budget[0],
+        xpBudgetConfig: config[0],
+        configAccount: configAccount,
+        budgetLamports: budgetAccount?.lamports ?? 0n,
+    };
+}
+/** Resolve existing canonical XP accounts without migrating or creating anything.
+ * A supplied Game-version map belongs to one fresh validation pass, never a context.
+ */
+export async function resolveXpRuntime(ctx, input, freshGameVersions, options) {
+    const { game, character, structure, profile } = input;
+    if (profile !== undefined &&
+        character !== (await findCharacterPda(profile, game)))
+        fail(game, 'does not identify the canonical Character for the authorized Profile');
+    const gameVersion = freshGameVersions?.get(game) ??
+        (await readFreshGameRuntimeVersion(ctx, game, options));
+    freshGameVersions?.set(game, gameVersion);
+    if (gameVersion !== 2)
+        fail(game, gameVersion === 1
+            ? 'belongs to a migration-sealed Game'
+            : `uses unsupported Game runtime version ${gameVersion}`);
+    const intent = {
+        game,
+        gameVersion,
+        ...(profile === undefined ? {} : { profile }),
+        ...(character !== undefined ? { character } : {}),
+        ...(structure !== undefined ? { structure } : {}),
+    };
+    const config = character === undefined
+        ? undefined
+        : await derive('XpBudgetConfig', [game]);
+    const budget = character === undefined
+        ? undefined
+        : await derive('CareerXpBudget', [game, character]);
+    const accrual = structure === undefined
+        ? undefined
+        : await derive('StructureXpAccrual', [structure]);
+    const addresses = [
+        ...(config ? [config[0]] : []),
+        ...(budget ? [budget[0]] : []),
+        ...(accrual ? [accrual[0]] : []),
+    ];
+    const raw = addresses.length === 0
+        ? []
+        : await readContextRawAccounts(ctx, addresses, options);
+    const byAddress = new Map(addresses.map((address, index) => [address, raw[index]]));
+    if (config) {
+        const configValue = decode(byAddress.get(config[0]), config[0], getXpBudgetConfigDecoder(), XP_BUDGET_CONFIG_DISCRIMINATOR);
+        validateBinding(configValue, config[0], game, config[1], 1);
+    }
+    if (budget) {
+        const value = decode(byAddress.get(budget[0]), budget[0], getCareerXpBudgetDecoder(), CAREER_XP_BUDGET_DISCRIMINATOR);
+        validateBinding(value, budget[0], game, budget[1], 1);
+        if (value.characterId !== character || value.reconciledThresholdVersion < 1)
+            fail(budget[0], 'does not belong to this Character or has not completed XP reconciliation');
+    }
+    if (accrual) {
+        const value = decode(byAddress.get(accrual[0]), accrual[0], getStructureXpAccrualDecoder(), STRUCTURE_XP_ACCRUAL_DISCRIMINATOR);
+        validateBinding(value, accrual[0], game, accrual[1], 2);
+        if (value.structure !== structure)
+            fail(accrual[0], 'does not belong to this structure');
+    }
+    return {
+        gameVersion,
+        intent,
+        accounts: {
+            ...(config ? { xpBudgetConfig: config[0] } : {}),
+            ...(budget ? { xpBudget: budget[0] } : {}),
+            ...(accrual ? { xpAccrual: accrual[0] } : {}),
+        },
+    };
+}
+//# sourceMappingURL=xp-runtime.js.map

package/dist/internal/planning/xp-runtime.js.map

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

package/dist/internal/system-program.d.ts

@@ -0,0 +1,4 @@
+import type { Address } from '@solana/kit';
+/** System program identity, also used by C4 for stored absent-account addresses. */
+export declare const SYSTEM_PROGRAM: Address;
+//# sourceMappingURL=system-program.d.ts.map

package/dist/internal/system-program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-program.d.ts","sourceRoot":"","sources":["../../src/internal/system-program.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,oFAAoF;AACpF,eAAO,MAAM,cAAc,EAAyC,OAAO,CAAC"}

package/dist/internal/system-program.js

@@ -0,0 +1,3 @@
+/** System program identity, also used by C4 for stored absent-account addresses. */
+export const SYSTEM_PROGRAM = '11111111111111111111111111111111';
+//# sourceMappingURL=system-program.js.map

package/dist/internal/system-program.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-program.js","sourceRoot":"","sources":["../../src/internal/system-program.ts"],"names":[],"mappings":"AAEA,oFAAoF;AACpF,MAAM,CAAC,MAAM,cAAc,GAAG,kCAA6C,CAAC"}

package/dist/loyalty/actions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/loyalty/actions/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAazE,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAEL,KAAK,IAAI,EAEV,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAE5D,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAElC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,4BAA4B;IAC3C,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;CAC3C;AAuHD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,wBAAwB,EAC9B,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,IAAI,CAAC,CA2Hf"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/loyalty/actions/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAczE,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAEL,KAAK,IAAI,EAEV,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAE5D,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAElC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,4BAA4B;IAC3C,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;CAC3C;AA8FD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,wBAAwB,EAC9B,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,IAAI,CAAC,CA4Hf"}

package/dist/loyalty/actions/index.js

@@ -1,10 +1,11 @@
-import { getAddressEncoder, isAddress } from '@solana/kit';
+import { getAddressEncoder } from '@solana/kit';
 import { InvalidActionInputError, SageSdkError } from '../../client/errors.js';
 import { readContextRawAccounts } from '../../client/reconciliation.js';
-import { characterAccountDefinition, findCharacterPda, } from '../../internal/c4/identity.js';
+import { characterAccountDefinition, findCharacterPda, } from '../../internal/c4/character.js';
 import { deriveLoyaltyAtlasBankAddress, deriveLoyaltyFactionAddress, loyaltyAtlasBankAccountDefinition, } from '../../internal/c4/loyalty.js';
 import { requireGameAddress } from '../../internal/game-context.js';
-import { adaptClaimLoyaltyAtlasInstruction, validatePlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
+import { deriveInternalLoyaltyAtlasBankState } from '../../internal/loyalty-atlas-bank-state.js';
+import { adaptClaimLoyaltyAtlasInstruction, readPlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
 import { createPlan, } from '../../planning/index.js';
 function invalid(field, value, acceptedRange, remedy) {
     throw new InvalidActionInputError(field, value, acceptedRange, remedy);
@@ -26,24 +27,10 @@ function exactKeys(value, field, required, optional = []) {
         invalid(field, missing === undefined ? unexpected : `missing ${missing}`, `exactly the fields ${[...required, ...optional].join(', ')}`, `Remove unknown fields and provide every required ${field} field before retrying.`);
     }
 }
-function address(value, field) {
-    if (typeof value !== 'string' || !isAddress(value)) {
-        return invalid(field, value, 'one valid z.ink/Solana account address', `Set ${field} to the documented public account address before retrying.`);
-    }
-    return value;
-}
 function validateOptions(value) {
     const options = record(value, 'options');
     exactKeys(options, 'options', ['atUnixSeconds', 'authorization']);
-    const authorizationRecord = record(options.authorization, 'authorization');
-    exactKeys(authorizationRecord, 'authorization', ['profile', 'authority', 'keyIndex'], ['certificate']);
-    const authorization = authorizationRecord;
-    address(authorization.profile, 'authorization.profile');
-    address(authorization.authority, 'authorization.authority');
-    if (authorization.certificate !== undefined) {
-        address(authorization.certificate, 'authorization.certificate');
-    }
-    validatePlanAuthorization(authorization);
+    const authorization = readPlanAuthorization(options.authorization);
     if (typeof options.atUnixSeconds !== 'bigint' || options.atUnixSeconds < 0n) {
         invalid('atUnixSeconds', options.atUnixSeconds, 'a non-negative bigint Unix timestamp', 'Provide the explicit current Unix timestamp used to evaluate Loyalty ATLAS Bank expiry before retrying.');
     }
@@ -102,11 +89,11 @@ export async function planClaimLoyaltyAtlas(ctx, bank, input) {
     if (bank.faction.address !== faction) {
         fail(`Loyalty ATLAS Bank ${bank.address} does not match canonical faction account ${faction}. Refresh the Bank and retry.`, bank.address);
     }
-    if (bank.claimableAtlasRaw === 0n) {
+    const state = deriveInternalLoyaltyAtlasBankState(bank, options.atUnixSeconds);
+    if (state.kind === 'empty') {
         fail(`Loyalty ATLAS Bank ${bank.address} has no claimable ATLAS. Refresh it and retry after ATLAS is credited.`, bank.address);
     }
-    if (bank.expiresAtUnixSeconds !== 0n &&
-        options.atUnixSeconds >= bank.expiresAtUnixSeconds) {
+    if (state.kind === 'expired') {
         fail(`Loyalty ATLAS Bank ${bank.address} expired at Unix timestamp ${String(bank.expiresAtUnixSeconds)}. This balance cannot be claimed; refresh the Bank before choosing another action.`, bank.address);
     }
     const character = await findCharacterPda(options.authorization.profile, game);