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

package/dist/internal/planning/rent-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rent-catalog.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/rent-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAG7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAmB1E,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAA6B,CAAC;AAI/E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAuCD;0DAC0D;AAC1D,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IACT,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC9C,CAAC,CAcD;AAED,gFAAgF;AAChF,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC;IACT,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC9C,CAAC,CAUD;AAED;qEACqE;AACrE,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,OAAO,EACb,MAAM,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAChE,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IACT,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC9C,CAAC,CAcD;AA+ED;gFACgF;AAChF,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAClC,IAAI,CAoCN"}

package/dist/internal/planning/rent-catalog.js

@@ -0,0 +1,165 @@
+import { AccountRole } from '@solana/kit';
+import { SageSdkError } from '../../client/errors.js';
+import { readContextRawAccounts } from '../../client/reconciliation.js';
+import { ATTACK_STARBASE_DISCRIMINATOR, CANCEL_CLAIM_STAKE_BUILDING_DESIGN_DISCRIMINATOR, CLAIM_STAKES_RENT_TOP_UP_DISCRIMINATOR, DECONSTRUCT_CLAIM_STAKE_INSTANCE_DISCRIMINATOR, FINALIZE_BUILDING_CHANGES_DISCRIMINATOR, PLACE_CLAIM_STAKE_BUILDINGS_DISCRIMINATOR, PLACE_CLAIM_STAKE_INSTANCE_WITH_HUB_DISCRIMINATOR, START_CLAIM_STAKES_FLEET_TRANSFER_DISCRIMINATOR, } from '../c4/discriminators.js';
+import { deriveRentCatalogAddress, deriveRentLevelHeadAddress, deriveRentSettlementAuthorityAddress, } from '../c4/pda.js';
+import { SAGE_PROGRAM_ADDRESS } from '../c4/runtime-bindings.js';
+import { accountAbsentPrecondition } from './account-state.js';
+/** Baseline-record hints; the program reads them only under an Active catalog. */
+export const DISABLED_RENT_HINTS = Object.freeze([0, 0, 0]);
+const RENT_HINTS_BYTES = 12;
+async function requireAbsent(ctx, accounts) {
+    const raw = await readContextRawAccounts(ctx, accounts.map(({ address }) => address));
+    accounts.forEach(({ address, present }, index) => {
+        if (raw[index] !== undefined)
+            throw new SageSdkError('ACTION_PRECONDITION_FAILED', present, {
+                address,
+            });
+    });
+    return accounts.map(({ address, describes }) => accountAbsentPrecondition(address, describes));
+}
+function catalogAccount(rentCatalog, game, action) {
+    return {
+        address: rentCatalog,
+        present: `Game ${game} has rent catalog ${rentCatalog}, so its rent is no longer Disabled and ${action} needs rent history accounts this SDK does not plan yet. Use the game client for ${action}.`,
+        describes: `Rent catalog ${rentCatalog} remains absent, so rent stays Disabled.`,
+    };
+}
+/** Requires Disabled rent for an existing Claim Stake: neither the Game's rent
+ * catalog nor the stake's settlement authority exists. */
+export async function requireDisabledStakeRent(ctx, game, stake, action) {
+    const [[rentCatalog], [rentAuthority]] = await Promise.all([
+        deriveRentCatalogAddress(game),
+        deriveRentSettlementAuthorityAddress(stake),
+    ]);
+    const guards = await requireAbsent(ctx, [
+        catalogAccount(rentCatalog, game, action),
+        {
+            address: rentAuthority,
+            present: `Claim Stake ${stake} has rent settlement authority ${rentAuthority}, so it may hold a rent evaluation this SDK does not plan yet. Use the game client for ${action}.`,
+            describes: `Claim Stake ${stake} rent settlement authority ${rentAuthority} remains absent.`,
+        },
+    ]);
+    return { accounts: { rentAuthority, rentCatalog }, guards };
+}
+/** Requires that a new Claim Stake address has no rent settlement authority. */
+export async function requireNewStakeRent(ctx, stake) {
+    const [rentAuthority] = await deriveRentSettlementAuthorityAddress(stake);
+    const guards = await requireAbsent(ctx, [
+        {
+            address: rentAuthority,
+            present: `Rent settlement authority ${rentAuthority} already exists for new Claim Stake address ${stake}. Generate a fresh address-only Claim Stake signer and retry placement.`,
+            describes: `New Claim Stake ${stake} rent settlement authority ${rentAuthority} remains absent.`,
+        },
+    ]);
+    return { rentAuthority, guards };
+}
+/** Requires Disabled rent for a Starbase-level change in `system`: neither the
+ * Game's rent catalog nor the System's level history head exists. */
+export async function requireDisabledLevelRent(ctx, game, system, action) {
+    const [[rentCatalog], [rentHead]] = await Promise.all([
+        deriveRentCatalogAddress(game),
+        deriveRentLevelHeadAddress(game, system.systemId),
+    ]);
+    const guards = await requireAbsent(ctx, [
+        catalogAccount(rentCatalog, game, action),
+        {
+            address: rentHead,
+            present: `Star System ${system.address} has Starbase-level rent history ${rentHead}, which ${action} must extend with history pages this SDK does not plan yet. Use the game client for ${action}.`,
+            describes: `Star System ${system.address} Starbase-level rent history ${rentHead} remains absent.`,
+        },
+    ]);
+    return { accounts: { rentCatalog, rentHead }, guards };
+}
+// Disabled-rent layouts of the pinned generated builders, without rent pages.
+// The adapter suites pin each layout to its builder, and rent-catalog tests
+// build every layout through those adapters.
+function rentLayouts() {
+    return [
+        [CLAIM_STAKES_RENT_TOP_UP_DISCRIMINATOR, 13, 10, 11, [12], false, 18],
+        [
+            PLACE_CLAIM_STAKE_INSTANCE_WITH_HUB_DISCRIMINATOR,
+            14,
+            -1,
+            13,
+            [],
+            false,
+            0,
+        ],
+        [
+            PLACE_CLAIM_STAKE_BUILDINGS_DISCRIMINATOR,
+            19,
+            14,
+            15,
+            [16, 17, 18],
+            true,
+            0,
+        ],
+        [
+            CANCEL_CLAIM_STAKE_BUILDING_DESIGN_DISCRIMINATOR,
+            17,
+            12,
+            13,
+            [14, 15, 16],
+            true,
+            22,
+        ],
+        [
+            FINALIZE_BUILDING_CHANGES_DISCRIMINATOR,
+            20,
+            15,
+            16,
+            [17, 18, 19],
+            true,
+            22,
+        ],
+        [
+            START_CLAIM_STAKES_FLEET_TRANSFER_DISCRIMINATOR,
+            19,
+            14,
+            15,
+            [16, 17, 18],
+            true,
+            0,
+        ],
+        [
+            DECONSTRUCT_CLAIM_STAKE_INSTANCE_DISCRIMINATOR,
+            22,
+            11,
+            12,
+            [13, 14, 16, 17, 18],
+            true,
+            27,
+        ],
+        [ATTACK_STARBASE_DISCRIMINATOR, 32, 25, 26, [27, 28], false, 11],
+    ];
+}
+/** Binds every rent account of a recognized instruction to an absence guard
+ * and rejects rent pages, supplied optional rent accounts and nonzero hints. */
+export function validateRentInstructions(steps, guards) {
+    for (const [index, { instruction }] of steps.entries()) {
+        if (instruction.programAddress !== SAGE_PROGRAM_ADDRESS)
+            continue;
+        const data = instruction.data;
+        const layout = rentLayouts().find(([discriminator]) => discriminator.every((byte, offset) => data?.[offset] === byte));
+        if (!layout)
+            continue;
+        const [, count, catalog, writable, omitted, hints, dataLength] = layout;
+        const metas = instruction.accounts;
+        const guarded = (at, role) => metas[at].role === role &&
+            guards.some((g) => g.kind === 'account-absent' && g.address === metas[at].address);
+        if (!data ||
+            !metas ||
+            metas.length !== count ||
+            (dataLength !== 0 && data.length !== dataLength) ||
+            (hints &&
+                (data.length < 8 + RENT_HINTS_BYTES ||
+                    data.subarray(data.length - RENT_HINTS_BYTES).some(Boolean))) ||
+            omitted.some((at) => metas[at].address !== SAGE_PROGRAM_ADDRESS ||
+                metas[at].role !== AccountRole.READONLY) ||
+            (catalog >= 0 && !guarded(catalog, AccountRole.READONLY)) ||
+            !guarded(writable, AccountRole.WRITABLE))
+            throw new SageSdkError('ACTION_PRECONDITION_FAILED', `Step ${index}: this instruction needs the current Disabled-rent layout with an absence safeguard for each rent account. Refresh the accounts and recreate the Plan with its planner before signing.`);
+    }
+}
+//# sourceMappingURL=rent-catalog.js.map

package/dist/internal/planning/rent-catalog.js.map

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

package/dist/internal/planning/rent.d.ts

@@ -0,0 +1,19 @@
+import type { Address } from '@solana/kit';
+import type { RawAccount } from '../../client/contracts.js';
+import { SageSdkError } from '../../client/errors.js';
+/** Shared exact-range Rent calculation, including the account overhead. */
+export declare function rentMinimumBalance(rate: bigint, threshold: number, length: number, address?: Address): bigint;
+export declare const SYSVAR_OWNER: Address;
+export declare const RENT_ADDRESS: Address;
+/** Validated Rent inputs and the existing minimum-balance callable. */
+export interface RentCalculation {
+    (length: number): bigint;
+    readonly rentLamportsPerByteYear: bigint;
+    readonly rentExemptionThreshold: number;
+}
+export declare function readRent(account: RawAccount): RentCalculation;
+/** Internal estimate-data failure; never used for transport or lifecycle errors. */
+export declare class RentCalculationError extends SageSdkError {
+    constructor(message: string, address: Address);
+}
+//# sourceMappingURL=rent.d.ts.map

package/dist/internal/planning/rent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rent.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/rent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,OAAsB,GAC9B,MAAM,CAcR;AAED,eAAO,MAAM,YAAY,EAC0B,OAAO,CAAC;AAE3D,eAAO,MAAM,YAAY,EAC0B,OAAO,CAAC;AAE3D,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;CACzC;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,eAAe,CA6B7D;AAMD,oFAAoF;AACpF,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;CAG9C"}

package/dist/internal/planning/rent.js

@@ -0,0 +1,35 @@
+import { SageSdkError } from '../../client/errors.js';
+/** Shared exact-range Rent calculation, including the account overhead. */
+export function rentMinimumBalance(rate, threshold, length, address = RENT_ADDRESS) {
+    const base = (BigInt(length) + 128n) * rate;
+    const result = Number(base) * threshold;
+    if (base > BigInt(Number.MAX_SAFE_INTEGER) ||
+        !Number.isFinite(result) ||
+        result < 0 ||
+        result > Number.MAX_SAFE_INTEGER)
+        throw new RentCalculationError('Account storage funding exceeds the supported exact calculation range. Use a supported Rent configuration before planning this action.', address);
+    return BigInt(Math.trunc(result));
+}
+export const SYSVAR_OWNER = 'Sysvar1111111111111111111111111111111111111';
+export const RENT_ADDRESS = 'SysvarRent111111111111111111111111111111111';
+export function readRent(account) {
+    if (account.owner !== SYSVAR_OWNER ||
+        account.executable ||
+        account.data.length !== 17)
+        rentFailure('The Rent sysvar has an unexpected owner or layout. Refresh the configured deployment before calculating storage funding.', account.address);
+    const view = new DataView(account.data.buffer, account.data.byteOffset, account.data.byteLength);
+    const rate = view.getBigUint64(0, true), threshold = view.getFloat64(8, true);
+    if (!Number.isFinite(threshold) || threshold < 0 || view.getUint8(16) > 100)
+        rentFailure('The Rent sysvar contains unsupported values. Refresh the deployment or use a supported configuration before planning this action.', account.address);
+    return Object.freeze(Object.assign((length) => rentMinimumBalance(rate, threshold, length, account.address), { rentLamportsPerByteYear: rate, rentExemptionThreshold: threshold }));
+}
+function rentFailure(message, address) {
+    throw new RentCalculationError(message, address);
+}
+/** Internal estimate-data failure; never used for transport or lifecycle errors. */
+export class RentCalculationError extends SageSdkError {
+    constructor(message, address) {
+        super('ACTION_PRECONDITION_FAILED', message, { address });
+    }
+}
+//# sourceMappingURL=rent.js.map

package/dist/internal/planning/rent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rent.js","sourceRoot":"","sources":["../../../src/internal/planning/rent.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,2EAA2E;AAC3E,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,SAAiB,EACjB,MAAc,EACd,UAAmB,YAAY;IAE/B,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAC5C,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;IACxC,IACE,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC;QACtC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;QACxB,MAAM,GAAG,CAAC;QACV,MAAM,GAAG,MAAM,CAAC,gBAAgB;QAEhC,MAAM,IAAI,oBAAoB,CAC5B,wIAAwI,EACxI,OAAO,CACR,CAAC;IACJ,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GACvB,6CAAwD,CAAC;AAE3D,MAAM,CAAC,MAAM,YAAY,GACvB,6CAAwD,CAAC;AAS3D,MAAM,UAAU,QAAQ,CAAC,OAAmB;IAC1C,IACE,OAAO,CAAC,KAAK,KAAK,YAAY;QAC9B,OAAO,CAAC,UAAU;QAClB,OAAO,CAAC,IAAI,CAAC,MAAM,KAAK,EAAE;QAE1B,WAAW,CACT,0HAA0H,EAC1H,OAAO,CAAC,OAAO,CAChB,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,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,IAAI,CAAC,EACrC,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,GAAG;QACzE,WAAW,CACT,mIAAmI,EACnI,OAAO,CAAC,OAAO,CAChB,CAAC;IACJ,OAAO,MAAM,CAAC,MAAM,CAClB,MAAM,CAAC,MAAM,CACX,CAAC,MAAc,EAAE,EAAE,CACjB,kBAAkB,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EAC9D,EAAE,uBAAuB,EAAE,IAAI,EAAE,sBAAsB,EAAE,SAAS,EAAE,CACrE,CACF,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,OAAe,EAAE,OAAgB;IACpD,MAAM,IAAI,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AACnD,CAAC;AAED,oFAAoF;AACpF,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACpD,YAAY,OAAe,EAAE,OAAgB;QAC3C,KAAK,CAAC,4BAA4B,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAC5D,CAAC;CACF"}

package/dist/internal/planning/research-unlock.d.ts

@@ -0,0 +1,60 @@
+import { type Address } from '@solana/kit';
+import type { RawAccount } from '../../client/contracts.js';
+import type { PlanPrecondition, PlanStep } from '../../planning/index.js';
+import type { GameResearchUnlockRule, GameXpCategory } from '../c4/game.js';
+/** Persisted research unlock guard: one exact next level of one node. */
+export type ResearchUnlockGuard = Extract<PlanPrecondition, {
+    readonly kind: 'research-unlock';
+}>;
+/** Caller intent before planning fills the observed sequences and debit. */
+export interface ResearchUnlockIntent {
+    readonly game: Address;
+    readonly profile: Address;
+    readonly authority: Address;
+    readonly keyIndex: number;
+    readonly system: Address;
+    readonly nodeId: number;
+    readonly level: number;
+    readonly researchSequenceId?: number;
+    readonly xpSequenceId?: number;
+    readonly maximumAtlasDebit?: bigint;
+}
+/** Canonical accounts the unlock reads and writes. */
+export interface ResearchUnlockAccounts {
+    readonly character: Address;
+    readonly starbasePlayer: Address;
+    readonly currencyCache: Address;
+    readonly clock: Address;
+}
+/** Validated rule, resulting level and exact costs of one unlock. */
+export interface ResearchUnlockSpend {
+    readonly rule: GameResearchUnlockRule;
+    readonly level: number;
+    readonly atlasDebit: bigint;
+    readonly cargo: readonly {
+        readonly cargoId: number;
+        readonly quantityRaw: bigint;
+    }[];
+    readonly points: readonly {
+        readonly category: GameXpCategory;
+        readonly costRaw: bigint;
+    }[];
+}
+/** Derives the canonical Character, Starbase Player and Currency Cache. */
+export declare function resolveResearchUnlock(intent: {
+    readonly game: Address;
+    readonly profile: Address;
+    readonly system: Address;
+}): Promise<ResearchUnlockAccounts>;
+/** Validates one next-level unlock against fresh accounts and Game rules and
+ * returns its exact costs. Planning and execution share every check; an
+ * intent carrying observed sequences and a debit also requires them to hold. */
+export declare function validateResearchUnlock(intent: ResearchUnlockIntent, resolved: ResearchUnlockAccounts, accounts: ReadonlyMap<Address, RawAccount | undefined>, rules: {
+    readonly sequenceId: number;
+    readonly xpSequenceId: number;
+    readonly rules: readonly GameResearchUnlockRule[];
+}): Promise<ResearchUnlockSpend>;
+/** Binds every research unlock instruction to exactly one persisted guard:
+ * direct key, accounts, roles, key index and node must all match. */
+export declare function validateResearchUnlockInstructions(steps: readonly PlanStep[], preconditions: readonly PlanPrecondition[]): void;
+//# sourceMappingURL=research-unlock.d.ts.map

package/dist/internal/planning/research-unlock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-unlock.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/research-unlock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAW1E,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAsB5E,yEAAyE;AACzE,MAAM,MAAM,mBAAmB,GAAG,OAAO,CACvC,gBAAgB,EAChB;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,CACrC,CAAC;AAEF,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,sDAAsD;AACtD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS;QACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,EAAE,CAAC;IACJ,QAAQ,CAAC,MAAM,EAAE,SAAS;QACxB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;QAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,EAAE,CAAC;CACL;AAkCD,2EAA2E;AAC3E,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAWlC;AAED;;gFAEgF;AAChF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,oBAAoB,EAC5B,QAAQ,EAAE,sBAAsB,EAChC,QAAQ,EAAE,WAAW,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC,EACtD,KAAK,EAAE;IACL,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACnD,GACA,OAAO,CAAC,mBAAmB,CAAC,CAsN9B;AAgBD;qEACqE;AACrE,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,aAAa,EAAE,SAAS,gBAAgB,EAAE,GACzC,IAAI,CA+CN"}

package/dist/internal/planning/research-unlock.js

@@ -0,0 +1,208 @@
+import { AccountRole, isOffCurveAddress } from '@solana/kit';
+import { SageSdkError } from '../../client/errors.js';
+import { characterAccountDefinition, findCharacterPda, } from '../c4/character.js';
+import { deriveCurrencyCache, validateCurrencyCache, } from '../c4/currency-cache.js';
+import { UNLOCK_RESEARCH_NODE_DISCRIMINATOR } from '../c4/discriminators.js';
+import { profileAccountDefinition } from '../c4/identity.js';
+import { PROFILE_SCOPE, SAGE_SCOPE } from '../c4/profile-permissions.js';
+import { PLAYER_PROFILE_PROGRAM_ADDRESS, SAGE_PROGRAM_ADDRESS, } from '../c4/runtime-bindings.js';
+import { deriveStarbasePlayerAddress, starbasePlayerAccountDefinition, } from '../c4/starbase.js';
+import { deriveStarSystemAddress, starSystemAccountDefinition, } from '../c4/world.js';
+import { CLOCK_ADDRESS, readClock } from './faction-enrollment.js';
+import { directProfileKey, grantsPermission, profileKeyExpired, } from './profile-key.js';
+const BASIS_POINTS = 10000n;
+// SAGE doResearch permission bit (SAGE_FLAGS.DO_RESEARCH).
+const DO_RESEARCH = 40n;
+const CAREERS = {
+    'council-rank': 'councilRank',
+    pilot: 'pilot',
+    'data-runner': 'dataRunner',
+    mining: 'mining',
+    building: 'building',
+    crafting: 'crafting',
+    combat: 'combat',
+};
+const LABELS = {
+    pilot: 'Pilot',
+    'data-runner': 'Data Runner',
+    mining: 'Mining',
+    building: 'Building',
+    crafting: 'Crafting',
+    combat: 'Combat',
+};
+function fail(address, message) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', message, { address });
+}
+/** Derives the canonical Character, Starbase Player and Currency Cache. */
+export async function resolveResearchUnlock(intent) {
+    const [character, [currencyCache]] = await Promise.all([
+        findCharacterPda(intent.profile, intent.game),
+        deriveCurrencyCache(intent.game),
+    ]);
+    return {
+        character,
+        starbasePlayer: await deriveStarbasePlayerAddress(intent.system, character),
+        currencyCache,
+        clock: CLOCK_ADDRESS,
+    };
+}
+/** Validates one next-level unlock against fresh accounts and Game rules and
+ * returns its exact costs. Planning and execution share every check; an
+ * intent carrying observed sequences and a debit also requires them to hold. */
+export async function validateResearchUnlock(intent, resolved, accounts, rules) {
+    const node = `Research node ${intent.nodeId}`;
+    if (isOffCurveAddress(intent.authority))
+        fail(intent.profile, 'Research requires an on-curve direct Profile authority. Select a current direct key and replan.');
+    const required = (address, name) => {
+        const raw = accounts.get(address);
+        if (!raw || raw.executable)
+            fail(address, `${name} ${address} is missing or executable. Select an existing Character, Star System and Starbase Player, then replan the research unlock.`);
+        return raw;
+    };
+    const profile = profileAccountDefinition.decode(required(intent.profile, 'Profile'));
+    const character = characterAccountDefinition.decode(required(resolved.character, 'Character'));
+    const system = starSystemAccountDefinition.decode(required(intent.system, 'Star System'));
+    const player = starbasePlayerAccountDefinition.decode(required(resolved.starbasePlayer, 'Starbase Player'));
+    await validateCurrencyCache(required(resolved.currencyCache, 'Currency Cache'), intent.game, 'research unlock');
+    const now = readClock(required(resolved.clock, 'Clock sysvar'));
+    if (character.game !== intent.game ||
+        character.playerProfile !== intent.profile)
+        fail(resolved.character, 'The Character belongs to a different Game or Profile. Refresh the canonical Character and replan the research unlock.');
+    if (system.game !== intent.game ||
+        (await deriveStarSystemAddress(system.game, system.systemId)) !==
+            intent.system ||
+        !system.starbase)
+        fail(intent.system, 'The selected System is not canonical for this Game or has no Starbase. Choose a Starbase System where the Character has a Starbase Player and replan.');
+    if (player.playerProfile !== intent.profile ||
+        player.character !== resolved.character ||
+        player.system !== intent.system)
+        fail(resolved.starbasePlayer, 'The Starbase Player has a different Profile, Character or System. Refresh the canonical Starbase Player and replan.');
+    if (player.sequenceId !== system.sequenceId)
+        fail(resolved.starbasePlayer, `The Starbase Player belongs to Starbase generation ${player.sequenceId}, but the Starbase at System ${intent.system} is at generation ${system.sequenceId}; the program rejects it as destroyed. Choose a System where the Character's Starbase Player is current and replan.`);
+    if ((intent.researchSequenceId !== undefined &&
+        rules.sequenceId !== intent.researchSequenceId) ||
+        (intent.xpSequenceId !== undefined &&
+            rules.xpSequenceId !== intent.xpSequenceId))
+        fail(intent.game, 'The Game research or XP definitions changed after planning. Replan to review the current requirements and costs before signing.');
+    if (character.modifiers.seqId !== rules.sequenceId ||
+        character.modifiers.unupdatedCount !== 0 ||
+        character.xp.seqId !== rules.xpSequenceId)
+        fail(resolved.character, `The Character is not synchronized with the current Game definitions (research ${character.modifiers.seqId} of ${rules.sequenceId} with ${character.modifiers.unupdatedCount} pending nodes, XP ${character.xp.seqId} of ${rules.xpSequenceId}). Synchronize the Character with the game client, then replan; this SDK does not plan synchronization.`);
+    const rule = rules.rules.find(({ id }) => id === intent.nodeId);
+    if (!rule)
+        fail(intent.game, `${node} is not in the current Game research catalog. Choose a node from getResearchCatalog and replan.`);
+    const unlocked = character.modifiers.unlockedNodes.includes(intent.nodeId);
+    const stored = character.modifiers.nodeLevels.find(({ nodeId }) => nodeId === intent.nodeId)?.level;
+    if (unlocked ? stored === 0 : stored !== undefined)
+        fail(resolved.character, `${node} has an inconsistent stored level on this Character. Synchronize the Character with the game client, then replan.`);
+    const current = unlocked ? (stored ?? 1) : 0;
+    if (rule.maxLevel !== 0 && current >= rule.maxLevel)
+        fail(resolved.character, `${node} "${rule.name}" is already at its maximum level ${rule.maxLevel}. Choose another node.`);
+    if (intent.level !== current + 1)
+        fail(resolved.character, `${node} "${rule.name}" is at level ${current}, so an unlock reaches level ${current + 1}, not ${intent.level}. Replan with level ${current + 1}.`);
+    const tags = character.modifiers.values.researchTags;
+    const missing = rule.requiredTagIds.filter((tag) => !tags.includes(tag));
+    if (missing.length > 0)
+        fail(resolved.character, `${node} "${rule.name}" requires every research tag in [${rule.requiredTagIds.join(', ')}]; the Character lacks [${missing.join(', ')}]. Unlock the nodes that grant them first, then replan.`);
+    for (const cost of rule.xpCosts) {
+        const field = CAREERS[cost.category];
+        if (field === undefined)
+            fail(intent.game, `${node} "${rule.name}" costs Daily XP, which this SDK has not qualified for research. Use the game client for this node.`);
+        const xp = character.xp[field];
+        const council = field === 'councilRank';
+        const label = LABELS[cost.category] ?? 'Council Rank';
+        const earn = council ? 'career levels toward Renown' : `${label} XP`;
+        if (xp.level < cost.minimumLevel)
+            fail(resolved.character, `${node} "${rule.name}" requires ${label} level ${cost.minimumLevel}; the Character is at level ${xp.level}. Earn ${earn}, then replan.`);
+        const earned = council ? xp.earned : BigInt(xp.level);
+        const available = earned > xp.spent ? earned - xp.spent : 0n;
+        const unit = council
+            ? 'Renown'
+            : `${label} research point${cost.costRaw === 1n ? '' : 's'}`;
+        if (available < cost.costRaw)
+            fail(resolved.character, `${node} "${rule.name}" costs ${cost.costRaw} ${unit}; the Character has ${available} available. Earn ${earn}, then replan.`);
+    }
+    const growth = BASIS_POINTS + BigInt(rule.costGrowthBasisPoints) * BigInt(current);
+    if (current > 0 &&
+        rule.costGrowthBasisPoints > 0 &&
+        rule.cargoCosts.length > 0)
+        fail(intent.game, `${node} "${rule.name}" grows cargo costs per level, which this SDK has not qualified. Use the game client for this level.`);
+    if ((rule.atlasCostRaw * growth) % BASIS_POINTS !== 0n)
+        fail(intent.game, `${node} "${rule.name}" has a fractional grown ATLAS cost at level ${current}, whose rounding this SDK has not qualified. Use the game client for this level.`);
+    const atlasDebit = (rule.atlasCostRaw * growth) / BASIS_POINTS;
+    if (intent.maximumAtlasDebit !== undefined &&
+        atlasDebit > intent.maximumAtlasDebit)
+        fail(intent.game, `${node} "${rule.name}" now costs ${atlasDebit} ATLAS Floyds, above the ${intent.maximumAtlasDebit} this Plan approved. Replan and review the cost before signing.`);
+    if (character.atlasRaw < atlasDebit)
+        fail(resolved.character, `${node} "${rule.name}" costs ${atlasDebit} ATLAS Floyds; the Character holds ${character.atlasRaw}. Add ATLAS to the Character, then replan.`);
+    for (const { cargoId, quantityRaw } of rule.cargoCosts) {
+        const held = player.cargo.amounts.find((amount) => amount.cargoId === cargoId)
+            ?.amount ?? 0n;
+        if (held < quantityRaw)
+            fail(resolved.starbasePlayer, `${node} "${rule.name}" consumes ${quantityRaw} of cargo ${cargoId} from the Starbase Player; it holds ${held}. Move that cargo to the Starbase Player at System ${intent.system}, then replan.`);
+    }
+    const key = directProfileKey(profile.keys, intent.keyIndex, intent.authority);
+    if (!key)
+        fail(intent.profile, 'The selected direct Profile key is absent or belongs to another authority. Select the current key index for this authority and replan.');
+    if (profileKeyExpired(key, now))
+        fail(intent.profile, 'The selected Profile key has expired. Renew it or select a current direct key and replan the research unlock.');
+    if (!grantsPermission(key, PROFILE_SCOPE, 0n) &&
+        !grantsPermission(key, SAGE_SCOPE, DO_RESEARCH))
+        fail(intent.profile, 'The selected key cannot do research. Use a direct Profile AUTH key or a SAGE doResearch key and replan.');
+    return {
+        rule,
+        level: current + 1,
+        atlasDebit,
+        cargo: rule.cargoCosts,
+        points: rule.xpCosts.map(({ category, costRaw }) => ({
+            category,
+            costRaw,
+        })),
+    };
+}
+function isUnlock(step) {
+    const { instruction } = step;
+    return (instruction.programAddress === SAGE_PROGRAM_ADDRESS &&
+        UNLOCK_RESEARCH_NODE_DISCRIMINATOR.every((byte, index) => instruction.data?.[index] === byte));
+}
+function u16(data, offset) {
+    return data[offset] | (data[offset + 1] << 8);
+}
+/** Binds every research unlock instruction to exactly one persisted guard:
+ * direct key, accounts, roles, key index and node must all match. */
+export function validateResearchUnlockInstructions(steps, preconditions) {
+    const guards = preconditions.filter((guard) => guard.kind === 'research-unlock');
+    const unlocks = steps.filter(isUnlock);
+    const characters = new Set(guards.map(({ address }) => address));
+    if (unlocks.length !== guards.length || characters.size !== guards.length)
+        throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'Every research unlock instruction requires exactly one matching research-unlock guard, with at most one unlock per Character. Recreate the Plan with planUnlockResearchNode.');
+    const remaining = [...guards];
+    for (const { instruction, signers } of unlocks) {
+        const data = instruction.data;
+        const metas = instruction.accounts;
+        const index = remaining.findIndex((guard) => {
+            const expected = [
+                [guard.authority, AccountRole.READONLY_SIGNER],
+                [guard.profile, AccountRole.WRITABLE],
+                [SAGE_PROGRAM_ADDRESS, AccountRole.READONLY],
+                [PLAYER_PROFILE_PROGRAM_ADDRESS, AccountRole.READONLY],
+                [guard.address, AccountRole.WRITABLE],
+                [guard.game, AccountRole.READONLY],
+                [guard.starbasePlayer, AccountRole.WRITABLE],
+                [guard.system, AccountRole.READONLY],
+                [guard.currencyCache, AccountRole.WRITABLE],
+            ];
+            return (data?.length === 12 &&
+                u16(data, 8) === guard.keyIndex &&
+                u16(data, 10) === guard.nodeId &&
+                metas?.length === expected.length &&
+                expected.every(([address, role], at) => metas[at].address === address && metas[at].role === role) &&
+                signers.length === 1 &&
+                signers[0] === guard.authority);
+        });
+        if (index < 0)
+            throw new SageSdkError('ACTION_PRECONDITION_FAILED', 'A research unlock instruction does not match its persisted Profile key, Character, Starbase Player, System, Currency Cache or node. Recreate the Plan with planUnlockResearchNode.');
+        remaining.splice(index, 1);
+    }
+}
+//# sourceMappingURL=research-unlock.js.map

package/dist/internal/planning/research-unlock.js.map

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

package/dist/internal/planning/respawn-guards.d.ts

@@ -0,0 +1,3 @@
+import type { PlanPrecondition, PlanStep } from '../../planning/index.js';
+export declare function validateRespawnInstructions(steps: readonly PlanStep[], guards: readonly PlanPrecondition[]): void;
+//# sourceMappingURL=respawn-guards.d.ts.map

package/dist/internal/planning/respawn-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"respawn-guards.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/respawn-guards.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAO1E,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAClC,IAAI,CA8CN"}

package/dist/internal/planning/respawn-guards.js

@@ -0,0 +1,42 @@
+import { AccountRole } from '@solana/kit';
+import { InvalidActionInputError } from '../../client/errors.js';
+import { SAGE_PROGRAM_ADDRESS } from '../c4/runtime-bindings.js';
+import { IDLE_TO_RESPAWN_DISCRIMINATOR, RESPAWN_TO_DOCKED_DISCRIMINATOR, } from '../c4/discriminators.js';
+export function validateRespawnInstructions(steps, guards) {
+    const selected = guards.filter((g) => g.kind === 'fleet-respawn');
+    const recovery = steps.filter(({ instruction: i }) => i.programAddress === SAGE_PROGRAM_ADDRESS &&
+        [IDLE_TO_RESPAWN_DISCRIMINATOR, RESPAWN_TO_DOCKED_DISCRIMINATOR].some((d) => d.every((v, n) => i.data?.[n] === v)));
+    if (!selected.length && !recovery.length)
+        return;
+    const bad = () => {
+        throw new InvalidActionInputError('respawn', undefined, 'one standalone recovery instruction with its matching safeguard', 'Recreate the recovery Plan. Start and timed completion are separate transactions; do not combine recovery with other actions.');
+    };
+    if (steps.length !== 1 || recovery.length !== 1 || selected.length !== 1)
+        bad();
+    const guard = selected[0];
+    const step = recovery[0];
+    const i = step.instruction;
+    const start = guard.phase === 'start';
+    const d = start
+        ? IDLE_TO_RESPAWN_DISCRIMINATOR
+        : RESPAWN_TO_DOCKED_DISCRIMINATOR;
+    const accounts = i.accounts;
+    if (!i.data ||
+        i.data.length !== 10 ||
+        !d.every((v, n) => i.data[n] === v) ||
+        i.data[8] + i.data[9] * 256 !== guard.keyIndex ||
+        accounts?.length !== (start ? 11 : 8) ||
+        step.signers.length !== 1 ||
+        step.signers[0] !== guard.authority)
+        bad();
+    for (const [n, address, role] of [
+        [0, guard.authority, AccountRole.READONLY_SIGNER],
+        [1, guard.profile, AccountRole.WRITABLE],
+        [start ? 5 : 4, guard.address, AccountRole.WRITABLE],
+        [start ? 8 : 5, guard.game, AccountRole.READONLY],
+        [6, guard.system, AccountRole.READONLY],
+    ])
+        if (accounts[n]?.address !== address || accounts[n]?.role !== role)
+            bad();
+}
+//# sourceMappingURL=respawn-guards.js.map

package/dist/internal/planning/respawn-guards.js.map

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