@aephia/atlas-kit 0.6.0-next.15 → 0.6.0-next.151

package/dist/internal/planning/region-access.js

@@ -0,0 +1,94 @@
+import { SageSdkError } from '../../client/errors.js';
+import { deriveRegionTrackerAddress, regionTrackerAccountDefinition, } from '../c4/factions.js';
+import { fleetAccountDefinition } from '../c4/fleet.js';
+import { regionContainsCoordinate } from '../c4/region-geometry.js';
+import { getFleetDecoder, getRegionTrackerDecoder, getStarSystemDecoder, } from '../c4/runtime-bindings.js';
+import { starSystemAccountDefinition } from '../c4/world.js';
+import { hashAccountState } from './account-state.js';
+/** Decodes the canonical version 0 RegionTracker, or refuses with `message`. */
+async function decodeTracker(tracker, game, valid, message) {
+    const decoded = !tracker.executable &&
+        tracker.address === (await deriveRegionTrackerAddress(game))
+        ? regionTrackerAccountDefinition.decode(tracker)
+        : undefined;
+    if (!valid || decoded?.game !== game || decoded.version !== 0)
+        throw new SageSdkError('ACTION_PRECONDITION_FAILED', message, {
+            address: tracker.address,
+        });
+    return getRegionTrackerDecoder().decode(tracker.data);
+}
+function hashRegions(tracker, value) {
+    return hashAccountState(tracker.owner, new TextEncoder().encode(JSON.stringify(value, (_key, item) => typeof item === 'bigint' ? String(item) : item)));
+}
+/** The Regions containing a Star System's coordinate, in tracker order; an
+ * empty list is deep space. The tracker must be the canonical version 0
+ * account. */
+export async function regionsContainingSystem(tracker, system, game) {
+    const data = await decodeTracker(tracker, game, system !== undefined, 'The Star System is missing, or the RegionTracker is not the canonical version 0 account for this Game. Refresh world region data and recreate the Plan.');
+    starSystemAccountDefinition.validate(system);
+    const [x, y] = getStarSystemDecoder().decode(system.data).coordinates;
+    const coordinate = { x: x.raw, y: y.raw };
+    return data.regions.unsizedList.filter((region) => regionContainsCoordinate(region, coordinate));
+}
+/** Digest of the access data of every Region containing a Star System's
+ * coordinate: id, owner, safety status and risk zone, in tracker order. An
+ * empty list is deep space. Other Regions and their systems may change.
+ */
+export async function hashRegionAccess(tracker, system, game) {
+    const regions = await regionsContainingSystem(tracker, system, game);
+    return hashRegions(tracker, regions.map(({ id, owner, safetyStatus, riskZone }) => [
+        id,
+        owner,
+        safetyStatus,
+        riskZone,
+    ]));
+}
+/** A Fleet's exact action coordinate in `game`: its Idle location, or the end
+ * of the warp or subwarp a movement start settles first; `undefined` for any
+ * other state, another Game or a missing Fleet.
+ */
+export function fleetActionCoordinate(fleet, game) {
+    if (!fleet)
+        return undefined;
+    fleetAccountDefinition.validate(fleet);
+    const { gameId, location, state } = getFleetDecoder().decode(fleet.data);
+    const at = state.__kind === 'Idle'
+        ? location
+        : state.__kind === 'MoveWarp'
+            ? state.fields[0].to
+            : state.__kind === 'MoveSubwarp'
+                ? state.fields[0].journey.to
+                : undefined;
+    return gameId === game && at ? { x: at[0].raw, y: at[1].raw } : undefined;
+}
+/** Digest of the Regions a straight path can touch: the Region count, then the
+ * id, border, bounding box, owner, safety status and risk zone of every Region
+ * whose bounding box overlaps the path's, in tracker order. The tracker must
+ * be the canonical version 0 account; Regions away from the path, and every
+ * Region's systems, may change.
+ */
+export async function hashRegionPath(tracker, game, from, to) {
+    const data = await decodeTracker(tracker, game, true, 'The RegionTracker is not the canonical version 0 account for this Game. Refresh world region data and recreate the coordinate movement Plan.');
+    const [minX, maxX] = from.x < to.x ? [from.x, to.x] : [to.x, from.x];
+    const [minY, maxY] = from.y < to.y ? [from.y, to.y] : [to.y, from.y];
+    const regions = data.regions.unsizedList
+        .filter(({ boundingBox: box }) => box.minX.raw <= maxX &&
+        box.maxX.raw >= minX &&
+        box.minY.raw <= maxY &&
+        box.maxY.raw >= minY)
+        .map(({ id, border, boundingBox, owner, safetyStatus, riskZone }) => [
+        id,
+        border.map((point) => point.map(({ raw }) => raw)),
+        [
+            boundingBox.minX,
+            boundingBox.maxX,
+            boundingBox.minY,
+            boundingBox.maxY,
+        ].map(({ raw }) => raw),
+        owner,
+        safetyStatus,
+        riskZone,
+    ]);
+    return hashRegions(tracker, [data.regions.unsizedList.length, regions]);
+}
+//# sourceMappingURL=region-access.js.map

package/dist/internal/planning/region-access.js.map

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

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":"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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,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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"}