@aephia/atlas-kit 0.6.0-next.12 → 0.6.0-next.121

package/dist/internal/planning/open-signal-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-signal-guard.js","sourceRoot":"","sources":["../../../src/internal/planning/open-signal-guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAGtD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,8BAA8B,EAAE,MAAM,yBAAyB,CAAC;AACzE,MAAM,UAAU,8BAA8B,CAC5C,KAA0B,EAC1B,MAAmC;IAEnC,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAC5B,CAAC,CAAC,EAAwB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,kBAAkB,CAC3D,CAAC;IACF,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,CAC/B,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,CACrB,CAAC,CAAC,cAAc,KAAK,oBAAoB;QACzC,8BAA8B,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CACpE,CAAC;IACF,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,MAAM;QAAE,OAAO;IACrD,MAAM,GAAG,GAAG,GAAU,EAAE;QACtB,MAAM,IAAI,YAAY,CACpB,4BAA4B,EAC5B,wJAAwJ,CACzJ,CAAC;IACJ,CAAC,CAAC;IACF,IACE,QAAQ,CAAC,MAAM,KAAK,YAAY,CAAC,MAAM;QACvC,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,MAAM;QAEhE,GAAG,EAAE,CAAC;IACR,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAC3C,IACE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,cAAc,IAAI,CAAC,CAAC,OAAO,KAAK,KAAK,CAAC,IAAI,CAAC;YAE1E,GAAG,EAAE,CAAC;QACR,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,CACjC,CAAC,IAAI,EAAE,EAAE,CACP,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YACzB,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,SAAS;YACnC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,KAAK,EAAE;YACpC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAE,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAE,GAAG,GAAG;gBACzD,KAAK,CAAC,QAAQ;YAChB,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,KAAK,QAAQ,CAAC,MAAM;YACrD,QAAQ,CAAC,KAAK,CACZ,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,OAAO;gBACrD,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,KAAK,CAAC,CAAC,IAAI,CAChD,CACJ,CAAC;QACF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,GAAG,EAAE,CAAC;IAClC,CAAC;AACH,CAAC"}

package/dist/internal/planning/open-signal.d.ts

@@ -0,0 +1,31 @@
+import type { Address } from '@solana/kit';
+import { openSignalInstruction } from '../c4/open-signal.js';
+export { openSignalInstruction };
+import type { RawAccount } from '../../client/contracts.js';
+export interface OpenSignalIntent {
+    readonly game: Address;
+    readonly fleet: Address;
+    readonly profile: Address;
+    readonly authority: Address;
+    readonly keyIndex: number;
+}
+export interface OpenSignalGuard extends OpenSignalIntent {
+    readonly kind: 'scan-signal-open';
+    readonly address: Address;
+    readonly character: Address;
+    readonly maximumProfileDebit: bigint;
+    readonly authorityHash: string;
+    readonly describes: string;
+    readonly dataHash?: never;
+}
+export declare function resolveOpenSignal(intent: OpenSignalIntent): Promise<{
+    address: Address;
+    character: Address;
+}>;
+export declare function openSignalAddresses(guard: OpenSignalGuard): readonly Address[];
+export declare function validateOpenSignal(guard: OpenSignalGuard, accounts: ReadonlyMap<Address, RawAccount | undefined>, expectedAuthorityHash?: string): Promise<{
+    profileDebit: bigint;
+    profileReserve: bigint;
+    authorityHash: string;
+}>;
+//# sourceMappingURL=open-signal.d.ts.map

package/dist/internal/planning/open-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-signal.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/open-signal.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,qBAAqB,EAItB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,qBAAqB,EAAE,CAAC;AACjC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAa5D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AACD,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;CAC3B;AACD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAAC,CAMnD;AAID,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,eAAe,GACrB,SAAS,OAAO,EAAE,CASpB;AACD,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,WAAW,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC,EACtD,qBAAqB,CAAC,EAAE,MAAM;;;;GAoG/B"}

package/dist/internal/planning/open-signal.js

@@ -0,0 +1,85 @@
+import { hashAccountState } from './account-state.js';
+import { openSignalInstruction, scanSignalSize, SAGE_PROGRAM_ADDRESS, PLAYER_PROFILE_PROGRAM_ADDRESS, } from '../c4/open-signal.js';
+export { openSignalInstruction };
+import { SageSdkError } from '../../client/errors.js';
+import { fleetAccountDefinition, deriveFleetAddress } from '../c4/fleet.js';
+import { profileAccountDefinition } from '../c4/identity.js';
+import { characterAccountDefinition, findCharacterPda, } from '../c4/character.js';
+import { deriveScanLifecycleAddress } from '../c4/scan-lifecycle.js';
+import { CLOCK_ADDRESS, readClock } from './faction-enrollment.js';
+import { RENT_ADDRESS, readRent } from './rent.js';
+import { directProfileKey, profileKeyExpired } from './profile-key.js';
+export async function resolveOpenSignal(intent) {
+    const [address, character] = await Promise.all([
+        deriveScanLifecycleAddress('scanSignal', intent.game, intent.fleet),
+        findCharacterPda(intent.profile, intent.game),
+    ]);
+    return { address: address[0], character };
+}
+function fail(address, message) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', message, { address });
+}
+export function openSignalAddresses(guard) {
+    return [
+        guard.address,
+        guard.fleet,
+        guard.profile,
+        guard.character,
+        RENT_ADDRESS,
+        CLOCK_ADDRESS,
+    ];
+}
+export async function validateOpenSignal(guard, accounts, expectedAuthorityHash) {
+    const resolved = await resolveOpenSignal(guard);
+    if (resolved.address !== guard.address ||
+        resolved.character !== guard.character)
+        fail(guard.address, 'Signal or Character PDA contradicts the Game, Fleet or Profile. Recreate the setup Plan from fresh canonical accounts.');
+    const required = (address) => {
+        const raw = accounts.get(address);
+        if (!raw || raw.executable)
+            fail(address, 'A signal setup prerequisite is missing or executable. Refetch valid accounts and recreate the Plan.');
+        return raw;
+    };
+    if (accounts.get(guard.address))
+        fail(guard.address, 'The canonical signal already exists. Refetch and reuse it; setup cannot replace an existing signal.');
+    const fleet = fleetAccountDefinition.decode(required(guard.fleet));
+    if (fleet.game !== guard.game ||
+        fleet.ownerProfile !== guard.profile ||
+        (await deriveFleetAddress(fleet)) !== guard.fleet ||
+        fleet.subProfile !== '11111111111111111111111111111111')
+        fail(guard.fleet, 'The Fleet has a different Game, owner, canonical PDA or delegated controller. Refetch a directly owned Fleet and recreate setup.');
+    const character = characterAccountDefinition.decode(required(guard.character));
+    if (character.game !== guard.game ||
+        character.playerProfile !== guard.profile)
+        fail(guard.character, 'The owner/controller Character does not belong to this Game and Profile. Refetch the canonical Character and recreate setup.');
+    const profileRaw = required(guard.profile);
+    const profile = profileAccountDefinition.decode(profileRaw);
+    const now = readClock(required(CLOCK_ADDRESS));
+    const key = directProfileKey(profile.keys, guard.keyIndex, guard.authority);
+    if (!key || profileKeyExpired(key, now))
+        fail(guard.profile, 'The selected direct Profile key is missing, mismatched or expired. Refetch the Profile, select a current key and recreate setup.');
+    if (key.scope !== PLAYER_PROFILE_PROGRAM_ADDRESS &&
+        key.scope !== SAGE_PROGRAM_ADDRESS)
+        fail(guard.profile, 'The selected key has an unrelated program scope. Select a current Profile- or SAGE-scoped direct key and recreate setup; instruction permission acceptance remains chain-authoritative.');
+    const authorityHash = await hashAccountState(profileRaw.owner, new TextEncoder().encode(JSON.stringify([
+        profile.version,
+        profile.authKeyCount,
+        profile.keyThreshold,
+        key.address,
+        key.scope,
+        String(key.permissionsRaw),
+        String(key.expiresAtRaw),
+    ])));
+    if (expectedAuthorityHash !== undefined &&
+        authorityHash !== expectedAuthorityHash)
+        fail(guard.profile, 'The selected Profile authorization changed. Refetch the key and recreate setup before signing.');
+    const rent = readRent(required(RENT_ADDRESS));
+    const profileDebit = rent(scanSignalSize());
+    const profileReserve = rent(profileRaw.data.length);
+    if (profileDebit > guard.maximumProfileDebit)
+        fail(guard.profile, 'Signal rent now exceeds the approved Profile debit. Recreate setup and inspect the new funding ceiling before signing.');
+    if (profileRaw.lamports < profileReserve + profileDebit)
+        fail(guard.profile, 'The Profile lacks signal rent while retaining its own storage reserve. Fund the Profile explicitly, refetch and recreate setup; transaction fees are separate.');
+    return { profileDebit, profileReserve, authorityHash };
+}
+//# sourceMappingURL=open-signal.js.map

package/dist/internal/planning/open-signal.js.map

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

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

@@ -0,0 +1,40 @@
+import { type Address, type Instruction } from '@solana/kit';
+import type { RawAccount, SageContext } from '../../client/contracts.js';
+import type { PlanPrecondition } from '../../planning/index.js';
+export declare const ORIGINAL_TOKEN_PROGRAM: Address;
+export declare const ATA_PROGRAM: Address;
+/** Rejects with the calling planner's wording and remedy. */
+type Fail = (message: string, address: Address) => never;
+/** What a wallet token transfer Plan rechecks and leaves to the chain. */
+export declare const TOKEN_TRANSFER_DISCLOSURE = "System identity, active Starbase generation and applicable CSS requirements are rechecked before signing; unrelated System combat, shield, health and hab activity is not equality-bound. Execution access checks remain chain-authoritative, not a client-side atomicity guarantee. Mint supply and authorities may change; initialized original Token mint layout and decimals are rechecked before signing.";
+/** The canonical associated token account of `owner` for an original Token `mint`. */
+export declare function deriveAssociatedTokenAddress(owner: Address, mint: Address): Promise<Address>;
+/** Whether a wallet is an original or Token-2022 multisig authority, which
+ * needs signer semantics outside the single-owner wallet planners. */
+export declare function isTokenMultisig(account: RawAccount | undefined): boolean;
+/** The raw balance of an initialized, unfrozen original Token account of
+ * `mint` owned by `owner`, or why the account is not one: `layout` for
+ * anything but a well-formed 165-byte original Token account, `holder` for
+ * its state, mint or owner. Mint and authority sit at 0/32, the state at 108
+ * and u32 COption tags at 72/109/129. A recorded delegate does not prevent the
+ * owner from transferring, so it is accepted. */
+export declare function originalTokenBalance(account: RawAccount, mint: Address, owner: Address): bigint | 'layout' | 'holder';
+/** {@link originalTokenBalance}, failing with the calling planner's wording
+ * when the account is not the expected original Token account. */
+export declare function readTokenAccount(account: RawAccount, mint: Address, owner: Address, fail: Fail): bigint;
+/** Validates an explicit payer for idempotent canonical ATA creation and
+ * returns the creation instruction, its storage funding, and the payer, Rent
+ * and program observations. Reads Rent unless the caller already holds it. */
+export declare function resolveAssociatedTokenCreation(ctx: SageContext, request: {
+    readonly payer: Address;
+    readonly address: Address;
+    readonly owner: Address;
+    readonly mint: Address;
+    readonly rent?: RawAccount;
+}, fail: Fail, observe: (account: RawAccount, role: string) => Promise<PlanPrecondition>): Promise<{
+    readonly instruction: Instruction;
+    readonly preconditions: readonly PlanPrecondition[];
+    readonly storageFunding: bigint;
+}>;
+export {};
+//# sourceMappingURL=original-token.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"original-token.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/original-token.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,OAAO,EACZ,KAAK,WAAW,EACjB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAIhE,eAAO,MAAM,sBAAsB,EACgB,OAAO,CAAC;AAC3D,eAAO,MAAM,WAAW,EAC4B,OAAO,CAAC;AAI5D,6DAA6D;AAC7D,KAAK,IAAI,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,KAAK,CAAC;AAEzD,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB,mZAC4W,CAAC;AAEnZ,sFAAsF;AACtF,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,OAAO,CAAC,CAWlB;AAED;sEACsE;AACtE,wBAAgB,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,CAOxE;AAED;;;;;iDAKiD;AACjD,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,GACb,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAkB9B;AAED;kEACkE;AAClE,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,IAAI,GACT,MAAM,CAcR;AAED;;8EAE8E;AAC9E,wBAAsB,8BAA8B,CAClD,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;CAC5B,EACD,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAC,GACxE,OAAO,CAAC;IACT,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACpD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC,CAAC,CAgED"}

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

@@ -0,0 +1,112 @@
+import { AccountRole, getAddressDecoder, getAddressEncoder, getProgramDerivedAddress, } from '@solana/kit';
+import { readContextRawAccounts } from '../../client/reconciliation.js';
+import { SYSTEM_PROGRAM } from '../system-program.js';
+import { RENT_ADDRESS, readRent } from './rent.js';
+export const ORIGINAL_TOKEN_PROGRAM = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
+export const ATA_PROGRAM = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
+const TOKEN_2022_PROGRAM = 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb';
+/** What a wallet token transfer Plan rechecks and leaves to the chain. */
+export const TOKEN_TRANSFER_DISCLOSURE = 'System identity, active Starbase generation and applicable CSS requirements are rechecked before signing; unrelated System combat, shield, health and hab activity is not equality-bound. Execution access checks remain chain-authoritative, not a client-side atomicity guarantee. Mint supply and authorities may change; initialized original Token mint layout and decimals are rechecked before signing.';
+/** The canonical associated token account of `owner` for an original Token `mint`. */
+export async function deriveAssociatedTokenAddress(owner, mint) {
+    const encoder = getAddressEncoder();
+    const [address] = await getProgramDerivedAddress({
+        programAddress: ATA_PROGRAM,
+        seeds: [
+            encoder.encode(owner),
+            encoder.encode(ORIGINAL_TOKEN_PROGRAM),
+            encoder.encode(mint),
+        ],
+    });
+    return address;
+}
+/** Whether a wallet is an original or Token-2022 multisig authority, which
+ * needs signer semantics outside the single-owner wallet planners. */
+export function isTokenMultisig(account) {
+    return (account !== undefined &&
+        account.data.length === 355 &&
+        (account.owner === ORIGINAL_TOKEN_PROGRAM ||
+            account.owner === TOKEN_2022_PROGRAM));
+}
+/** The raw balance of an initialized, unfrozen original Token account of
+ * `mint` owned by `owner`, or why the account is not one: `layout` for
+ * anything but a well-formed 165-byte original Token account, `holder` for
+ * its state, mint or owner. Mint and authority sit at 0/32, the state at 108
+ * and u32 COption tags at 72/109/129. A recorded delegate does not prevent the
+ * owner from transferring, so it is accepted. */
+export function originalTokenBalance(account, mint, owner) {
+    const { data } = account;
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    if (account.executable ||
+        account.owner !== ORIGINAL_TOKEN_PROGRAM ||
+        data.length !== 165 ||
+        [72, 109, 129].some((offset) => view.getUint32(offset, true) > 1))
+        return 'layout';
+    const decoder = getAddressDecoder();
+    if (view.getUint8(108) !== 1 ||
+        decoder.decode(data.subarray(0, 32)) !== mint ||
+        decoder.decode(data.subarray(32, 64)) !== owner)
+        return 'holder';
+    return view.getBigUint64(64, true);
+}
+/** {@link originalTokenBalance}, failing with the calling planner's wording
+ * when the account is not the expected original Token account. */
+export function readTokenAccount(account, mint, owner, fail) {
+    const { address } = account;
+    const balance = originalTokenBalance(account, mint, owner);
+    if (balance === 'layout')
+        fail(`Account ${address} must be a well-formed original Token account of exactly 165 bytes; Token-2022 and multisig layouts are unsupported.`, address);
+    if (balance === 'holder')
+        fail(`Token account ${address} must be initialized, unfrozen and hold mint ${mint} under owner ${owner}; delegated spending is unsupported.`, address);
+    return balance;
+}
+/** Validates an explicit payer for idempotent canonical ATA creation and
+ * returns the creation instruction, its storage funding, and the payer, Rent
+ * and program observations. Reads Rent unless the caller already holds it. */
+export async function resolveAssociatedTokenCreation(ctx, request, fail, observe) {
+    const addresses = [
+        request.payer,
+        ATA_PROGRAM,
+        SYSTEM_PROGRAM,
+        ORIGINAL_TOKEN_PROGRAM,
+        ...(request.rent === undefined ? [RENT_ADDRESS] : []),
+    ];
+    const accounts = (await readContextRawAccounts(ctx, addresses)).map((account, index) => account ??
+        fail(`ATA creation prerequisite ${addresses[index]} is missing. Create or fund it separately.`, addresses[index]));
+    const [payer, ...programs] = accounts.slice(0, 4);
+    const rent = request.rent ?? accounts[4];
+    if (programs.some((program) => !program.executable))
+        fail('ATA creation requires executable associated-token, System and original Token programs in this deployment.', ATA_PROGRAM);
+    // Original Token accounts occupy 165 bytes; the shared Rent reader includes
+    // the 128-byte account overhead and validates the full sysvar.
+    const storageFunding = readRent(rent)(165);
+    if (payer.owner !== SYSTEM_PROGRAM ||
+        payer.executable ||
+        payer.data.length !== 0 ||
+        payer.lamports < storageFunding)
+        fail(`ATA payer must be a System wallet with at least ${storageFunding} lamports for storage, in addition to transaction fees.`, request.payer);
+    const roles = [
+        'ATA payer identity',
+        'Associated-token program',
+        'System program',
+        'Token program',
+        'Rent configuration',
+    ];
+    return {
+        instruction: {
+            programAddress: ATA_PROGRAM,
+            accounts: [
+                { address: request.payer, role: AccountRole.WRITABLE_SIGNER },
+                { address: request.address, role: AccountRole.WRITABLE },
+                { address: request.owner, role: AccountRole.READONLY },
+                { address: request.mint, role: AccountRole.READONLY },
+                { address: SYSTEM_PROGRAM, role: AccountRole.READONLY },
+                { address: ORIGINAL_TOKEN_PROGRAM, role: AccountRole.READONLY },
+            ],
+            data: Uint8Array.of(1),
+        },
+        preconditions: await Promise.all(accounts.map((account, index) => observe(account, roles[index]))),
+        storageFunding,
+    };
+}
+//# sourceMappingURL=original-token.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"original-token.js","sourceRoot":"","sources":["../../../src/internal/planning/original-token.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,GAGzB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEnD,MAAM,CAAC,MAAM,sBAAsB,GACjC,6CAAwD,CAAC;AAC3D,MAAM,CAAC,MAAM,WAAW,GACtB,8CAAyD,CAAC;AAC5D,MAAM,kBAAkB,GACtB,6CAAwD,CAAC;AAK3D,0EAA0E;AAC1E,MAAM,CAAC,MAAM,yBAAyB,GACpC,gZAAgZ,CAAC;AAEnZ,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,KAAc,EACd,IAAa;IAEb,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;IACpC,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,wBAAwB,CAAC;QAC/C,cAAc,EAAE,WAAW;QAC3B,KAAK,EAAE;YACL,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;YACrB,OAAO,CAAC,MAAM,CAAC,sBAAsB,CAAC;YACtC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;SACrB;KACF,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;sEACsE;AACtE,MAAM,UAAU,eAAe,CAAC,OAA+B;IAC7D,OAAO,CACL,OAAO,KAAK,SAAS;QACrB,OAAO,CAAC,IAAI,CAAC,MAAM,KAAK,GAAG;QAC3B,CAAC,OAAO,CAAC,KAAK,KAAK,sBAAsB;YACvC,OAAO,CAAC,KAAK,KAAK,kBAAkB,CAAC,CACxC,CAAC;AACJ,CAAC;AAED;;;;;iDAKiD;AACjD,MAAM,UAAU,oBAAoB,CAClC,OAAmB,EACnB,IAAa,EACb,KAAc;IAEd,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACzE,IACE,OAAO,CAAC,UAAU;QAClB,OAAO,CAAC,KAAK,KAAK,sBAAsB;QACxC,IAAI,CAAC,MAAM,KAAK,GAAG;QACnB,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QAEjE,OAAO,QAAQ,CAAC;IAClB,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;IACpC,IACE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC;QACxB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI;QAC7C,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK;QAE/C,OAAO,QAAQ,CAAC;IAClB,OAAO,IAAI,CAAC,YAAY,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC;AAED;kEACkE;AAClE,MAAM,UAAU,gBAAgB,CAC9B,OAAmB,EACnB,IAAa,EACb,KAAc,EACd,IAAU;IAEV,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC5B,MAAM,OAAO,GAAG,oBAAoB,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3D,IAAI,OAAO,KAAK,QAAQ;QACtB,IAAI,CACF,WAAW,OAAO,sHAAsH,EACxI,OAAO,CACR,CAAC;IACJ,IAAI,OAAO,KAAK,QAAQ;QACtB,IAAI,CACF,iBAAiB,OAAO,gDAAgD,IAAI,gBAAgB,KAAK,sCAAsC,EACvI,OAAO,CACR,CAAC;IACJ,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;8EAE8E;AAC9E,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAClD,GAAgB,EAChB,OAMC,EACD,IAAU,EACV,OAAyE;IAMzE,MAAM,SAAS,GAAG;QAChB,OAAO,CAAC,KAAK;QACb,WAAW;QACX,cAAc;QACd,sBAAsB;QACtB,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KACtD,CAAC;IACF,MAAM,QAAQ,GAAG,CAAC,MAAM,sBAAsB,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,CACjE,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CACjB,OAAO;QACP,IAAI,CACF,6BAA6B,SAAS,CAAC,KAAK,CAAE,4CAA4C,EAC1F,SAAS,CAAC,KAAK,CAAE,CAClB,CACJ,CAAC;IACF,MAAM,CAAC,KAAK,EAAE,GAAG,QAAQ,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAG/C,CAAC;IACF,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,QAAQ,CAAC,CAAC,CAAE,CAAC;IAC1C,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;QACjD,IAAI,CACF,2GAA2G,EAC3G,WAAW,CACZ,CAAC;IACJ,4EAA4E;IAC5E,+DAA+D;IAC/D,MAAM,cAAc,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAC3C,IACE,KAAK,CAAC,KAAK,KAAK,cAAc;QAC9B,KAAK,CAAC,UAAU;QAChB,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QACvB,KAAK,CAAC,QAAQ,GAAG,cAAc;QAE/B,IAAI,CACF,mDAAmD,cAAc,yDAAyD,EAC1H,OAAO,CAAC,KAAK,CACd,CAAC;IACJ,MAAM,KAAK,GAAG;QACZ,oBAAoB;QACpB,0BAA0B;QAC1B,gBAAgB;QAChB,eAAe;QACf,oBAAoB;KACrB,CAAC;IACF,OAAO;QACL,WAAW,EAAE;YACX,cAAc,EAAE,WAAW;YAC3B,QAAQ,EAAE;gBACR,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,WAAW,CAAC,eAAe,EAAE;gBAC7D,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,QAAQ,EAAE;gBACxD,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,WAAW,CAAC,QAAQ,EAAE;gBACtD,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,QAAQ,EAAE;gBACrD,EAAE,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,CAAC,QAAQ,EAAE;gBACvD,EAAE,OAAO,EAAE,sBAAsB,EAAE,IAAI,EAAE,WAAW,CAAC,QAAQ,EAAE;aAChE;YACD,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;SACvB;QACD,aAAa,EAAE,MAAM,OAAO,CAAC,GAAG,CAC9B,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAE,CAAC,CAAC,CAClE;QACD,cAAc;KACf,CAAC;AACJ,CAAC"}

package/dist/internal/planning/own-starbase-facts.d.ts

@@ -0,0 +1,33 @@
+import type { Address } from '@solana/kit';
+import type { RawAccount } from '../../client/contracts.js';
+/** How a planner names itself in the remedies it shares. */
+export interface OwnStarbaseAction {
+    /** Completes "Refresh the canonical Character and …", e.g. `replan Fleet creation`. */
+    readonly replan: string;
+    /** Completes "Refresh the canonical membership …", e.g. `before creating a Fleet`. */
+    readonly before: string;
+}
+/** Decodes and relates the Profile, Character, faction membership, Star System
+ * and StarbasePlayer that Fleet creation and ship assembly both require: one
+ * canonical Character and membership for the Profile, a canonical Starbase
+ * System owned by that faction, and the StarbasePlayer joining them.
+ * `required` reads each account with the planner's own wording. */
+export declare function readOwnStarbaseFacts(intent: {
+    readonly game: Address;
+    readonly profile: Address;
+    readonly system: Address;
+}, resolved: {
+    readonly profile: Address;
+    readonly character: Address;
+    readonly profileFaction: Address;
+    readonly system: Address;
+    readonly starbasePlayer: Address;
+}, required: (address: Address, name: string) => RawAccount, action: OwnStarbaseAction): Promise<{
+    profileRaw: RawAccount;
+    profile: Readonly<import("../c4/identity.js").ProfileAccountData>;
+    character: Readonly<import("../c4/character.js").CharacterAccountData>;
+    faction: Readonly<import("../c4/profile-faction.js").ProfileFactionAccountData>;
+    starbase: import("../c4/world.js").WorldStarbaseData;
+    player: Readonly<import("../c4/starbase.js").StarbasePlayerAccountData>;
+}>;
+//# sourceMappingURL=own-starbase-facts.d.ts.map

package/dist/internal/planning/own-starbase-facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"own-starbase-facts.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/own-starbase-facts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAW5D,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAMD;;;;mEAImE;AACnE,wBAAsB,oBAAoB,CACxC,MAAM,EAAE;IACN,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B,EACD,QAAQ,EAAE;IACR,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC,EACD,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,UAAU,EACxD,MAAM,EAAE,iBAAiB;;;;;;;GAiE1B"}

package/dist/internal/planning/own-starbase-facts.js

@@ -0,0 +1,49 @@
+import { SageSdkError } from '../../client/errors.js';
+import { characterAccountDefinition } from '../c4/character.js';
+import { profileAccountDefinition } from '../c4/identity.js';
+import { profileFactionAccountDefinition } from '../c4/profile-faction.js';
+import { starbasePlayerAccountDefinition } from '../c4/starbase.js';
+import { deriveStarSystemAddress, starSystemAccountDefinition, } from '../c4/world.js';
+function fail(address, message) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', message, { address });
+}
+/** Decodes and relates the Profile, Character, faction membership, Star System
+ * and StarbasePlayer that Fleet creation and ship assembly both require: one
+ * canonical Character and membership for the Profile, a canonical Starbase
+ * System owned by that faction, and the StarbasePlayer joining them.
+ * `required` reads each account with the planner's own wording. */
+export async function readOwnStarbaseFacts(intent, resolved, required, action) {
+    const profileRaw = required(resolved.profile, 'Profile');
+    const profile = profileAccountDefinition.decode(profileRaw);
+    const character = characterAccountDefinition.decode(required(resolved.character, 'Character'));
+    const faction = profileFactionAccountDefinition.decode(required(resolved.profileFaction, 'ProfileFaction'));
+    const system = starSystemAccountDefinition.decode(required(resolved.system, 'Star System'));
+    const player = starbasePlayerAccountDefinition.decode(required(resolved.starbasePlayer, 'StarbasePlayer'));
+    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 ${action.replan}.`);
+    if (faction.profile !== intent.profile)
+        fail(resolved.profileFaction, `The faction membership belongs to a different Profile. Refresh the canonical membership ${action.before}.`);
+    if (system.game !== intent.game ||
+        (await deriveStarSystemAddress(system.game, system.systemId)) !==
+            intent.system ||
+        !system.starbase)
+        fail(resolved.system, 'The selected System is not canonical for this Game or has no Starbase. Choose a valid Starbase System and replan.');
+    if (player.playerProfile !== intent.profile ||
+        player.character !== resolved.character ||
+        player.system !== intent.system ||
+        player.faction !== faction.faction)
+        fail(resolved.starbasePlayer, 'The StarbasePlayer has a different Profile, Character, System or faction relationship. Refresh the canonical StarbasePlayer and replan.');
+    if (faction.faction === 'unaligned' ||
+        system.starbase.owner !== faction.faction)
+        fail(resolved.system, 'This planner supports an existing own-faction StarbasePlayer only. Select an own-faction Starbase; other diplomacy or access routes require separate supported planning.');
+    return {
+        profileRaw,
+        profile,
+        character,
+        faction,
+        starbase: system.starbase,
+        player,
+    };
+}
+//# sourceMappingURL=own-starbase-facts.js.map

package/dist/internal/planning/own-starbase-facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"own-starbase-facts.js","sourceRoot":"","sources":["../../../src/internal/planning/own-starbase-facts.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,+BAA+B,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,+BAA+B,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EACL,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,gBAAgB,CAAC;AAUxB,SAAS,IAAI,CAAC,OAAgB,EAAE,OAAe;IAC7C,MAAM,IAAI,YAAY,CAAC,4BAA4B,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;AAC7E,CAAC;AAED;;;;mEAImE;AACnE,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAIC,EACD,QAMC,EACD,QAAwD,EACxD,MAAyB;IAEzB,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,wBAAwB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC5D,MAAM,SAAS,GAAG,0BAA0B,CAAC,MAAM,CACjD,QAAQ,CAAC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,CAC1C,CAAC;IACF,MAAM,OAAO,GAAG,+BAA+B,CAAC,MAAM,CACpD,QAAQ,CAAC,QAAQ,CAAC,cAAc,EAAE,gBAAgB,CAAC,CACpD,CAAC;IACF,MAAM,MAAM,GAAG,2BAA2B,CAAC,MAAM,CAC/C,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,CACzC,CAAC;IACF,MAAM,MAAM,GAAG,+BAA+B,CAAC,MAAM,CACnD,QAAQ,CAAC,QAAQ,CAAC,cAAc,EAAE,gBAAgB,CAAC,CACpD,CAAC;IACF,IACE,SAAS,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI;QAC9B,SAAS,CAAC,aAAa,KAAK,MAAM,CAAC,OAAO;QAE1C,IAAI,CACF,QAAQ,CAAC,SAAS,EAClB,6FAA6F,MAAM,CAAC,MAAM,GAAG,CAC9G,CAAC;IACJ,IAAI,OAAO,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO;QACpC,IAAI,CACF,QAAQ,CAAC,cAAc,EACvB,2FAA2F,MAAM,CAAC,MAAM,GAAG,CAC5G,CAAC;IACJ,IACE,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI;QAC3B,CAAC,MAAM,uBAAuB,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC3D,MAAM,CAAC,MAAM;QACf,CAAC,MAAM,CAAC,QAAQ;QAEhB,IAAI,CACF,QAAQ,CAAC,MAAM,EACf,mHAAmH,CACpH,CAAC;IACJ,IACE,MAAM,CAAC,aAAa,KAAK,MAAM,CAAC,OAAO;QACvC,MAAM,CAAC,SAAS,KAAK,QAAQ,CAAC,SAAS;QACvC,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;QAC/B,MAAM,CAAC,OAAO,KAAK,OAAO,CAAC,OAAO;QAElC,IAAI,CACF,QAAQ,CAAC,cAAc,EACvB,yIAAyI,CAC1I,CAAC;IACJ,IACE,OAAO,CAAC,OAAO,KAAK,WAAW;QAC/B,MAAM,CAAC,QAAQ,CAAC,KAAK,KAAK,OAAO,CAAC,OAAO;QAEzC,IAAI,CACF,QAAQ,CAAC,MAAM,EACf,0KAA0K,CAC3K,CAAC;IACJ,OAAO;QACL,UAAU;QACV,OAAO;QACP,SAAS;QACT,OAAO;QACP,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,MAAM;KACP,CAAC;AACJ,CAAC"}

package/dist/internal/planning/plan-fields.d.ts

@@ -0,0 +1,60 @@
+import { type Address } from '@solana/kit';
+export type UnknownRecord = Record<string, unknown>;
+export declare const MAX_U64 = 18446744073709551615n;
+/** Rejects one Plan field with the shared recreate-or-hydrate remedy. */
+export declare function invalid(field: string, value: unknown, acceptedRange: string): never;
+export declare function readRecord(value: unknown, field: string): UnknownRecord;
+export declare function assertKeys(value: UnknownRecord, field: string, required: readonly string[], optional?: readonly string[]): void;
+export declare function readString(value: unknown, field: string): string;
+export declare function readAddress(value: unknown, field: string): Address;
+/** An integer, or with `finite` any finite number, in an inclusive range. */
+export interface NumberField {
+    readonly min: number;
+    readonly max: number;
+    readonly accepted: string;
+    readonly finite?: true;
+}
+/** A bigint in an inclusive range; Plan JSON carries a canonical decimal string. */
+export interface BigIntField {
+    readonly min: bigint;
+    readonly max: bigint;
+    readonly accepted: string;
+}
+/** One of a fixed set of values. */
+export interface TokenField {
+    readonly values: readonly unknown[];
+    readonly accepted: string;
+}
+/** How one Plan guard field is validated in memory and decoded from Plan JSON. */
+export type GuardFieldType = 'address' | 'hash' | 'string' | 'text' | 'label' | NumberField | BigIntField | TokenField;
+/** A guard field: key, type and whether it may be omitted. */
+export type GuardFieldEntry = readonly [
+    key: string,
+    type: GuardFieldType,
+    optional?: true
+];
+/** One flat guard kind; field order is the normalized and serialized order. */
+export interface GuardSchema {
+    readonly fields: readonly GuardFieldEntry[];
+    /** Extra fields for the guard's validated `status`, keyed by status value.
+     * Requires a `status` field; a status without an entry adds no fields.
+     */
+    readonly byStatus?: Readonly<Record<string, readonly GuardFieldEntry[]>>;
+    /** Cross-field invariants, evaluated after every field is valid. */
+    readonly check?: (guard: UnknownRecord) => boolean;
+    /** Replaces every field-level error with one safeguard-level error. */
+    readonly error?: {
+        readonly accepted: string;
+        readonly remedy: string;
+    };
+}
+/** Validates one flat guard against its schema; `wire` decodes Plan JSON values.
+ * The result is frozen, with `kind` first, fields in schema order and
+ * `describes` last.
+ */
+export declare function normalizeSchemaGuard(guard: UnknownRecord, field: string, schema: GuardSchema, wire: boolean): UnknownRecord;
+/** Converts a guard to Plan JSON: bigint values become decimal strings and
+ * undefined members are omitted, at every depth, preserving key order.
+ */
+export declare function guardToWire(value: unknown): unknown;
+//# sourceMappingURL=plan-fields.d.ts.map

package/dist/internal/planning/plan-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-fields.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/plan-fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAItD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,eAAO,MAAM,OAAO,wBAAsB,CAAC;AAK3C,yEAAyE;AACzE,wBAAgB,OAAO,CACrB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,MAAM,GACpB,KAAK,CAOP;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAKvE;AAED,wBAAgB,UAAU,CACxB,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,GAAE,SAAS,MAAM,EAAO,GAC/B,IAAI,CAWN;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAIlE;AAED,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC;CACxB;AAED,oFAAoF;AACpF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,oCAAoC;AACpC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,kFAAkF;AAClF,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,WAAW,GACX,WAAW,GACX,UAAU,CAAC;AAEf,8DAA8D;AAC9D,MAAM,MAAM,eAAe,GAAG,SAAS;IACrC,GAAG,EAAE,MAAM;IACX,IAAI,EAAE,cAAc;IACpB,QAAQ,CAAC,EAAE,IAAI;CAChB,CAAC;AAEF,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAC5C;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC,CAAC,CAAC;IACzE,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC;IACnD,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACzE;AAoGD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,OAAO,GACZ,aAAa,CA2Cf;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASnD"}

package/dist/internal/planning/plan-fields.js

@@ -0,0 +1,159 @@
+import { isAddress } from '@solana/kit';
+import { InvalidActionInputError } from '../../client/errors.js';
+export const MAX_U64 = 0xffffffffffffffffn;
+const DATA_HASH_PATTERN = /^[\da-f]{64}$/u;
+const UNSIGNED_DECIMAL = /^(0|[1-9][0-9]*)$/u;
+const SIGNED_DECIMAL = /^(0|-?[1-9][0-9]*)$/u;
+/** Rejects one Plan field with the shared recreate-or-hydrate remedy. */
+export function invalid(field, value, acceptedRange) {
+    throw new InvalidActionInputError(field, value, acceptedRange, 'Correct this Plan field and recreate or hydrate the Plan before retrying.');
+}
+export function readRecord(value, field) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return invalid(field, value, 'a plain object');
+    }
+    return value;
+}
+export function assertKeys(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(', ')}`);
+    }
+}
+export function readString(value, field) {
+    return typeof value === 'string' ? value : invalid(field, value, 'a string');
+}
+export function readAddress(value, field) {
+    return typeof value === 'string' && isAddress(value)
+        ? value
+        : invalid(field, value, 'a valid base58 Solana address');
+}
+const LABEL_ACCEPTED = 'a nonblank, NUL-free Unicode label of at most 64 UTF-8 bytes';
+function readLabel(value, field, fail) {
+    if (typeof value !== 'string')
+        return fail(field, value, 'a string');
+    const bytes = new TextEncoder().encode(value);
+    if (value.trim().length === 0 ||
+        value.includes('\0') ||
+        bytes.length > 64 ||
+        new TextDecoder('utf-8', { ignoreBOM: true }).decode(bytes) !== value)
+        fail(field, value, LABEL_ACCEPTED);
+    return value;
+}
+function readField(type, value, field, wire, fail) {
+    if (type === 'address')
+        return typeof value === 'string' && isAddress(value)
+            ? value
+            : fail(field, value, 'a valid base58 Solana address');
+    if (type === 'hash')
+        return typeof value === 'string' && DATA_HASH_PATTERN.test(value)
+            ? value
+            : fail(field, value, 'a lowercase 64-character SHA-256 hex digest');
+    if (type === 'string')
+        return typeof value === 'string' ? value : fail(field, value, 'a string');
+    if (type === 'text')
+        return typeof value === 'string' && value.trim().length > 0
+            ? value
+            : fail(field, value, 'a nonblank string');
+    if (type === 'label')
+        return readLabel(value, field, fail);
+    if ('values' in type)
+        return type.values.includes(value)
+            ? value
+            : fail(field, value, type.accepted);
+    if (typeof type.min === 'bigint') {
+        let parsed = value;
+        if (wire) {
+            const signed = type.min < 0n;
+            if (typeof value !== 'string' ||
+                !(signed ? SIGNED_DECIMAL : UNSIGNED_DECIMAL).test(value))
+                fail(field, value, signed
+                    ? 'a canonical decimal string'
+                    : 'a canonical unsigned decimal string');
+            parsed = BigInt(value);
+        }
+        return typeof parsed === 'bigint' &&
+            parsed >= type.min &&
+            parsed <= type.max
+            ? parsed
+            : fail(field, parsed, type.accepted);
+    }
+    const range = type;
+    return typeof value === 'number' &&
+        (range.finite ? Number.isFinite(value) : Number.isInteger(value)) &&
+        value >= range.min &&
+        value <= range.max
+        ? value
+        : fail(field, value, range.accepted);
+}
+/** Fields for the guard's `status` variant. The status is validated against
+ * its `status` field type before the exact-key check, and only own `byStatus`
+ * entries are used, so an inherited name such as `__proto__` is a typed status
+ * error, never a prototype lookup. A missing status is left to the exact-key
+ * check.
+ */
+function variantFields(guard, field, schema, wire, fail) {
+    const variants = schema.byStatus;
+    if (variants === undefined || !Object.hasOwn(guard, 'status'))
+        return [];
+    const [, type] = schema.fields.find(([key]) => key === 'status');
+    const status = readField(type, guard.status, `${field}.status`, wire, fail);
+    return typeof status === 'string' && Object.hasOwn(variants, status)
+        ? variants[status]
+        : [];
+}
+/** Validates one flat guard against its schema; `wire` decodes Plan JSON values.
+ * The result is frozen, with `kind` first, fields in schema order and
+ * `describes` last.
+ */
+export function normalizeSchemaGuard(guard, field, schema, wire) {
+    const fail = schema.error === undefined
+        ? invalid
+        : () => {
+            throw new InvalidActionInputError(String(guard.kind), guard, schema.error.accepted, schema.error.remedy);
+        };
+    const fields = [
+        ...schema.fields,
+        ...variantFields(guard, field, schema, wire, fail),
+    ];
+    // `describes` closes every guard, after any status-specific fields.
+    const entries = [
+        ...fields.filter(([key]) => key !== 'describes'),
+        ...fields.filter(([key]) => key === 'describes'),
+    ];
+    const keys = (optional) => entries.filter((entry) => (entry[2] === true) === optional).map(([k]) => k);
+    try {
+        assertKeys(guard, field, ['kind', ...keys(false)], keys(true));
+    }
+    catch (error) {
+        if (schema.error === undefined)
+            throw error;
+        fail(field, guard, 'exact guard fields');
+    }
+    const normalized = { kind: guard.kind };
+    for (const [key, type, optional] of entries) {
+        if (optional === true && guard[key] === undefined)
+            continue;
+        normalized[key] = readField(type, guard[key], `${field}.${key}`, wire, fail);
+    }
+    if (schema.check !== undefined && !schema.check(normalized))
+        fail(field, guard, 'internally consistent guard fields');
+    return Object.freeze(normalized);
+}
+/** Converts a guard to Plan JSON: bigint values become decimal strings and
+ * undefined members are omitted, at every depth, preserving key order.
+ */
+export function guardToWire(value) {
+    if (typeof value === 'bigint')
+        return String(value);
+    if (Array.isArray(value))
+        return value.map(guardToWire);
+    if (value === null || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, member]) => member !== undefined)
+        .map(([key, member]) => [key, guardToWire(member)]));
+}
+//# sourceMappingURL=plan-fields.js.map