@aephia/atlas-kit 0.6.0-next.14 → 0.6.0-next.140

package/dist/internal/planning/profile-storage-funding.js

@@ -0,0 +1,58 @@
+import { SageSdkError } from '../../client/errors.js';
+import { profileAccountDefinition } from '../c4/identity.js';
+import { PROFILE_SCOPE } from '../c4/profile-permissions.js';
+import { directProfileKey, grantsPermission, hasPermissionBit, } from './profile-key.js';
+import { readRent } from './rent.js';
+// Profile drainSolVault permission bit, any scope.
+const DRAIN_SOL_VAULT = 63n;
+function fail(address, message) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', message, { address });
+}
+/** Refuses a direct Profile key that can fund none of an action's positive
+ * storage debit: the program withdraws it from the Profile vault with the
+ * signing key, which must be Profile AUTH or also hold `drainSolVault` (any
+ * scope). A delegated or certificate key is left to the program. Returns
+ * whether the key is a direct Profile key. */
+export function requireStorageFundingKey(input) {
+    const key = directProfileKey(profileAccountDefinition.decode(input.profileRaw).keys, input.keyIndex, input.authority);
+    if (input.profileDebit > 0n &&
+        key &&
+        !grantsPermission(key, PROFILE_SCOPE, 0n) &&
+        !hasPermissionBit(key, DRAIN_SOL_VAULT))
+        fail(input.profileRaw.address, `The ${input.action} needs ${input.profileDebit} Profile lamports for account storage, which the program withdraws from the Profile vault with the signing key; this key lacks drainSolVault. Use a direct Profile AUTH key or a key that also holds drainSolVault, then replan.`);
+    return key !== undefined;
+}
+/** Checks that the signing key and the Profile can fund one action's storage
+ * debit. A zero debit withdraws nothing, so it needs neither `drainSolVault`
+ * nor Profile excess lamports. */
+export function checkProfileStorageFunding(input) {
+    const { profileRaw, action, profileDebit } = input;
+    const rent = readRent(input.rentRaw);
+    if (input.maximumProfileDebit !== undefined &&
+        profileDebit > input.maximumProfileDebit)
+        fail(profileRaw.address, `The ${action} now needs ${profileDebit} Profile lamports for account storage, above the ${input.maximumProfileDebit} this Plan approved. An earlier action in the same Plan may use storage it was planned against: execute the actions as separate Plans, or refresh the accounts and replan, then review the storage funding before signing.`);
+    const profileReserve = rent(profileRaw.data.length);
+    const direct = requireStorageFundingKey(input);
+    if (profileDebit > 0n && profileRaw.lamports < profileReserve + profileDebit)
+        fail(profileRaw.address, `The ${action} needs ${profileDebit} Profile lamports for account storage above the Profile's own ${profileReserve}-lamport rent reserve; the Profile holds ${profileRaw.lamports}. Add ${profileReserve + profileDebit - profileRaw.lamports} lamports to the Profile, then replan.`);
+    return { profileDebit, profileReserve, direct };
+}
+/** Builds the guard and the summary sentence for one action's storage funding. */
+export function profileStorageFundingGuard(input) {
+    const { profileDebit } = input.funding;
+    const disclosure = profileDebit > 0n
+        ? `The program funds ${profileDebit} lamports of account storage from Profile ${input.profile}'s vault with the signing key (a locked rent deposit, separate from transaction fees).${input.funding.direct ? '' : ' The selected key is not a direct Profile key, so its drainSolVault permission is checked by the program, not locally.'}`
+        : `This action needs no Profile storage funding at the observed account sizes and balances.`;
+    return {
+        disclosure,
+        guard: {
+            kind: 'profile-storage-funding',
+            address: input.address,
+            profile: input.profile,
+            authority: input.authority,
+            maximumProfileDebit: profileDebit,
+            describes: `Account storage funding from the Profile vault stays at most ${profileDebit} lamports, and the signing key and Profile balance can fund it.`,
+        },
+    };
+}
+//# sourceMappingURL=profile-storage-funding.js.map

package/dist/internal/planning/profile-storage-funding.js.map

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

package/dist/internal/planning/recipe-state.d.ts

@@ -0,0 +1,9 @@
+import type { RawAccount } from '../../client/contracts.js';
+/** Preserve the complete pinned Recipe encoding except its shared usage counter. */
+export declare function hashRecipeConfiguration(account: RawAccount): Promise<string>;
+/** Each Crafting Process start consumes exactly one Recipe use, whatever its
+ * quantity; completing or cancelling an existing job reserves none. A Recipe is
+ * usable only while its usage count is below its limit, so a stored limit of
+ * `0` is never usable. */
+export declare function validateRecipeUsage(account: RawAccount, requiredUses: bigint): void;
+//# sourceMappingURL=recipe-state.d.ts.map

package/dist/internal/planning/recipe-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipe-state.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/recipe-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAS5D,oFAAoF;AACpF,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,MAAM,CAAC,CAKjB;AAED;;;0BAG0B;AAC1B,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,UAAU,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI,CAWN"}

package/dist/internal/planning/recipe-state.js

@@ -0,0 +1,23 @@
+import { SageSdkError } from '../../client/errors.js';
+import { readRecipeName, readRecipeUsage, RECIPE_USAGE_COUNT_OFFSET, } from '../c4/crafting.js';
+import { hashAccountState } from './account-state.js';
+/** Preserve the complete pinned Recipe encoding except its shared usage counter. */
+export async function hashRecipeConfiguration(account) {
+    readRecipeUsage(account);
+    const data = new Uint8Array(account.data);
+    data.fill(0, RECIPE_USAGE_COUNT_OFFSET, RECIPE_USAGE_COUNT_OFFSET + 8);
+    return hashAccountState(account.owner, data);
+}
+/** Each Crafting Process start consumes exactly one Recipe use, whatever its
+ * quantity; completing or cancelling an existing job reserves none. A Recipe is
+ * usable only while its usage count is below its limit, so a stored limit of
+ * `0` is never usable. */
+export function validateRecipeUsage(account, requiredUses) {
+    if (requiredUses === 0n)
+        return;
+    const recipe = readRecipeUsage(account);
+    const remaining = recipe.limit > recipe.count ? recipe.limit - recipe.count : 0n;
+    if (requiredUses > remaining)
+        throw new SageSdkError('ACTION_PRECONDITION_FAILED', `Recipe ${readRecipeName(account) || account.address} usage limit has remaining ${remaining}, but a Crafting Process start requested ${requiredUses}. The Recipe's uses are exhausted; choose another active Recipe, then recreate the Plan before retrying.`, { address: account.address });
+}
+//# sourceMappingURL=recipe-state.js.map

package/dist/internal/planning/recipe-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipe-state.js","sourceRoot":"","sources":["../../../src/internal/planning/recipe-state.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EACL,cAAc,EACd,eAAe,EACf,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAAmB;IAEnB,eAAe,CAAC,OAAO,CAAC,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,yBAAyB,EAAE,yBAAyB,GAAG,CAAC,CAAC,CAAC;IACvE,OAAO,gBAAgB,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AAC/C,CAAC;AAED;;;0BAG0B;AAC1B,MAAM,UAAU,mBAAmB,CACjC,OAAmB,EACnB,YAAoB;IAEpB,IAAI,YAAY,KAAK,EAAE;QAAE,OAAO;IAChC,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,SAAS,GACb,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACjE,IAAI,YAAY,GAAG,SAAS;QAC1B,MAAM,IAAI,YAAY,CACpB,4BAA4B,EAC5B,UAAU,cAAc,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,OAAO,8BAA8B,SAAS,4CAA4C,YAAY,0GAA0G,EAC7P,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAC7B,CAAC;AACN,CAAC"}

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

@@ -0,0 +1,37 @@
+import { type Address } from '@solana/kit';
+import type { SageContext } from '../../client/contracts.js';
+import type { PlanPrecondition, PlanStep } from '../../planning/index.js';
+/** Baseline-record hints; the program reads them only under an Active catalog. */
+export declare const DISABLED_RENT_HINTS: readonly number[];
+export interface DisabledStakeRent {
+    readonly rentCatalog: Address;
+    readonly rentAuthority: Address;
+}
+export interface DisabledLevelRent {
+    readonly rentCatalog: Address;
+    readonly rentHead: Address;
+}
+/** Requires Disabled rent for an existing Claim Stake: neither the Game's rent
+ * catalog nor the stake's settlement authority exists. */
+export declare function requireDisabledStakeRent(ctx: SageContext, game: Address, stake: Address, action: string): Promise<{
+    readonly accounts: DisabledStakeRent;
+    readonly guards: readonly PlanPrecondition[];
+}>;
+/** Requires that a new Claim Stake address has no rent settlement authority. */
+export declare function requireNewStakeRent(ctx: SageContext, stake: Address): Promise<{
+    readonly rentAuthority: Address;
+    readonly guards: readonly PlanPrecondition[];
+}>;
+/** 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 declare function requireDisabledLevelRent(ctx: SageContext, game: Address, system: {
+    readonly address: Address;
+    readonly systemId: number;
+}, action: string): Promise<{
+    readonly accounts: DisabledLevelRent;
+    readonly guards: readonly PlanPrecondition[];
+}>;
+/** Binds every rent account of a recognized instruction to an absence guard
+ * and rejects rent pages, supplied optional rent accounts and nonzero hints. */
+export declare function validateRentInstructions(steps: readonly PlanStep[], guards: readonly PlanPrecondition[]): void;
+//# sourceMappingURL=rent-catalog.d.ts.map

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":"AAAA,OAAO,EAAE,WAAW,EAAgB,MAAM,aAAa,CAAC;AAGxD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE,OAAO,EACL,6BAA6B,EAC7B,gDAAgD,EAChD,sCAAsC,EACtC,8CAA8C,EAC9C,uCAAuC,EACvC,yCAAyC,EACzC,iDAAiD,EACjD,+CAA+C,GAChD,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,oCAAoC,GACrC,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,kFAAkF;AAClF,MAAM,CAAC,MAAM,mBAAmB,GAAsB,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAE/E,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAkB5B,KAAK,UAAU,aAAa,CAC1B,GAAgB,EAChB,QAAkC;IAElC,MAAM,GAAG,GAAG,MAAM,sBAAsB,CACtC,GAAG,EACH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,CACvC,CAAC;IACF,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,EAAE;QAC/C,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,SAAS;YAC1B,MAAM,IAAI,YAAY,CAAC,4BAA4B,EAAE,OAAO,EAAE;gBAC5D,OAAO;aACR,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,CAC7C,yBAAyB,CAAC,OAAO,EAAE,SAAS,CAAC,CAC9C,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CACrB,WAAoB,EACpB,IAAa,EACb,MAAc;IAEd,OAAO;QACL,OAAO,EAAE,WAAW;QACpB,OAAO,EAAE,QAAQ,IAAI,qBAAqB,WAAW,2CAA2C,MAAM,oFAAoF,MAAM,GAAG;QACnM,SAAS,EAAE,gBAAgB,WAAW,0CAA0C;KACjF,CAAC;AACJ,CAAC;AAED;0DAC0D;AAC1D,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,GAAgB,EAChB,IAAa,EACb,KAAc,EACd,MAAc;IAKd,MAAM,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACzD,wBAAwB,CAAC,IAAI,CAAC;QAC9B,oCAAoC,CAAC,KAAK,CAAC;KAC5C,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE;QACtC,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC;QACzC;YACE,OAAO,EAAE,aAAa;YACtB,OAAO,EAAE,eAAe,KAAK,kCAAkC,aAAa,0FAA0F,MAAM,GAAG;YAC/K,SAAS,EAAE,eAAe,KAAK,8BAA8B,aAAa,kBAAkB;SAC7F;KACF,CAAC,CAAC;IACH,OAAO,EAAE,QAAQ,EAAE,EAAE,aAAa,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,CAAC;AAC9D,CAAC;AAED,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,GAAgB,EAChB,KAAc;IAKd,MAAM,CAAC,aAAa,CAAC,GAAG,MAAM,oCAAoC,CAAC,KAAK,CAAC,CAAC;IAC1E,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE;QACtC;YACE,OAAO,EAAE,aAAa;YACtB,OAAO,EAAE,6BAA6B,aAAa,+CAA+C,KAAK,yEAAyE;YAChL,SAAS,EAAE,mBAAmB,KAAK,8BAA8B,aAAa,kBAAkB;SACjG;KACF,CAAC,CAAC;IACH,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;AACnC,CAAC;AAED;qEACqE;AACrE,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,GAAgB,EAChB,IAAa,EACb,MAAgE,EAChE,MAAc;IAKd,MAAM,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACpD,wBAAwB,CAAC,IAAI,CAAC;QAC9B,0BAA0B,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC;KAClD,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE;QACtC,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC;QACzC;YACE,OAAO,EAAE,QAAQ;YACjB,OAAO,EAAE,eAAe,MAAM,CAAC,OAAO,oCAAoC,QAAQ,WAAW,MAAM,uFAAuF,MAAM,GAAG;YACnM,SAAS,EAAE,eAAe,MAAM,CAAC,OAAO,gCAAgC,QAAQ,kBAAkB;SACnG;KACF,CAAC,CAAC;IACH,OAAO,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,CAAC;AACzD,CAAC;AAeD,8EAA8E;AAC9E,4EAA4E;AAC5E,6CAA6C;AAC7C,SAAS,WAAW;IAClB,OAAO;QACL,CAAC,sCAAsC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACrE;YACE,iDAAiD;YACjD,EAAE;YACF,CAAC,CAAC;YACF,EAAE;YACF,EAAE;YACF,KAAK;YACL,CAAC;SACF;QACD;YACE,yCAAyC;YACzC,EAAE;YACF,EAAE;YACF,EAAE;YACF,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;YACZ,IAAI;YACJ,CAAC;SACF;QACD;YACE,gDAAgD;YAChD,EAAE;YACF,EAAE;YACF,EAAE;YACF,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;YACZ,IAAI;YACJ,EAAE;SACH;QACD;YACE,uCAAuC;YACvC,EAAE;YACF,EAAE;YACF,EAAE;YACF,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;YACZ,IAAI;YACJ,EAAE;SACH;QACD;YACE,+CAA+C;YAC/C,EAAE;YACF,EAAE;YACF,EAAE;YACF,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;YACZ,IAAI;YACJ,CAAC;SACF;QACD;YACE,8CAA8C;YAC9C,EAAE;YACF,EAAE;YACF,EAAE;YACF,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;YACpB,IAAI;YACJ,EAAE;SACH;QACD,CAAC,6BAA6B,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;KACjE,CAAC;AACJ,CAAC;AAED;gFACgF;AAChF,MAAM,UAAU,wBAAwB,CACtC,KAA0B,EAC1B,MAAmC;IAEnC,KAAK,MAAM,CAAC,KAAK,EAAE,EAAE,WAAW,EAAE,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,WAAW,CAAC,cAAc,KAAK,oBAAoB;YAAE,SAAS;QAClE,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC;QAC9B,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,EAAE,EAAE,CACpD,aAAa,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,CAC/D,CAAC;QACF,IAAI,CAAC,MAAM;YAAE,SAAS;QACtB,MAAM,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,GAAG,MAAM,CAAC;QACxE,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,CAAC;QACnC,MAAM,OAAO,GAAG,CAAC,EAAU,EAAE,IAAiB,EAAE,EAAE,CAChD,KAAM,CAAC,EAAE,CAAE,CAAC,IAAI,KAAK,IAAI;YACzB,MAAM,CAAC,IAAI,CACT,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,gBAAgB,IAAI,CAAC,CAAC,OAAO,KAAK,KAAM,CAAC,EAAE,CAAE,CAAC,OAAO,CACxE,CAAC;QACJ,IACE,CAAC,IAAI;YACL,CAAC,KAAK;YACN,KAAK,CAAC,MAAM,KAAK,KAAK;YACtB,CAAC,UAAU,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC;YAChD,CAAC,KAAK;gBACJ,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,gBAAgB;oBACjC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,GAAG,gBAAgB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YACjE,OAAO,CAAC,IAAI,CACV,CAAC,EAAE,EAAE,EAAE,CACL,KAAK,CAAC,EAAE,CAAE,CAAC,OAAO,KAAK,oBAAoB;gBAC3C,KAAK,CAAC,EAAE,CAAE,CAAC,IAAI,KAAK,WAAW,CAAC,QAAQ,CAC3C;YACD,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;YACzD,CAAC,OAAO,CAAC,QAAQ,EAAE,WAAW,CAAC,QAAQ,CAAC;YAExC,MAAM,IAAI,YAAY,CACpB,4BAA4B,EAC5B,QAAQ,KAAK,wLAAwL,CACtM,CAAC;IACN,CAAC;AACH,CAAC"}

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,69 @@
+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;
+    readonly maximumProfileDebit?: bigint;
+}
+/** Canonical accounts the unlock reads and writes. */
+export interface ResearchUnlockAccounts {
+    readonly character: Address;
+    readonly starbasePlayer: Address;
+    readonly currencyCache: Address;
+    readonly clock: Address;
+    readonly rent: 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;
+    }[];
+    /** Bytes the unlock adds to the Character. */
+    readonly characterGrowthBytes: number;
+    /** Conservative Profile lamport debit for Character and Starbase Player
+     * storage; surplus refunds to the Profile are not credited. */
+    readonly profileDebit: bigint;
+    /** The Profile's own rent minimum, which the vault withdrawal preserves. */
+    readonly profileReserve: 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":"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"}