@aephia/atlas-kit 0.5.0 → 0.6.0-next.10

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

@@ -0,0 +1,49 @@
+import { getAddressDecoder, getAddressEncoder, getProgramDerivedAddress, } from '@solana/kit';
+import { SageSdkError } from '../../client/errors.js';
+export const ORIGINAL_TOKEN_PROGRAM = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
+export const ATA_PROGRAM = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
+export const SYSTEM_PROGRAM = '11111111111111111111111111111111';
+export function failShipImport(message, address) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', `${message} Refresh the relevant accounts and prepare a new ship import Plan.`, { address });
+}
+export async function deriveShipTokenAddress(owner, mint) {
+    const encoder = getAddressEncoder();
+    return (await getProgramDerivedAddress({
+        programAddress: ATA_PROGRAM,
+        seeds: [
+            encoder.encode(owner),
+            encoder.encode(ORIGINAL_TOKEN_PROGRAM),
+            encoder.encode(mint),
+        ],
+    }))[0];
+}
+function bytes(account, length) {
+    if (account.executable ||
+        account.owner !== ORIGINAL_TOKEN_PROGRAM ||
+        account.data.length !== length)
+        failShipImport(`Account ${account.address} must be an original Token account with exactly ${length} bytes; Token-2022 is unsupported.`, account.address);
+    return new DataView(account.data.buffer, account.data.byteOffset, account.data.byteLength);
+}
+function option(view, offset, account) {
+    if (view.getUint32(offset, true) > 1)
+        failShipImport('The Token account has malformed optional fields.', account.address);
+}
+export function validateShipMint(account) {
+    const view = bytes(account, 82);
+    option(view, 0, account);
+    option(view, 46, account);
+    if (view.getUint8(45) !== 1 || view.getUint8(44) !== 0)
+        failShipImport('Ship import requires an initialized zero-decimal mint so each token is one ship.', account.address);
+}
+export function validateShipToken(account, mint, owner) {
+    const view = bytes(account, 165);
+    for (const offset of [72, 109, 129])
+        option(view, offset, account);
+    const decoder = getAddressDecoder();
+    if (view.getUint8(108) !== 1 ||
+        decoder.decode(account.data.subarray(0, 32)) !== mint ||
+        decoder.decode(account.data.subarray(32, 64)) !== owner)
+        failShipImport(`The token account must be initialized, unfrozen and hold ship mint ${mint} under authority ${owner}. Delegated token spending is unsupported.`, account.address);
+    return view.getBigUint64(64, true);
+}
+//# sourceMappingURL=ship-token.js.map

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

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

package/dist/internal/read-meta.d.ts

@@ -1,9 +1,10 @@
+import type { DefinitionSection } from '../registry/index.js';
 import type { Commitment, DataSourceIdentity, DiscoveryStrategy } from '../client/contracts.js';
 /** Provenance attached non-enumerably to finder results.
  *
  * @example
  * ```ts
- * declare const fleets: object;
+ * declare const fleets: readonly {readonly address: Address}[];
  * const meta: ReadMeta | undefined = readMeta(fleets);
  * if (meta) console.log(meta.strategy, meta.slot);
  * ```
@@ -78,7 +79,42 @@ type ReadMetaInput = Omit<ReadMeta, 'toJSON'>;
  * const meta = readMeta(fleets);
  * ```
  */
-export declare function readMeta(result: object): ReadMeta | undefined;
-export declare function attachReadMeta<T extends object>(result: T, meta: ReadMeta | ReadMetaInput): T;
+export declare function readMeta<T extends object>(result: T): (unknown extends T ? ReadMeta | DefinitionPreloadMeta : T extends PreloadedDefinitions ? DefinitionPreloadMeta : PreloadedDefinitions extends T ? ReadMeta | DefinitionPreloadMeta : ReadMeta) | undefined;
+export declare function attachReadMeta<T extends object>(result: T, meta: ReadMeta | ReadMetaInput | DefinitionPreloadMeta | Omit<DefinitionPreloadMeta, 'toJSON'>): T;
+declare const PRELOADED_DEFINITIONS: unique symbol;
+/** The immutable section names satisfied by one preload call.
+ * @example
+ * ```ts
+ * import { preloadDefinitions } from '@aephia/atlas-kit';
+ * declare const ctx: SageContext;
+ * const sections: PreloadedDefinitions = await preloadDefinitions(ctx, ['cargo']);
+ * ```
+ */
+export type PreloadedDefinitions = readonly DefinitionSection[] & {
+    readonly [PRELOADED_DEFINITIONS]: true;
+};
+/** Per-section provenance; unavailable observations are never inferred from siblings.
+ * @example
+ * ```ts
+ * import { preloadDefinitions } from '@aephia/atlas-kit';
+ * declare const ctx: SageContext;
+ * const meta: DefinitionPreloadMeta | undefined = readMeta(await preloadDefinitions(ctx, ['ships']));
+ * ```
+ */
+export interface DefinitionPreloadMeta {
+    readonly kind: 'definition-preload';
+    readonly sections: readonly {
+        readonly section: DefinitionSection;
+        readonly sequenceId: number;
+        readonly observation: {
+            readonly availability: 'unavailable';
+        } | {
+            readonly availability: 'available';
+            readonly slot: bigint;
+            readonly commitment: Commitment;
+        };
+    }[];
+    toJSON(): unknown;
+}
 export {};
 //# sourceMappingURL=read-meta.d.ts.map

package/dist/internal/read-meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read-meta.d.ts","sourceRoot":"","sources":["../../src/internal/read-meta.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAShC;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IACzC,QAAQ,CAAC,cAAc,CAAC,EAAE,2BAA2B,CAAC;IACtD,mFAAmF;IACnF,MAAM,IAAI,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,KAAK,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAE7D;AAED,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAC7C,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,QAAQ,GAAG,aAAa,GAC7B,CAAC,CAaH"}
+{"version":3,"file":"read-meta.d.ts","sourceRoot":"","sources":["../../src/internal/read-meta.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAShC;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IACzC,QAAQ,CAAC,cAAc,CAAC,EAAE,2BAA2B,CAAC;IACtD,mFAAmF;IACnF,MAAM,IAAI,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,KAAK,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EACvC,MAAM,EAAE,CAAC,GAEP,CAAC,OAAO,SAAS,CAAC,GACd,QAAQ,GAAG,qBAAqB,GAChC,CAAC,SAAS,oBAAoB,GAC5B,qBAAqB,GACrB,oBAAoB,SAAS,CAAC,GAC5B,QAAQ,GAAG,qBAAqB,GAChC,QAAQ,CAAC,GACjB,SAAS,CAAC;AAOd,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAC7C,MAAM,EAAE,CAAC,EACT,IAAI,EACA,QAAQ,GACR,aAAa,GACb,qBAAqB,GACrB,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,GACxC,CAAC,CAaH;AAED,OAAO,CAAC,MAAM,qBAAqB,EAAE,OAAO,MAAM,CAAC;AACnD;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,SAAS,iBAAiB,EAAE,GAAG;IAChE,QAAQ,CAAC,CAAC,qBAAqB,CAAC,EAAE,IAAI,CAAC;CACxC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAC1B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;QACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,WAAW,EAChB;YAAE,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAA;SAAE,GACxC;YACE,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC;YACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YACtB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;SACjC,CAAC;KACP,EAAE,CAAC;IACJ,MAAM,IAAI,OAAO,CAAC;CACnB"}

package/dist/internal/read-meta.js

@@ -1,15 +1,5 @@
 import { attachJsonSerialization } from './json.js';
 const READ_META = Symbol('aephia.sage.readMeta');
-/** Returns finder provenance without wrapping the finder result.
- *
- * @example
- * ```ts
- * declare const ctx: SageContext;
- * declare const profileAddress: Address;
- * const fleets = await getFleetsByOwner(ctx, profileAddress);
- * const meta = readMeta(fleets);
- * ```
- */
 export function readMeta(result) {
     return result[READ_META];
 }

package/dist/internal/read-meta.js.map

@@ -1 +1 @@
-{"version":3,"file":"read-meta.js","sourceRoot":"","sources":["../../src/internal/read-meta.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAEpD,MAAM,SAAS,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAgFjD;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAc;IACrC,OAAQ,MAA0B,CAAC,SAAS,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,MAAS,EACT,IAA8B;IAE9B,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAClC,uBAAuB,CAAC;QACtB,GAAG,IAAI;KACR,CAAC,CACH,CAAC;IACF,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE;QACvC,YAAY,EAAE,KAAK;QACnB,UAAU,EAAE,KAAK;QACjB,KAAK,EAAE,cAAc;QACrB,QAAQ,EAAE,KAAK;KAChB,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"read-meta.js","sourceRoot":"","sources":["../../src/internal/read-meta.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAEpD,MAAM,SAAS,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAqGjD,MAAM,UAAU,QAAQ,CACtB,MAAc;IAEd,OAAQ,MAA0B,CAAC,SAAS,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,MAAS,EACT,IAIyC;IAEzC,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAClC,uBAAuB,CAAC;QACtB,GAAG,IAAI;KACR,CAAC,CACH,CAAC;IACF,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE;QACvC,YAAY,EAAE,KAAK;QACnB,UAAU,EAAE,KAAK;QACjB,KAAK,EAAE,cAAc;QACrB,QAAQ,EAAE,KAAK;KAChB,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,40 @@
+import type { SageContext } from '../../client/contracts.js';
+import { type PlanAuthorization } from '../../internal/planning/authorization-adapter.js';
+import { type Plan } from '../../planning/index.js';
+import type { LoyaltyAtlasBankSnapshot } from '../index.js';
+export type { PlanAuthorization };
+/** Exact inputs for claiming one Loyalty ATLAS Bank's full raw balance.
+ *
+ * @example
+ * ```ts
+ * declare const authorization: PlanAuthorization;
+ * const options: PlanClaimLoyaltyAtlasOptions = {
+ *   atUnixSeconds: 1_786_000_000n,
+ *   authorization,
+ * };
+ * ```
+ */
+export interface PlanClaimLoyaltyAtlasOptions {
+    /** Explicit non-negative Unix timestamp used to evaluate Bank expiry. */
+    readonly atUnixSeconds: bigint;
+    readonly authorization: PlanAuthorization;
+}
+/** Plans one full Loyalty ATLAS Bank claim without signing or writes.
+ *
+ * Permission, final freshness, and concurrent claims remain
+ * chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const bank: LoyaltyAtlasBankSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planClaimLoyaltyAtlas(ctx, bank, {
+ *   atUnixSeconds: 1_786_000_000n,
+ *   authorization,
+ * });
+ * console.log(plan.describe());
+ * ```
+ */
+export declare function planClaimLoyaltyAtlas(ctx: SageContext, bank: LoyaltyAtlasBankSnapshot, input: PlanClaimLoyaltyAtlasOptions): Promise<Plan>;
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/loyalty/actions/index.js

@@ -0,0 +1,159 @@
+import { getAddressEncoder, isAddress } from '@solana/kit';
+import { InvalidActionInputError, SageSdkError } from '../../client/errors.js';
+import { readContextRawAccounts } from '../../client/reconciliation.js';
+import { characterAccountDefinition, findCharacterPda, } from '../../internal/c4/identity.js';
+import { deriveLoyaltyAtlasBankAddress, deriveLoyaltyFactionAddress, loyaltyAtlasBankAccountDefinition, } from '../../internal/c4/loyalty.js';
+import { requireGameAddress } from '../../internal/game-context.js';
+import { adaptClaimLoyaltyAtlasInstruction, validatePlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
+import { createPlan, } from '../../planning/index.js';
+function invalid(field, value, acceptedRange, remedy) {
+    throw new InvalidActionInputError(field, value, acceptedRange, remedy);
+}
+function fail(message, address) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', message, { address });
+}
+function record(value, field) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return invalid(field, value, 'a plain object', `Provide ${field} as the documented object before retrying.`);
+    }
+    return value;
+}
+function exactKeys(value, field, required, optional = []) {
+    const accepted = new Set([...required, ...optional]);
+    const missing = required.find((key) => !Object.hasOwn(value, key));
+    const unexpected = Object.keys(value).find((key) => !accepted.has(key));
+    if (missing !== undefined || unexpected !== undefined) {
+        invalid(field, missing === undefined ? unexpected : `missing ${missing}`, `exactly the fields ${[...required, ...optional].join(', ')}`, `Remove unknown fields and provide every required ${field} field before retrying.`);
+    }
+}
+function address(value, field) {
+    if (typeof value !== 'string' || !isAddress(value)) {
+        return invalid(field, value, 'one valid z.ink/Solana account address', `Set ${field} to the documented public account address before retrying.`);
+    }
+    return value;
+}
+function validateOptions(value) {
+    const options = record(value, 'options');
+    exactKeys(options, 'options', ['atUnixSeconds', 'authorization']);
+    const authorizationRecord = record(options.authorization, 'authorization');
+    exactKeys(authorizationRecord, 'authorization', ['profile', 'authority', 'keyIndex'], ['certificate']);
+    const authorization = authorizationRecord;
+    address(authorization.profile, 'authorization.profile');
+    address(authorization.authority, 'authorization.authority');
+    if (authorization.certificate !== undefined) {
+        address(authorization.certificate, 'authorization.certificate');
+    }
+    validatePlanAuthorization(authorization);
+    if (typeof options.atUnixSeconds !== 'bigint' || options.atUnixSeconds < 0n) {
+        invalid('atUnixSeconds', options.atUnixSeconds, 'a non-negative bigint Unix timestamp', 'Provide the explicit current Unix timestamp used to evaluate Loyalty ATLAS Bank expiry before retrying.');
+    }
+    return { atUnixSeconds: options.atUnixSeconds, authorization };
+}
+function requireAccount(account, accountAddress, message) {
+    return account ?? fail(message, accountAddress);
+}
+async function hashAccountState(account) {
+    const owner = getAddressEncoder().encode(account.owner);
+    const canonical = new Uint8Array(owner.length + account.data.length);
+    canonical.set(owner);
+    canonical.set(account.data, owner.length);
+    const digest = new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', canonical));
+    return [...digest].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+async function precondition(account, describes) {
+    return Object.freeze({
+        address: account.address,
+        dataHash: await hashAccountState(account),
+        describes,
+        kind: 'account-state',
+    });
+}
+/** Plans one full Loyalty ATLAS Bank claim without signing or writes.
+ *
+ * Permission, final freshness, and concurrent claims remain
+ * chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const bank: LoyaltyAtlasBankSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planClaimLoyaltyAtlas(ctx, bank, {
+ *   atUnixSeconds: 1_786_000_000n,
+ *   authorization,
+ * });
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planClaimLoyaltyAtlas(ctx, bank, input) {
+    const options = validateOptions(input);
+    const game = requireGameAddress(ctx);
+    if (bank.game.address !== game) {
+        fail(`Loyalty ATLAS Bank ${bank.address} does not match the configured Game ${game}. Refresh the Bank through this context and retry.`, bank.address);
+    }
+    if (bank.profile.address !== options.authorization.profile) {
+        fail(`Loyalty ATLAS Bank ${bank.address} does not belong to authorization Profile ${options.authorization.profile}. Choose that Profile's Bank, refresh it, and retry.`, bank.address);
+    }
+    const canonicalBank = await deriveLoyaltyAtlasBankAddress(game, options.authorization.profile, bank.factionId);
+    if (bank.address !== canonicalBank) {
+        fail(`Loyalty ATLAS Bank ${bank.address} is not the canonical Loyalty ATLAS Bank ${canonicalBank} for authorization Profile ${options.authorization.profile} and faction ${String(bank.factionId)}. Refresh the Bank and retry.`, bank.address);
+    }
+    const faction = await deriveLoyaltyFactionAddress(game, bank.factionId);
+    if (bank.faction.address !== faction) {
+        fail(`Loyalty ATLAS Bank ${bank.address} does not match canonical faction account ${faction}. Refresh the Bank and retry.`, bank.address);
+    }
+    if (bank.claimableAtlasRaw === 0n) {
+        fail(`Loyalty ATLAS Bank ${bank.address} has no claimable ATLAS. Refresh it and retry after ATLAS is credited.`, bank.address);
+    }
+    if (bank.expiresAtUnixSeconds !== 0n &&
+        options.atUnixSeconds >= bank.expiresAtUnixSeconds) {
+        fail(`Loyalty ATLAS Bank ${bank.address} expired at Unix timestamp ${String(bank.expiresAtUnixSeconds)}. This balance cannot be claimed; refresh the Bank before choosing another action.`, bank.address);
+    }
+    const character = await findCharacterPda(options.authorization.profile, game);
+    const [bankCandidate, characterCandidate] = await readContextRawAccounts(ctx, [bank.address, character]);
+    const bankAccount = requireAccount(bankCandidate, bank.address, `Loyalty ATLAS Bank ${bank.address} is missing. Refresh it and retry the claim.`);
+    const characterAccount = requireAccount(characterCandidate, character, `Canonical Character ${character} is missing for authorization Profile ${options.authorization.profile}. Refresh the Profile Character and retry the claim.`);
+    const currentBank = loyaltyAtlasBankAccountDefinition.decode(bankAccount);
+    const currentCharacter = characterAccountDefinition.decode(characterAccount);
+    if (bankAccount.address !== bank.address ||
+        currentBank.version !== bank.version ||
+        currentBank.bump !== bank.bump ||
+        currentBank.game !== game ||
+        currentBank.profile !== options.authorization.profile ||
+        currentBank.factionId !== bank.factionId ||
+        currentBank.claimableAtlasRaw !== bank.claimableAtlasRaw ||
+        currentBank.lifetimeLpRaw !== bank.lifetimeLpRaw ||
+        currentBank.lifetimeAtlasRaw !== bank.lifetimeAtlasRaw ||
+        currentBank.lastCreditedAtUnixSeconds !== bank.lastCreditedAtUnixSeconds ||
+        currentBank.expiresAtUnixSeconds !== bank.expiresAtUnixSeconds) {
+        fail(`Loyalty ATLAS Bank ${bank.address} changed or does not match its canonical Game, Profile, faction, balance, lifetime, credit, or expiry state. Refresh the Bank through this context and retry.`, bank.address);
+    }
+    if (characterAccount.address !== character ||
+        currentCharacter.playerProfile !== options.authorization.profile ||
+        currentCharacter.game !== game) {
+        fail(`Canonical Character ${character} does not match Profile ${options.authorization.profile} and configured Game ${game}. Refresh or repair the Character relationship before retrying.`, character);
+    }
+    const description = `Claim ${String(bank.claimableAtlasRaw)} raw ATLAS from Loyalty ATLAS Bank ${bank.address} to Character ${character}; permission, final freshness, and concurrent claims remain chain-authoritative.`;
+    return createPlan({
+        kind: 'loyalty.claim-atlas',
+        preconditions: await Promise.all([
+            precondition(bankAccount, `Loyalty ATLAS Bank ${bank.address} retains its validated Game, Profile, faction, positive full balance, credit, and expiry state.`),
+            precondition(characterAccount, `Character ${character} remains the canonical Character for Profile ${options.authorization.profile} and the configured Game.`),
+        ]),
+        steps: [
+            {
+                describes: description,
+                instruction: adaptClaimLoyaltyAtlasInstruction({
+                    authorization: options.authorization,
+                    bank: bank.address,
+                    character,
+                    factionId: bank.factionId,
+                    game,
+                }),
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: description,
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/loyalty/actions/index.js.map

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

package/dist/markets/actions/index.d.ts

@@ -0,0 +1,100 @@
+import { type Address } from '@solana/kit';
+import type { SageContext } from '../../client/contracts.js';
+import type { EntityRef } from '../../client/refs.js';
+import { type PlanAuthorization } from '../../internal/planning/authorization-adapter.js';
+import { type Plan } from '../../planning/index.js';
+import type { LocalMarketSnapshot } from '../index.js';
+export type { PlanAuthorization };
+/** Inputs for placing one exact Local Market order.
+ *
+ * `priceRaw` is the positive raw ATLAS price per cargo unit and `quantity` is
+ * the positive raw cargo quantity. Both values are unsigned-u64 integers.
+ *
+ * @example
+ * ```ts
+ * declare const authorization: PlanAuthorization;
+ * const options: PlanPlaceLocalMarketOrderOptions = {
+ *   authorization,
+ *   side: 'bid',
+ *   priceRaw: 100_000_000n,
+ *   quantity: 5n,
+ * };
+ * ```
+ */
+export interface PlanPlaceLocalMarketOrderOptions {
+    readonly authorization: PlanAuthorization;
+    readonly side: 'bid' | 'ask';
+    readonly priceRaw: bigint;
+    readonly quantity: bigint;
+}
+/** Inputs for cancelling owned Local Market orders and withdrawing filled escrow.
+ *
+ * `orderIds` is a dense, unique list of non-negative safe integers. Pass an
+ * empty list to request withdrawal of filled escrow without cancelling an open
+ * order. The chain remains authoritative about whether escrow is available.
+ *
+ * @example
+ * ```ts
+ * declare const authorization: PlanAuthorization;
+ * const options: PlanCancelLocalMarketOrdersOptions = {
+ *   authorization,
+ *   orderIds: [4, 9],
+ * };
+ * ```
+ */
+export interface PlanCancelLocalMarketOrdersOptions {
+    readonly authorization: PlanAuthorization;
+    readonly orderIds: readonly number[];
+}
+interface StarbasePlayerSnapshot {
+    readonly kind: 'starbasePlayer';
+    readonly address: Address;
+    readonly playerProfile: EntityRef<'profile'>;
+    readonly system: EntityRef<'starSystem'>;
+    readonly character: EntityRef<'character'>;
+    readonly sequenceId: bigint;
+    readonly cargo: {
+        readonly items: readonly {
+            readonly id: number;
+            readonly name: string;
+            readonly quantityRaw: bigint;
+        }[];
+    };
+}
+/** Plans one Local Market bid or ask without signing, simulation, or writes.
+ *
+ * The planner validates the loaded Local Market and Starbase Player, their
+ * canonical Character/System/Game graph, the current market-enabled Starbase
+ * incarnation, and the known bid ATLAS or ask cargo balance. Matching, rent,
+ * final capacity, permissions, and state races remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const market: LocalMarketSnapshot;
+ * declare const player: StarbasePlayerSnapshot;
+ * declare const options: PlanPlaceLocalMarketOrderOptions;
+ * const plan = await planPlaceLocalMarketOrder(ctx, market, player, options);
+ * console.log(plan.describe());
+ * ```
+ */
+export declare function planPlaceLocalMarketOrder(ctx: SageContext, market: LocalMarketSnapshot, player: StarbasePlayerSnapshot, input: PlanPlaceLocalMarketOrderOptions): Promise<Plan>;
+/** Plans cancellation of owned Local Market orders and filled-escrow withdrawal.
+ *
+ * The planner validates the loaded Local Market and Starbase Player, their
+ * canonical Profile/Character/System/Game graph, and each selected order's
+ * ownership and price. An empty selection requests filled-escrow withdrawal.
+ * Final escrow availability and order races remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const market: LocalMarketSnapshot;
+ * declare const player: StarbasePlayerSnapshot;
+ * declare const options: PlanCancelLocalMarketOrdersOptions;
+ * const plan = await planCancelLocalMarketOrders(ctx, market, player, options);
+ * console.log(plan.describe());
+ * ```
+ */
+export declare function planCancelLocalMarketOrders(ctx: SageContext, market: LocalMarketSnapshot, player: StarbasePlayerSnapshot, input: PlanCancelLocalMarketOrdersOptions): Promise<Plan>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/markets/actions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAoBtD,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAEL,KAAK,IAAI,EAEV,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAElC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,UAAU,sBAAsB;IAC9B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,KAAK,EAAE,SAAS;YACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;YACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;SAC9B,EAAE,CAAC;KACL,CAAC;CACH;AA2ND;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,sBAAsB,EAC9B,KAAK,EAAE,gCAAgC,GACtC,OAAO,CAAC,IAAI,CAAC,CA+Nf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,sBAAsB,EAC9B,KAAK,EAAE,kCAAkC,GACxC,OAAO,CAAC,IAAI,CAAC,CA8Of"}