@aephia/atlas-kit 0.4.0 → 0.6.0-next.1

package/dist/crafting/actions/index.js

@@ -0,0 +1,728 @@
+import { getAddressEncoder, getBytesEncoder, getProgramDerivedAddress, isAddress, } from '@solana/kit';
+import { InvalidActionInputError, SageSdkError } from '../../client/errors.js';
+import { readContextRawAccounts } from '../../client/reconciliation.js';
+import { sage } from '../../internal/c4/bindings.js';
+import { craftingHabAccountDefinition, craftingProcessAccountDefinition, deriveRecipeAddress, recipeAccountDefinition, } from '../../internal/c4/crafting.js';
+import { characterAccountDefinition, findCharacterPda, } from '../../internal/c4/identity.js';
+import { deriveStarbasePlayerAddress, starbasePlayerAccountDefinition, } from '../../internal/c4/starbase.js';
+import { deriveInternalCraftingProcessState } from '../../internal/crafting-process-state.js';
+import { requireGameAddress } from '../../internal/game-context.js';
+import { adaptCancelCraftingProcessInstruction, adaptStartCraftingProcessInstruction, adaptCompleteCraftingProcessInstruction, validatePlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
+import { deriveStarSystemAddress, starSystemAccountDefinition, } from '../../internal/c4/world.js';
+import { createPlan, } from '../../planning/index.js';
+const U64_MAX = (1n << 64n) - 1n;
+const U32_MAX = 4_294_967_295;
+function invalid(field, value, acceptedRange, remedy) {
+    throw new InvalidActionInputError(field, value, acceptedRange, remedy);
+}
+function readRecord(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 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(', ')}`, `Remove unknown fields and provide every required ${field} field before retrying.`);
+    }
+}
+function readAddress(value, field) {
+    if (typeof value !== 'string' || !isAddress(value)) {
+        return invalid(field, value, 'one valid z.ink/Solana account address', `Set ${field} to the documented account address before retrying.`);
+    }
+    return value;
+}
+function validateStartOptions(value) {
+    const options = readRecord(value, 'options');
+    assertKeys(options, 'options', ['authorization', 'craftingProcess', 'quantity', 'numCrew'], ['craftingHab']);
+    const authorizationRecord = readRecord(options.authorization, 'authorization');
+    assertKeys(authorizationRecord, 'authorization', ['profile', 'authority', 'keyIndex'], ['certificate']);
+    const authorization = authorizationRecord;
+    readAddress(authorization.profile, 'authorization.profile');
+    readAddress(authorization.authority, 'authorization.authority');
+    if (authorization.certificate !== undefined) {
+        readAddress(authorization.certificate, 'authorization.certificate');
+    }
+    validatePlanAuthorization(authorization);
+    if (typeof options.quantity !== 'bigint' ||
+        options.quantity <= 0n ||
+        options.quantity > U64_MAX) {
+        invalid('quantity', options.quantity, `a positive raw bigint from 1 through ${String(U64_MAX)} (unsigned u64)`, 'Set quantity to the exact positive Recipe quantity within the instruction codec range.');
+    }
+    if (typeof options.numCrew !== 'number' ||
+        !Number.isInteger(options.numCrew) ||
+        options.numCrew < 0 ||
+        options.numCrew > U32_MAX) {
+        invalid('numCrew', options.numCrew, `an integer from 0 through ${String(U32_MAX)} (unsigned u32)`, 'Set numCrew to the exact available crew count within the instruction codec range.');
+    }
+    return {
+        authorization,
+        craftingProcess: readAddress(options.craftingProcess, 'craftingProcess'),
+        numCrew: options.numCrew,
+        quantity: options.quantity,
+        ...(options.craftingHab === undefined
+            ? {}
+            : { craftingHab: options.craftingHab }),
+    };
+}
+function validateCompleteOptions(value) {
+    const options = readRecord(value, 'options');
+    assertKeys(options, 'options', ['authorization', 'atUnixSeconds']);
+    const authorizationRecord = readRecord(options.authorization, 'authorization');
+    assertKeys(authorizationRecord, 'authorization', ['profile', 'authority', 'keyIndex'], ['certificate']);
+    const authorization = authorizationRecord;
+    readAddress(authorization.profile, 'authorization.profile');
+    readAddress(authorization.authority, 'authorization.authority');
+    if (authorization.certificate !== undefined) {
+        readAddress(authorization.certificate, 'authorization.certificate');
+    }
+    validatePlanAuthorization(authorization);
+    if (typeof options.atUnixSeconds !== 'bigint' || options.atUnixSeconds < 0n) {
+        invalid('atUnixSeconds', options.atUnixSeconds, 'a non-negative bigint Unix timestamp', 'Set atUnixSeconds to the explicit current Unix timestamp before retrying.');
+    }
+    return { atUnixSeconds: options.atUnixSeconds, authorization };
+}
+function validateCancelOptions(value) {
+    const options = readRecord(value, 'options');
+    assertKeys(options, 'options', ['authorization', 'atUnixSeconds']);
+    const authorizationRecord = readRecord(options.authorization, 'authorization');
+    assertKeys(authorizationRecord, 'authorization', ['profile', 'authority', 'keyIndex'], ['certificate']);
+    const authorization = authorizationRecord;
+    readAddress(authorization.profile, 'authorization.profile');
+    readAddress(authorization.authority, 'authorization.authority');
+    if (authorization.certificate !== undefined) {
+        readAddress(authorization.certificate, 'authorization.certificate');
+    }
+    validatePlanAuthorization(authorization);
+    if (typeof options.atUnixSeconds !== 'bigint' || options.atUnixSeconds < 0n) {
+        invalid('atUnixSeconds', options.atUnixSeconds, 'a non-negative bigint Unix timestamp', 'Set atUnixSeconds to the explicit current Unix timestamp before retrying.');
+    }
+    return { atUnixSeconds: options.atUnixSeconds, authorization };
+}
+function fail(message, address) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', message, { address });
+}
+function requireAccount(account, address, message) {
+    return account ?? fail(message, address);
+}
+function balance(items, cargoId) {
+    return items.find((item) => item.id === cargoId)?.quantityRaw ?? 0n;
+}
+function sameBalances(snapshot, account) {
+    if (snapshot.length !== account.length)
+        return false;
+    const seen = new Set();
+    return snapshot.every((item) => {
+        if (seen.has(item.id))
+            return false;
+        seen.add(item.id);
+        return account.some((amount) => amount.cargoId === item.id && amount.quantityRaw === item.quantityRaw);
+    });
+}
+function sameStarbaseBalances(snapshot, account) {
+    return sameBalances(snapshot, account.map(({ amount, cargoId }) => ({ cargoId, quantityRaw: amount })));
+}
+function validateKnownInputs(recipe, items, quantity, source, sourceAddress) {
+    for (const ingredient of recipe.ingredients) {
+        const required = ingredient.quantityRaw * quantity;
+        const available = balance(items, ingredient.id);
+        if (available < required) {
+            fail(`${source} ${sourceAddress} ${ingredient.name} has ${String(available)} raw units, but Recipe ${recipe.name} requires ${String(required)} for quantity ${String(quantity)}. Add the missing input cargo, refresh the ${source}, and retry.`, sourceAddress);
+        }
+    }
+}
+async function deriveCurrencyCacheAddress(game) {
+    const [address] = await getProgramDerivedAddress({
+        programAddress: sage.SAGE_PROGRAM_ADDRESS,
+        seeds: [
+            getBytesEncoder().encode(new TextEncoder().encode('CurrencyConfig')),
+            getAddressEncoder().encode(game),
+        ],
+    });
+    return address;
+}
+function validateCurrencyCache(account, game, canonicalAddress) {
+    const decoder = sage.getCurrencyConfigCacheDecoder();
+    const validDiscriminator = sage.CURRENCY_CONFIG_CACHE_DISCRIMINATOR.every((byte, index) => account.data[index] === byte);
+    if (account.address !== canonicalAddress ||
+        account.owner !== sage.SAGE_PROGRAM_ADDRESS ||
+        account.data.length !== decoder.fixedSize ||
+        !validDiscriminator ||
+        decoder.decode(account.data).gameId !== game) {
+        fail(`CurrencyCache ${account.address} does not match the configured Game, canonical PDA, owner, or pinned account layout. Refresh the Game currency configuration and retry.`, account.address);
+    }
+}
+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',
+    });
+}
+async function resolveAccounts(ctx, recipe, player, options, game) {
+    const character = await findCharacterPda(options.authorization.profile, game);
+    const currencyCache = options.craftingHab === undefined
+        ? undefined
+        : await deriveCurrencyCacheAddress(game);
+    const addresses = [
+        character,
+        player.address,
+        recipe.address,
+        options.craftingProcess,
+        ...(options.craftingHab === undefined
+            ? []
+            : [options.craftingHab.address, currencyCache]),
+    ];
+    const reads = await readContextRawAccounts(ctx, addresses);
+    const characterAccount = requireAccount(reads[0], character, `Canonical Character ${character} is missing for Profile ${options.authorization.profile}. Create or repair the Character in the configured Game, refresh the Starbase Player, and retry.`);
+    const playerAccount = requireAccount(reads[1], player.address, `Starbase Player ${player.address} is missing. Refresh the Starbase Player and retry starting the Crafting Process.`);
+    const recipeAccount = requireAccount(reads[2], recipe.address, `Recipe ${recipe.address} is missing. Refresh the Recipe and retry starting the Crafting Process.`);
+    if (reads[3] !== undefined) {
+        fail(`Crafting Process ${options.craftingProcess} already exists. Choose a new signer address for the new Crafting Process and retry.`, options.craftingProcess);
+    }
+    const characterData = characterAccountDefinition.decode(characterAccount);
+    if (characterAccount.address !== character ||
+        characterData.playerProfile !== options.authorization.profile ||
+        characterData.game !== game) {
+        fail(`The canonical Character does not match Profile ${options.authorization.profile} and the configured Game ${game}. Refresh or repair the Character relationship before retrying.`, characterAccount.address);
+    }
+    const playerData = starbasePlayerAccountDefinition.decode(playerAccount);
+    const canonicalPlayer = await deriveStarbasePlayerAddress(playerData.system, playerData.character);
+    if (playerAccount.address !== player.address ||
+        canonicalPlayer !== player.address ||
+        playerData.playerProfile !== options.authorization.profile ||
+        playerData.system !== player.system.address ||
+        playerData.character !== character ||
+        Math.max(0, playerData.totalCrew - playerData.busyCrew) !==
+            player.availableCrew ||
+        !sameStarbaseBalances(player.cargo.items, playerData.cargo.amounts)) {
+        fail(`Starbase Player ${player.address} changed or does not match its canonical System, Character, Profile, crew, or cargo relationships. Refresh the Starbase Player through this context and retry.`, player.address);
+    }
+    const recipeData = recipeAccountDefinition.decode(recipeAccount);
+    const canonicalRecipe = await deriveRecipeAddress(game, recipeData.id);
+    if (recipeAccount.address !== recipe.address ||
+        canonicalRecipe !== recipe.address ||
+        recipeData.game !== game ||
+        recipeData.id !== recipe.id ||
+        recipeData.status !== recipe.status ||
+        recipeData.habRequired !== recipe.habRequired ||
+        recipeData.usageCountRaw !== recipe.usageCountRaw ||
+        recipeData.usageLimitRaw !== recipe.usageLimitRaw ||
+        !sameBalances(recipe.ingredients, recipeData.inputs)) {
+        fail(`Recipe ${recipe.address} changed or does not match the configured Game, canonical PDA, status, limits, or ingredients. Refresh the Recipe through this context and retry.`, recipe.address);
+    }
+    if (options.craftingHab === undefined) {
+        return { character, characterAccount, playerAccount, recipeAccount };
+    }
+    const habAccount = requireAccount(reads[4], options.craftingHab.address, `Crafting Hab ${options.craftingHab.address} is missing. Refresh the Hab and retry starting the Crafting Process.`);
+    const currencyCacheAccount = requireAccount(reads[5], currencyCache, `Canonical CurrencyCache ${currencyCache} is missing for the configured Game. Refresh the Game currency configuration and retry.`);
+    const habData = craftingHabAccountDefinition.decode(habAccount);
+    if (habAccount.address !== options.craftingHab.address ||
+        habData.game !== game ||
+        habData.ownerProfile !== options.authorization.profile ||
+        habData.system !== player.system.address ||
+        habData.state.kind !== options.craftingHab.state.kind ||
+        Math.max(0, habData.jobCapacity - habData.jobsRunning) !==
+            options.craftingHab.availableJobSlots ||
+        !habData.unlockedRecipeIds.includes(recipe.id) ||
+        !sameBalances(options.craftingHab.production.inventory.items, habData.production.inventory.amounts)) {
+        fail(`Crafting Hab ${options.craftingHab.address} changed or does not match its Game, Profile, System, active capacity, unlocked Recipe, or production inventory. Refresh the Crafting Hab through this context and retry.`, options.craftingHab.address);
+    }
+    validateCurrencyCache(currencyCacheAccount, game, currencyCache);
+    return {
+        character,
+        characterAccount,
+        currencyCache: currencyCache,
+        currencyCacheAccount,
+        habAccount,
+        playerAccount,
+        recipeAccount,
+    };
+}
+/** Plans one Crafting Process start without signing, simulation, or writes.
+ *
+ * The planner validates the loaded Recipe and Starbase Player, optional Hab,
+ * known ingredient balances, available crew, and exact whole-account state. It
+ * returns one inert Plan whose two required signer roles are bound only during
+ * execution.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const recipe: RecipeSnapshot;
+ * declare const player: StarbasePlayerSnapshot;
+ * declare const options: PlanStartCraftingProcessOptions;
+ * const plan = await planStartCraftingProcess(ctx, recipe, player, options);
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planStartCraftingProcess(ctx, recipe, player, input) {
+    const options = validateStartOptions(input);
+    const game = requireGameAddress(ctx);
+    const canonicalRecipe = await deriveRecipeAddress(game, recipe.id);
+    if (recipe.game.address !== game || canonicalRecipe !== recipe.address) {
+        fail(`Recipe ${recipe.address} does not match the configured Game ${game} or its canonical recipe-id PDA. Refresh the Recipe through this context and retry.`, recipe.address);
+    }
+    if (player.playerProfile.address !== options.authorization.profile) {
+        fail(`Starbase Player ${player.address} does not belong to authorization Profile ${options.authorization.profile}. Refresh the Starbase Player for that Profile and retry.`, player.address);
+    }
+    const canonicalPlayer = await deriveStarbasePlayerAddress(player.system.address, player.character.address);
+    if (canonicalPlayer !== player.address) {
+        fail(`Starbase Player ${player.address} is not canonical for its Character and System. Refresh the Starbase Player through this context and retry.`, player.address);
+    }
+    if (recipe.status !== 'active') {
+        fail(`Recipe ${recipe.name} is ${recipe.status}, so it cannot start a Crafting Process. Choose an active Recipe, refresh it, and retry.`, recipe.address);
+    }
+    if (recipe.usageLimitRaw !== 0n &&
+        (recipe.usageCountRaw >= recipe.usageLimitRaw ||
+            options.quantity > recipe.usageLimitRaw - recipe.usageCountRaw)) {
+        const remaining = recipe.usageCountRaw >= recipe.usageLimitRaw
+            ? 0n
+            : recipe.usageLimitRaw - recipe.usageCountRaw;
+        fail(`Recipe ${recipe.name} usage limit has remaining ${String(remaining)}, but requested ${String(options.quantity)}. Reduce quantity or choose another active Recipe before retrying.`, recipe.address);
+    }
+    if (options.numCrew > player.availableCrew) {
+        fail(`Starbase Player ${player.address} has only ${String(player.availableCrew)} crew available, but numCrew requested ${String(options.numCrew)}. Reduce numCrew or free crew, refresh the Starbase Player, and retry.`, player.address);
+    }
+    if (recipe.habRequired && options.craftingHab === undefined) {
+        fail(`Recipe ${recipe.name} requires a Crafting Hab. Provide craftingHab from the same Profile and Star System before retrying.`, recipe.address);
+    }
+    if (options.craftingHab !== undefined) {
+        if (options.craftingHab.game.address !== game) {
+            fail(`Crafting Hab ${options.craftingHab.address} does not match the configured Game ${game}. Refresh the Crafting Hab through this context and retry.`, options.craftingHab.address);
+        }
+        if (options.craftingHab.ownerProfile.address !== options.authorization.profile) {
+            fail(`Crafting Hab ${options.craftingHab.address} does not belong to Profile ${options.authorization.profile}. Choose a Hab owned by the authorization Profile and retry.`, options.craftingHab.address);
+        }
+        if (options.craftingHab.system.address !== player.system.address) {
+            fail(`Crafting Hab ${options.craftingHab.address} is not at Starbase Player System ${player.system.address}. Choose a Hab at the same Starbase and retry.`, options.craftingHab.address);
+        }
+        if (options.craftingHab.state.kind !== 'active') {
+            fail(`Crafting Hab ${options.craftingHab.address} is ${options.craftingHab.state.kind}; it must be active before starting a Crafting Process. Refresh or reactivate the Hab and retry.`, options.craftingHab.address);
+        }
+        if (options.craftingHab.availableJobSlots < 1) {
+            fail(`Crafting Hab ${options.craftingHab.address} has no available job slots. Complete or cancel another Hab job, refresh it, and retry.`, options.craftingHab.address);
+        }
+        if (!options.craftingHab.unlockedRecipes.some(({ address }) => address === recipe.address)) {
+            fail(`Crafting Hab ${options.craftingHab.address} has not unlocked Recipe ${recipe.name}. Choose an unlocked Recipe or update the Hab before retrying.`, options.craftingHab.address);
+        }
+        validateKnownInputs(recipe, options.craftingHab.production.inventory.items, options.quantity, 'Crafting Hab', options.craftingHab.address);
+    }
+    else {
+        validateKnownInputs(recipe, player.cargo.items, options.quantity, 'Starbase Player', player.address);
+    }
+    const resolved = await resolveAccounts(ctx, recipe, player, options, game);
+    const description = `Start crafting ${String(options.quantity)} units of ${recipe.name} with ${String(options.numCrew)} crew at Starbase Player ${player.address}.`;
+    const preconditions = [
+        precondition(resolved.characterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game.`),
+        precondition(resolved.playerAccount, `Starbase Player ${player.address} retains its Character, Profile, System, crew, and input inventory.`),
+        precondition(resolved.recipeAccount, `Recipe ${recipe.name} remains active with the validated usage limit and ingredients.`),
+        ...(resolved.habAccount === undefined
+            ? []
+            : [
+                precondition(resolved.habAccount, `Crafting Hab ${resolved.habAccount.address} remains active with an available job slot, the Recipe unlocked, and sufficient inputs.`),
+                precondition(resolved.currencyCacheAccount, 'The canonical CurrencyCache remains assigned to the configured Game for Hab crafting.'),
+            ]),
+    ];
+    return createPlan({
+        kind: 'crafting.start-process',
+        preconditions: await Promise.all(preconditions),
+        steps: [
+            {
+                describes: description,
+                instruction: adaptStartCraftingProcessInstruction({
+                    authorization: options.authorization,
+                    character: resolved.character,
+                    craftingProcess: options.craftingProcess,
+                    game,
+                    numCrew: options.numCrew,
+                    quantity: options.quantity,
+                    recipe: recipe.address,
+                    starbasePlayer: player.address,
+                    system: player.system.address,
+                    ...(options.craftingHab === undefined
+                        ? {}
+                        : {
+                            craftingHabInstance: options.craftingHab.address,
+                            currencyCache: resolved.currencyCache,
+                        }),
+                }),
+                signers: [options.authorization.authority, options.craftingProcess],
+            },
+        ],
+        summary: description,
+    });
+}
+function sameProcessSnapshot(process, account) {
+    return (account.version === process.version &&
+        account.recipe === process.recipe.address &&
+        account.profile === process.profile.address &&
+        account.system === process.system.address &&
+        account.starbasePlayer === process.starbasePlayer.address &&
+        account.starbaseSequenceId === process.starbaseSequenceId &&
+        account.craftingHab === process.craftingHab.address &&
+        account.quantityRaw === process.quantityRaw &&
+        account.numCrew === process.numCrew &&
+        account.startsAtUnixSeconds === process.startsAtUnixSeconds &&
+        account.endsAtUnixSeconds === process.endsAtUnixSeconds &&
+        account.feeEscrowRaw === process.feeEscrowRaw &&
+        account.inputs.sequenceId === process.inputs.sequenceId &&
+        account.inputs.storageCostRaw === process.inputs.usedStorageUnitsRaw &&
+        sameBalances(process.inputs.items, account.inputs.amounts));
+}
+function validateGameRead(account, game) {
+    if (account.address !== game ||
+        account.owner !== sage.SAGE_PROGRAM_ADDRESS ||
+        account.data.length < sage.GAME_DISCRIMINATOR.length ||
+        !sage.GAME_DISCRIMINATOR.every((byte, index) => account.data[index] === byte)) {
+        fail(`Game ${account.address} does not match the configured address, owner, or pinned account layout. Refresh the configured Game and retry.`, account.address);
+    }
+}
+async function resolveCompleteAccounts(ctx, process, options, game) {
+    const character = await findCharacterPda(options.authorization.profile, game);
+    const currencyCache = await deriveCurrencyCacheAddress(game);
+    const habAddress = process.craftingHab.address === sage.SAGE_PROGRAM_ADDRESS
+        ? undefined
+        : process.craftingHab.address;
+    const addresses = [
+        process.address,
+        process.recipe.address,
+        process.starbasePlayer.address,
+        process.system.address,
+        ...(habAddress === undefined ? [] : [habAddress]),
+        character,
+        game,
+        currencyCache,
+    ];
+    const reads = await readContextRawAccounts(ctx, addresses);
+    const byAddress = new Map(addresses.map((address, index) => [address, reads[index]]));
+    const processAccount = requireAccount(byAddress.get(process.address), process.address, `Crafting Process ${process.address} is missing, so it may already be cancelled or closed. Refresh the Crafting Process and retry only if it still exists.`);
+    const recipeAccount = requireAccount(byAddress.get(process.recipe.address), process.recipe.address, `Recipe ${process.recipe.address} is missing. Refresh the Crafting Process and its Recipe before retrying completion.`);
+    const playerAccount = requireAccount(byAddress.get(process.starbasePlayer.address), process.starbasePlayer.address, `Starbase Player ${process.starbasePlayer.address} is missing. Refresh the Crafting Process and Starbase Player before retrying completion.`);
+    const systemAccount = requireAccount(byAddress.get(process.system.address), process.system.address, `Star System ${process.system.address} is missing. Refresh the Crafting Process and Star System before retrying completion.`);
+    const characterAccount = requireAccount(byAddress.get(character), character, `Canonical Character ${character} is missing for Profile ${options.authorization.profile}. Create or repair the Character in the configured Game before retrying completion.`);
+    const gameAccount = requireAccount(byAddress.get(game), game, `Configured Game ${game} is missing. Refresh the configured Game before retrying completion.`);
+    const currencyCacheAccount = requireAccount(byAddress.get(currencyCache), currencyCache, `Canonical CurrencyCache ${currencyCache} is missing for the configured Game. Refresh the Game currency configuration before retrying completion.`);
+    const habAccount = habAddress === undefined
+        ? undefined
+        : requireAccount(byAddress.get(habAddress), habAddress, `Crafting Hab ${habAddress} is missing. Refresh the Crafting Process and Hab before retrying completion.`);
+    const processData = craftingProcessAccountDefinition.decode(processAccount);
+    if (processAccount.address !== process.address ||
+        !sameProcessSnapshot(process, processData)) {
+        fail(`Crafting Process ${process.address} changed or no longer matches its relationships, timing, crew, quantity, fee, or inputs. Refresh the Crafting Process and retry.`, process.address);
+    }
+    const recipeData = recipeAccountDefinition.decode(recipeAccount);
+    const canonicalRecipe = await deriveRecipeAddress(game, recipeData.id);
+    if (recipeAccount.address !== process.recipe.address ||
+        canonicalRecipe !== process.recipe.address ||
+        recipeData.game !== game ||
+        recipeData.id !== process.recipe.id ||
+        recipeData.name !== process.recipe.name ||
+        recipeData.status !== process.recipe.status ||
+        recipeData.habRequired !== process.recipe.habRequired ||
+        recipeData.usageCountRaw !== process.recipe.usageCountRaw ||
+        recipeData.usageLimitRaw !== process.recipe.usageLimitRaw ||
+        !sameBalances(process.recipe.ingredients, recipeData.inputs) ||
+        !sameBalances(process.recipe.outputs, recipeData.outputs)) {
+        fail(`Recipe ${process.recipe.address} changed or does not match the configured Game, canonical recipe-id PDA, status, Hab policy, limits, ingredients, or outputs. Refresh the Crafting Process and Recipe before retrying completion.`, process.recipe.address);
+    }
+    if (recipeData.habRequired && habAddress === undefined) {
+        fail(`Recipe ${recipeData.name} requires a Crafting Hab, but Crafting Process ${process.address} omits one. Refresh or repair the Process relationship before retrying completion.`, process.address);
+    }
+    const playerData = starbasePlayerAccountDefinition.decode(playerAccount);
+    const canonicalPlayer = await deriveStarbasePlayerAddress(process.system.address, character);
+    if (playerAccount.address !== process.starbasePlayer.address ||
+        canonicalPlayer !== process.starbasePlayer.address ||
+        playerData.playerProfile !== options.authorization.profile ||
+        playerData.character !== character ||
+        playerData.system !== process.system.address) {
+        fail(`Starbase Player ${process.starbasePlayer.address} does not match the authorization Profile, canonical Character, or Crafting Process System. Refresh the Crafting Process and Starbase Player before retrying completion.`, process.starbasePlayer.address);
+    }
+    const systemData = starSystemAccountDefinition.decode(systemAccount);
+    const canonicalSystem = await deriveStarSystemAddress(game, systemData.systemId);
+    if (systemAccount.address !== process.system.address ||
+        canonicalSystem !== process.system.address ||
+        systemData.game !== game ||
+        systemData.sequenceId !== process.starbaseSequenceId ||
+        systemData.starbase === undefined) {
+        fail(`Star System ${process.system.address} does not match the configured Game, canonical system-id PDA, active Starbase, or Crafting Process Starbase sequence. Refresh the Crafting Process and Star System before retrying completion.`, process.system.address);
+    }
+    if (habAccount !== undefined) {
+        const habData = craftingHabAccountDefinition.decode(habAccount);
+        if (habAccount.address !== habAddress ||
+            habData.game !== game ||
+            habData.ownerProfile !== options.authorization.profile ||
+            habData.system !== process.system.address ||
+            habData.systemSequenceId !== process.starbaseSequenceId ||
+            habData.state.kind !== 'active') {
+            fail(`Crafting Hab ${habAddress} is not active or does not match the configured Game, authorization Profile, Crafting Process System, or Starbase sequence. Refresh the Crafting Process and Hab before retrying completion.`, habAccount.address);
+        }
+    }
+    const characterData = characterAccountDefinition.decode(characterAccount);
+    if (characterAccount.address !== character ||
+        characterData.playerProfile !== options.authorization.profile ||
+        characterData.game !== game) {
+        fail(`The canonical Character does not match Profile ${options.authorization.profile} and the configured Game ${game}. Refresh or repair the Character relationship before retrying completion.`, characterAccount.address);
+    }
+    validateGameRead(gameAccount, game);
+    validateCurrencyCache(currencyCacheAccount, game, currencyCache);
+    return {
+        character,
+        characterAccount,
+        currencyCache,
+        currencyCacheAccount,
+        gameAccount,
+        ...(habAccount === undefined ? {} : { habAccount }),
+        playerAccount,
+        processAccount,
+        recipeAccount,
+        systemAccount,
+    };
+}
+/** Plans completion of one Crafting Process without signing, simulation, or writes.
+ *
+ * The planner resolves and validates the Process account graph, requires Profile
+ * ownership, and checks the translated lifecycle at the caller-provided Unix
+ * timestamp. Output capacity, permissions, XP, closure, and final execution
+ * freshness remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const process: CraftingProcessSnapshot;
+ * declare const options: PlanCompleteCraftingProcessOptions;
+ * const plan = await planCompleteCraftingProcess(ctx, process, options);
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planCompleteCraftingProcess(ctx, process, input) {
+    const options = validateCompleteOptions(input);
+    const game = requireGameAddress(ctx);
+    if (process.profile.address !== options.authorization.profile) {
+        fail(`Crafting Process ${process.address} does not belong to authorization Profile ${options.authorization.profile}. Use the owning Profile, refresh the Process, and retry.`, process.address);
+    }
+    const state = deriveInternalCraftingProcessState(process, options.atUnixSeconds);
+    if (state.kind !== 'complete') {
+        const timing = state.kind === 'scheduled'
+            ? 'scheduled and not complete'
+            : `in-progress and not complete with ${String(state.remainingSeconds)} seconds remaining`;
+        fail(`Crafting Process ${process.address} is ${timing} at Unix timestamp ${String(options.atUnixSeconds)}. Wait until it is complete, provide a current timestamp, and retry.`, process.address);
+    }
+    const resolved = await resolveCompleteAccounts(ctx, process, options, game);
+    const description = `Complete crafting ${String(process.quantityRaw)} units of ${process.recipe.name} at Starbase Player ${process.starbasePlayer.address}, returning ${String(process.numCrew)} crew and producing the Recipe outputs.`;
+    const preconditions = [
+        precondition(resolved.processAccount, `Crafting Process ${process.address} retains its validated relationships, timing, crew, quantity, fee, and inputs.`),
+        precondition(resolved.recipeAccount, `Recipe ${process.recipe.name} retains its validated Game, Hab policy, ingredients, and outputs.`),
+        precondition(resolved.playerAccount, `Starbase Player ${process.starbasePlayer.address} retains its Profile, Character, and System relationships.`),
+        precondition(resolved.systemAccount, `Star System ${process.system.address} retains its active Starbase and validated sequence.`),
+        ...(resolved.habAccount === undefined
+            ? []
+            : [
+                precondition(resolved.habAccount, `Crafting Hab ${resolved.habAccount.address} remains active in the validated Game, Profile, System, and Starbase sequence.`),
+            ]),
+        precondition(resolved.characterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game.`),
+        precondition(resolved.gameAccount, `Game ${game} retains its pinned owner and account layout.`),
+        precondition(resolved.currencyCacheAccount, 'The canonical CurrencyCache remains assigned to the configured Game.'),
+    ];
+    return createPlan({
+        kind: 'crafting.complete-process',
+        preconditions: await Promise.all(preconditions),
+        steps: [
+            {
+                describes: description,
+                instruction: adaptCompleteCraftingProcessInstruction({
+                    authorization: options.authorization,
+                    character: resolved.character,
+                    craftingProcess: process.address,
+                    currencyCache: resolved.currencyCache,
+                    game,
+                    recipe: process.recipe.address,
+                    starbasePlayer: process.starbasePlayer.address,
+                    system: process.system.address,
+                    ...(resolved.habAccount === undefined
+                        ? {}
+                        : { craftingHabInstance: resolved.habAccount.address }),
+                }),
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: description,
+    });
+}
+async function resolveCancelAccounts(ctx, process, options, game) {
+    const character = await findCharacterPda(options.authorization.profile, game);
+    const habAddress = process.craftingHab.address === sage.SAGE_PROGRAM_ADDRESS
+        ? undefined
+        : process.craftingHab.address;
+    const addresses = [
+        process.address,
+        process.recipe.address,
+        process.starbasePlayer.address,
+        process.system.address,
+        ...(habAddress === undefined ? [] : [habAddress]),
+        character,
+        game,
+    ];
+    const reads = await readContextRawAccounts(ctx, addresses);
+    const byAddress = new Map(addresses.map((address, index) => [address, reads[index]]));
+    const processAccount = requireAccount(byAddress.get(process.address), process.address, `Crafting Process ${process.address} is missing, so it may already be completed, cancelled, or closed. Refresh the Crafting Process and retry only if it still exists.`);
+    const systemAccount = requireAccount(byAddress.get(process.system.address), process.system.address, `Star System ${process.system.address} is missing. Refresh the Crafting Process and Star System before retrying cancellation.`);
+    const processData = craftingProcessAccountDefinition.decode(processAccount);
+    if (processAccount.address !== process.address ||
+        !sameProcessSnapshot(process, processData)) {
+        fail(`Crafting Process ${process.address} changed or no longer matches its relationships, timing, crew, quantity, fee, or inputs. Refresh the Crafting Process and retry.`, process.address);
+    }
+    const systemData = starSystemAccountDefinition.decode(systemAccount);
+    const canonicalSystem = await deriveStarSystemAddress(game, systemData.systemId);
+    if (systemAccount.address !== process.system.address ||
+        canonicalSystem !== process.system.address ||
+        systemData.game !== game) {
+        fail(`Star System ${process.system.address} does not match the configured Game or canonical system-id PDA. Refresh the Crafting Process and Star System before retrying cancellation.`, process.system.address);
+    }
+    if (systemData.sequenceId !== process.starbaseSequenceId) {
+        fail(`The Starbase sequence for Crafting Process ${process.address} is stale at ${String(process.starbaseSequenceId)}, while Star System ${process.system.address} is at sequence ${String(systemData.sequenceId)}. The program requires destroyCraftingProcess for this destroyed-Starbase cleanup case; do not cancel the Process.`, process.address);
+    }
+    if (systemData.starbase === undefined) {
+        fail(`Star System ${process.system.address} does not have an active Starbase. Refresh the Crafting Process and Star System before retrying cancellation.`, process.system.address);
+    }
+    const recipeAccount = requireAccount(byAddress.get(process.recipe.address), process.recipe.address, `Recipe ${process.recipe.address} is missing. Refresh the Crafting Process and its Recipe before retrying cancellation.`);
+    const playerAccount = requireAccount(byAddress.get(process.starbasePlayer.address), process.starbasePlayer.address, `Starbase Player ${process.starbasePlayer.address} is missing. Refresh the Crafting Process and Starbase Player before retrying cancellation.`);
+    const characterAccount = requireAccount(byAddress.get(character), character, `Canonical Character ${character} is missing for Profile ${options.authorization.profile}. Create or repair the Character in the configured Game before retrying cancellation.`);
+    const gameAccount = requireAccount(byAddress.get(game), game, `Configured Game ${game} is missing. Refresh the configured Game before retrying cancellation.`);
+    const habAccount = habAddress === undefined
+        ? undefined
+        : requireAccount(byAddress.get(habAddress), habAddress, `Crafting Hab ${habAddress} is missing. Refresh the Crafting Process and Hab before retrying cancellation.`);
+    const recipeData = recipeAccountDefinition.decode(recipeAccount);
+    const canonicalRecipe = await deriveRecipeAddress(game, recipeData.id);
+    if (recipeAccount.address !== process.recipe.address ||
+        canonicalRecipe !== process.recipe.address ||
+        recipeData.game !== game ||
+        recipeData.id !== process.recipe.id ||
+        recipeData.name !== process.recipe.name ||
+        recipeData.status !== process.recipe.status ||
+        recipeData.habRequired !== process.recipe.habRequired ||
+        recipeData.usageCountRaw !== process.recipe.usageCountRaw ||
+        recipeData.usageLimitRaw !== process.recipe.usageLimitRaw ||
+        !sameBalances(process.recipe.ingredients, recipeData.inputs) ||
+        !sameBalances(process.recipe.outputs, recipeData.outputs)) {
+        fail(`Recipe ${process.recipe.address} changed or does not match the configured Game, canonical recipe-id PDA, status, Hab policy, limits, ingredients, or outputs. Refresh the Crafting Process and Recipe before retrying cancellation.`, process.recipe.address);
+    }
+    if (recipeData.habRequired && habAddress === undefined) {
+        fail(`Recipe ${recipeData.name} requires a Crafting Hab, but Crafting Process ${process.address} omits one. Refresh or repair the Process relationship before retrying cancellation.`, process.address);
+    }
+    const playerData = starbasePlayerAccountDefinition.decode(playerAccount);
+    const canonicalPlayer = await deriveStarbasePlayerAddress(process.system.address, character);
+    if (playerAccount.address !== process.starbasePlayer.address ||
+        canonicalPlayer !== process.starbasePlayer.address ||
+        playerData.playerProfile !== options.authorization.profile ||
+        playerData.character !== character ||
+        playerData.system !== process.system.address) {
+        fail(`Starbase Player ${process.starbasePlayer.address} does not match the authorization Profile, canonical Character, or Crafting Process System. Refresh the Crafting Process and Starbase Player before retrying cancellation.`, process.starbasePlayer.address);
+    }
+    if (habAccount !== undefined) {
+        const habData = craftingHabAccountDefinition.decode(habAccount);
+        if (habAccount.address !== habAddress ||
+            habData.game !== game ||
+            habData.ownerProfile !== options.authorization.profile ||
+            habData.system !== process.system.address ||
+            habData.systemSequenceId !== process.starbaseSequenceId ||
+            habData.state.kind !== 'active') {
+            fail(`Crafting Hab ${habAddress} is not active or does not match the configured Game, authorization Profile, Crafting Process System, or Starbase sequence. Refresh the Crafting Process and Hab before retrying cancellation.`, habAccount.address);
+        }
+    }
+    const characterData = characterAccountDefinition.decode(characterAccount);
+    if (characterAccount.address !== character ||
+        characterData.playerProfile !== options.authorization.profile ||
+        characterData.game !== game) {
+        fail(`The canonical Character does not match Profile ${options.authorization.profile} and the configured Game ${game}. Refresh or repair the Character relationship before retrying cancellation.`, characterAccount.address);
+    }
+    validateGameRead(gameAccount, game);
+    return {
+        character,
+        characterAccount,
+        gameAccount,
+        ...(habAccount === undefined ? {} : { habAccount }),
+        playerAccount,
+        processAccount,
+        recipeAccount,
+        systemAccount,
+    };
+}
+/** Plans cancellation of one unfinished Crafting Process without signing or writes.
+ *
+ * The planner resolves and validates the Process account graph, requires Profile
+ * ownership, and rejects completed or destroyed-Starbase Process snapshots.
+ * Final inventory capacity, permissions, returned inputs and crew, and account
+ * closure remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const process: CraftingProcessSnapshot;
+ * declare const options: PlanCancelCraftingProcessOptions;
+ * const plan = await planCancelCraftingProcess(ctx, process, options);
+ * console.log(plan.describe());
+ * ```
+ */
+export async function planCancelCraftingProcess(ctx, process, input) {
+    const options = validateCancelOptions(input);
+    const game = requireGameAddress(ctx);
+    if (process.profile.address !== options.authorization.profile) {
+        fail(`Crafting Process ${process.address} does not belong to authorization Profile ${options.authorization.profile}. Use the owning Profile, refresh the Process, and retry.`, process.address);
+    }
+    const state = deriveInternalCraftingProcessState(process, options.atUnixSeconds);
+    if (state.kind === 'complete') {
+        fail(`Crafting Process ${process.address} is complete at Unix timestamp ${String(options.atUnixSeconds)} and cannot be cancelled. Use planCompleteCraftingProcess with a refreshed snapshot instead.`, process.address);
+    }
+    const resolved = await resolveCancelAccounts(ctx, process, options, game);
+    const description = `Cancel crafting ${String(process.quantityRaw)} units of ${process.recipe.name} at Starbase Player ${process.starbasePlayer.address}, returning all inputs and ${String(process.numCrew)} crew and closing the Crafting Process.`;
+    const preconditions = [
+        precondition(resolved.processAccount, `Crafting Process ${process.address} retains its validated relationships, timing, crew, quantity, fee, and inputs.`),
+        precondition(resolved.recipeAccount, `Recipe ${process.recipe.name} retains its validated Game, Hab policy, usage, ingredients, and outputs.`),
+        precondition(resolved.playerAccount, `Starbase Player ${process.starbasePlayer.address} retains its Profile, Character, and System relationships.`),
+        precondition(resolved.systemAccount, `Star System ${process.system.address} retains its active Starbase and validated sequence.`),
+        ...(resolved.habAccount === undefined
+            ? []
+            : [
+                precondition(resolved.habAccount, `Crafting Hab ${resolved.habAccount.address} remains active in the validated Game, Profile, System, and Starbase sequence.`),
+            ]),
+        precondition(resolved.characterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game.`),
+        precondition(resolved.gameAccount, `Game ${game} retains its pinned owner and account layout.`),
+    ];
+    return createPlan({
+        kind: 'crafting.cancel-process',
+        preconditions: await Promise.all(preconditions),
+        steps: [
+            {
+                describes: description,
+                instruction: adaptCancelCraftingProcessInstruction({
+                    authorization: options.authorization,
+                    character: resolved.character,
+                    craftingProcess: process.address,
+                    game,
+                    recipe: process.recipe.address,
+                    starbasePlayer: process.starbasePlayer.address,
+                    system: process.system.address,
+                    ...(resolved.habAccount === undefined
+                        ? {}
+                        : { craftingHabInstance: resolved.habAccount.address }),
+                }),
+                signers: [options.authorization.authority],
+            },
+        ],
+        summary: description,
+    });
+}
+//# sourceMappingURL=index.js.map