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

package/dist/crafting/actions/index.js

@@ -1,15 +1,23 @@
-import { getAddressEncoder, getBytesEncoder, getProgramDerivedAddress, isAddress, } from '@solana/kit';
+import { deriveCurrencyCache, validateCurrencyCache, } from '../../internal/c4/currency-cache.js';
+import { validateStarbaseSystem } from '../../internal/planning/starbase-system.js';
+import { SYSTEM_PROGRAM } from '../../internal/system-program.js';
+import { isAddress } from '@solana/kit';
+import { resolveActionRuntime } from '../../internal/planning/action-runtime.js';
+import { requireProfileStarbasePlayer } from '../../internal/planning/starbase-player-owner.js';
 import { InvalidActionInputError, SageSdkError } from '../../client/errors.js';
 import { readContextRawAccounts } from '../../client/reconciliation.js';
-import { sage } from '../../internal/c4/bindings.js';
+import { SAGE_PROGRAM_ADDRESS } from '../../internal/c4/runtime-bindings.js';
 import { craftingHabAccountDefinition, craftingProcessAccountDefinition, deriveRecipeAddress, recipeAccountDefinition, } from '../../internal/c4/crafting.js';
-import { characterAccountDefinition, findCharacterPda, } from '../../internal/c4/identity.js';
+import { characterAccountDefinition, findCharacterPda, } from '../../internal/c4/character.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';
+import { adaptCancelCraftingProcessInstruction, adaptStartCraftingProcessInstruction, adaptCompleteCraftingProcessInstruction, readPlanAuthorization, } from '../../internal/planning/authorization-adapter.js';
+import { starSystemAccountDefinition } from '../../internal/c4/world.js';
+import { buildPlannerPlan } from '../../planning/plan-construction.js';
+import { hashRecipeConfiguration, validateRecipeUsage, } from '../../internal/planning/recipe-state.js';
+import { accountStatePrecondition } from '../../internal/planning/account-state.js';
+import { GAME_DISCRIMINATOR } from '../../internal/c4/discriminators.js';
 const U64_MAX = (1n << 64n) - 1n;
 const U32_MAX = 4_294_967_295;
 function invalid(field, value, acceptedRange, remedy) {
@@ -38,15 +46,7 @@ function readAddress(value, field) {
 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);
+    const authorization = readPlanAuthorization(options.authorization);
     if (typeof options.quantity !== 'bigint' ||
         options.quantity <= 0n ||
         options.quantity > U64_MAX) {
@@ -68,35 +68,11 @@ function validateStartOptions(value) {
             : { 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) {
+/** Validates completion or cancellation options, which share one shape. */
+function validateProcessOptions(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);
+    const authorization = readPlanAuthorization(options.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.');
     }
@@ -134,48 +110,19 @@ function validateKnownInputs(recipe, items, quantity, source, 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({
+async function recipePrecondition(account, describes, requiredUses = 0n) {
+    return {
+        kind: 'recipe-state',
         address: account.address,
-        dataHash: await hashAccountState(account),
+        configHash: await hashRecipeConfiguration(account),
+        requiredUses,
         describes,
-        kind: 'account-state',
-    });
+    };
 }
-async function resolveAccounts(ctx, recipe, player, options, game) {
-    const character = await findCharacterPda(options.authorization.profile, game);
+async function resolveAccounts(ctx, recipe, player, options, game, character) {
     const currencyCache = options.craftingHab === undefined
         ? undefined
-        : await deriveCurrencyCacheAddress(game);
+        : await deriveCurrencyCache(game).then(([address]) => address);
     const addresses = [
         character,
         player.address,
@@ -218,11 +165,11 @@ async function resolveAccounts(ctx, recipe, player, options, 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);
     }
+    validateRecipeUsage(recipeAccount, options.quantity);
     if (options.craftingHab === undefined) {
         return { character, characterAccount, playerAccount, recipeAccount };
     }
@@ -240,7 +187,7 @@ async function resolveAccounts(ctx, recipe, player, options, game) {
         !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);
+    await validateCurrencyCache(currencyCacheAccount, game, 'crafting');
     return {
         character,
         characterAccount,
@@ -258,6 +205,17 @@ async function resolveAccounts(ctx, recipe, player, options, game) {
  * returns one inert Plan whose two required signer roles are bound only during
  * execution.
  *
+ * A Recipe whose stored `usageLimitRaw` is `0n` is treated as unlimited: the
+ * local usage-limit precondition is skipped regardless of `usageCountRaw`.
+ * This is pinned SDK behavior, not a verified game rule. The pinned generated
+ * Recipe documents `usageLimit` only as "The maximum number of times that
+ * this recipe can be used", and every Recipe observed on z.ink PTR stores
+ * `9007199254740991` (2^53 - 1) as its limit, so no zero-limit Recipe has been
+ * simulated or executed. If the program enforces a limit the SDK did not,
+ * simulation or execution surfaces its `UsageLimitExceeded` error
+ * (`1367932950`) instead of a local precondition failure. See
+ * `docs/evidence/crafting-zero-usage-limit.md`.
+ *
  * @example
  * ```ts
  * declare const ctx: SageContext;
@@ -275,24 +233,10 @@ export async function planStartCraftingProcess(ctx, recipe, player, input) {
     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);
-    }
+    const character = await requireProfileStarbasePlayer(player, options.authorization.profile, game);
     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);
     }
@@ -323,26 +267,41 @@ export async function planStartCraftingProcess(ctx, recipe, player, input) {
     else {
         validateKnownInputs(recipe, player.cargo.items, options.quantity, 'Starbase Player', player.address);
     }
-    const resolved = await resolveAccounts(ctx, recipe, player, options, game);
+    const resolved = await resolveAccounts(ctx, recipe, player, options, game, character);
+    const [runtimeSystem] = await readContextRawAccounts(ctx, [
+        player.system.address,
+    ]);
+    if (!runtimeSystem)
+        fail('The crafting System is missing. Refresh the Starbase and recreate this Plan.', player.system.address);
+    const runtime = await resolveActionRuntime(ctx, {
+        mode: 'crafting-start',
+        game,
+        system: player.system.address,
+        starbaseSeqId: starSystemAccountDefinition.decode(runtimeSystem).sequenceId,
+        ...(options.craftingHab === undefined
+            ? {}
+            : { structure: options.craftingHab.address }),
+    });
     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.`),
+        accountStatePrecondition(resolved.characterAccount, `The canonical Character remains assigned to Profile ${options.authorization.profile} in the configured Game.`),
+        accountStatePrecondition(resolved.playerAccount, `Starbase Player ${player.address} retains its Character, Profile, System, crew, and input inventory.`),
+        recipePrecondition(resolved.recipeAccount, `Recipe ${recipe.name} retains its configuration and enough remaining uses for this job.`, options.quantity),
         ...(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.'),
+                accountStatePrecondition(resolved.habAccount, `Crafting Hab ${resolved.habAccount.address} remains active with an available job slot, the Recipe unlocked, and sufficient inputs.`),
             ]),
     ];
-    return createPlan({
+    return buildPlannerPlan({
         kind: 'crafting.start-process',
-        preconditions: await Promise.all(preconditions),
+        preconditions: [...runtime.guards, ...(await Promise.all(preconditions))],
         steps: [
             {
-                describes: description,
+                describes: `${description} ${runtime.description}`,
                 instruction: adaptStartCraftingProcessInstruction({
+                    ...runtime.accounts,
+                    starbaseGovernance: runtime.accounts.starbaseGovernance,
                     authorization: options.authorization,
                     character: resolved.character,
                     craftingProcess: options.craftingProcess,
@@ -362,7 +321,7 @@ export async function planStartCraftingProcess(ctx, recipe, player, input) {
                 signers: [options.authorization.authority, options.craftingProcess],
             },
         ],
-        summary: description,
+        summary: `${description} ${runtime.description}`,
     });
 }
 function sameProcessSnapshot(process, account) {
@@ -372,7 +331,7 @@ function sameProcessSnapshot(process, account) {
         account.system === process.system.address &&
         account.starbasePlayer === process.starbasePlayer.address &&
         account.starbaseSequenceId === process.starbaseSequenceId &&
-        account.craftingHab === process.craftingHab.address &&
+        account.craftingHab === process.craftingHab?.address &&
         account.quantityRaw === process.quantityRaw &&
         account.numCrew === process.numCrew &&
         account.startsAtUnixSeconds === process.startsAtUnixSeconds &&
@@ -382,47 +341,57 @@ function sameProcessSnapshot(process, account) {
         account.inputs.storageCostRaw === process.inputs.usedStorageUnitsRaw &&
         sameBalances(process.inputs.items, account.inputs.amounts));
 }
+/** SDK reads omit `craftingHab` for a Process without a Hab; a caller-built
+ * snapshot carrying the raw stored System address is rejected with that cause
+ * instead of being read as a Hab and reported as a changed Process. */
+function processHabAddress(process) {
+    const habAddress = process.craftingHab?.address;
+    if (habAddress === SYSTEM_PROGRAM)
+        invalid('process.craftingHab', habAddress, 'a Crafting Hab address, or no craftingHab for a Process started without a Hab', 'The stored System address means this Process has no Hab. Use a snapshot from getCraftingProcess, which omits craftingHab, or omit craftingHab, then plan again.');
+    return habAddress;
+}
 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)) {
+        account.owner !== SAGE_PROGRAM_ADDRESS ||
+        account.data.length < GAME_DISCRIMINATOR.length ||
+        !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 = [
+/** Reads and validates the Crafting Process graph shared by completion and
+ * cancellation, with `extra` in the same read: the unchanged Process, its
+ * canonical System and Starbase, the unchanged Recipe and its Hab policy, the
+ * Profile's canonical Starbase Player and Character, and the Process Hab,
+ * active and owned, when present. `action` completes the remedies, and
+ * `staleStarbaseGuidance` adds advice for a replaced Starbase. */
+async function resolveProcessAccounts(ctx, process, profile, game, action, extra, staleStarbaseGuidance) {
+    const character = await findCharacterPda(profile, game);
+    const habAddress = processHabAddress(process);
+    const [processCandidate, recipeCandidate, playerCandidate, systemCandidate, characterCandidate, extraAccount, habCandidate,] = await readContextRawAccounts(ctx, [
         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);
+        extra,
+        ...(habAddress === undefined ? [] : [habAddress]),
+    ]);
+    const processAccount = requireAccount(processCandidate, 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.`);
     if (processAccount.address !== process.address ||
-        !sameProcessSnapshot(process, processData)) {
+        !sameProcessSnapshot(process, craftingProcessAccountDefinition.decode(processAccount))) {
         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);
     }
+    await validateStarbaseSystem(requireAccount(systemCandidate, process.system.address, `Star System ${process.system.address} is missing. Refresh the Crafting Process and Star System before retrying ${action}.`), {
+        address: process.system.address,
+        game,
+        starbaseSequenceId: process.starbaseSequenceId,
+    }, staleStarbaseGuidance);
+    const recipeAccount = requireAccount(recipeCandidate, process.recipe.address, `Recipe ${process.recipe.address} is missing. Refresh the Crafting Process and its Recipe before retrying ${action}.`);
+    const playerAccount = requireAccount(playerCandidate, process.starbasePlayer.address, `Starbase Player ${process.starbasePlayer.address} is missing. Refresh the Crafting Process and Starbase Player before retrying ${action}.`);
+    const characterAccount = requireAccount(characterCandidate, character, `Canonical Character ${character} is missing for Profile ${profile}. Create or repair the Character in the configured Game before retrying ${action}.`);
+    const habAccount = habAddress === undefined
+        ? undefined
+        : requireAccount(habCandidate, habAddress, `Crafting Hab ${habAddress} is missing. Refresh the Crafting Process and Hab before retrying ${action}.`);
     const recipeData = recipeAccountDefinition.decode(recipeAccount);
     const canonicalRecipe = await deriveRecipeAddress(game, recipeData.id);
     if (recipeAccount.address !== process.recipe.address ||
@@ -432,65 +401,72 @@ async function resolveCompleteAccounts(ctx, process, options, game) {
         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);
+        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 ${action}.`, 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);
+        fail(`Recipe ${recipeData.name} requires a Crafting Hab, but Crafting Process ${process.address} omits one. Refresh or repair the Process relationship before retrying ${action}.`, 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.playerProfile !== 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);
+        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 ${action}.`, process.starbasePlayer.address);
     }
     if (habAccount !== undefined) {
         const habData = craftingHabAccountDefinition.decode(habAccount);
         if (habAccount.address !== habAddress ||
             habData.game !== game ||
-            habData.ownerProfile !== options.authorization.profile ||
+            habData.ownerProfile !== 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);
+            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 ${action}.`, habAccount.address);
         }
     }
     const characterData = characterAccountDefinition.decode(characterAccount);
     if (characterAccount.address !== character ||
-        characterData.playerProfile !== options.authorization.profile ||
+        characterData.playerProfile !== 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);
+        fail(`The canonical Character does not match Profile ${profile} and the configured Game ${game}. Refresh or repair the Character relationship before retrying ${action}.`, characterAccount.address);
     }
-    validateGameRead(gameAccount, game);
-    validateCurrencyCache(currencyCacheAccount, game, currencyCache);
     return {
         character,
         characterAccount,
-        currencyCache,
-        currencyCacheAccount,
-        gameAccount,
-        ...(habAccount === undefined ? {} : { habAccount }),
+        extraAccount,
+        habAccount,
         playerAccount,
         processAccount,
         recipeAccount,
-        systemAccount,
     };
 }
+/** The validated Process graph preconditions, with `systemGuard` after the
+ * Starbase Player when the action guards the Starbase separately. */
+function processPreconditions(process, resolved, profile, systemGuard = []) {
+    return [
+        accountStatePrecondition(resolved.processAccount, `Crafting Process ${process.address} retains its validated relationships, timing, crew, quantity, fee, and inputs.`),
+        recipePrecondition(resolved.recipeAccount, `Recipe ${process.recipe.name} retains its validated Game, Hab policy, ingredients, and outputs.`),
+        accountStatePrecondition(resolved.playerAccount, `Starbase Player ${process.starbasePlayer.address} retains its Profile, Character, and System relationships.`),
+        ...systemGuard.map((guard) => Promise.resolve(guard)),
+        ...(resolved.habAccount === undefined
+            ? []
+            : [
+                accountStatePrecondition(resolved.habAccount, `Crafting Hab ${resolved.habAccount.address} remains active in the validated Game, Profile, System, and Starbase sequence.`),
+            ]),
+        accountStatePrecondition(resolved.characterAccount, `The canonical Character remains assigned to Profile ${profile} in the configured Game.`),
+    ];
+}
+/** Requires the authorization Profile to own the Process. */
+function requireProcessOwner(process, profile) {
+    if (process.profile.address !== profile) {
+        fail(`Crafting Process ${process.address} does not belong to authorization Profile ${profile}. Use the owning Profile, refresh the Process, and retry.`, process.address);
+    }
+}
 /** Plans completion of one Crafting Process without signing, simulation, or writes.
  *
  * The planner resolves and validates the Process account graph, requires Profile
@@ -508,11 +484,10 @@ async function resolveCompleteAccounts(ctx, process, options, game) {
  * ```
  */
 export async function planCompleteCraftingProcess(ctx, process, input) {
-    const options = validateCompleteOptions(input);
+    const options = validateProcessOptions(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 { profile } = options.authorization;
+    requireProcessOwner(process, profile);
     const state = deriveInternalCraftingProcessState(process, options.atUnixSeconds);
     if (state.kind !== 'complete') {
         const timing = state.kind === 'scheduled'
@@ -520,33 +495,36 @@ export async function planCompleteCraftingProcess(ctx, process, input) {
             : `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.`),
+    const [currencyCache] = await deriveCurrencyCache(game);
+    const resolved = await resolveProcessAccounts(ctx, process, profile, game, 'completion', currencyCache);
+    await validateCurrencyCache(requireAccount(resolved.extraAccount, currencyCache, `Canonical CurrencyCache ${currencyCache} is missing for the configured Game. Refresh the Game currency configuration before retrying completion.`), game, 'crafting');
+    const runtime = await resolveActionRuntime(ctx, {
+        mode: 'crafting-complete',
+        game,
+        system: process.system.address,
+        starbaseSeqId: process.starbaseSequenceId,
+        character: resolved.character,
+        process: process.address,
         ...(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({
+            ? {}
+            : { structure: resolved.habAccount.address }),
+    });
+    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.`;
+    return buildPlannerPlan({
         kind: 'crafting.complete-process',
-        preconditions: await Promise.all(preconditions),
+        preconditions: [
+            ...runtime.guards,
+            ...(await Promise.all(processPreconditions(process, resolved, profile))),
+        ],
         steps: [
             {
-                describes: description,
+                describes: `${description} ${runtime.description}`,
                 instruction: adaptCompleteCraftingProcessInstruction({
+                    ...runtime.accounts,
                     authorization: options.authorization,
                     character: resolved.character,
                     craftingProcess: process.address,
-                    currencyCache: resolved.currencyCache,
+                    currencyCache,
                     game,
                     recipe: process.recipe.address,
                     starbasePlayer: process.starbasePlayer.address,
@@ -558,108 +536,9 @@ export async function planCompleteCraftingProcess(ctx, process, input) {
                 signers: [options.authorization.authority],
             },
         ],
-        summary: description,
+        summary: `${description} ${runtime.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
@@ -677,33 +556,32 @@ async function resolveCancelAccounts(ctx, process, options, game) {
  * ```
  */
 export async function planCancelCraftingProcess(ctx, process, input) {
-    const options = validateCancelOptions(input);
+    const options = validateProcessOptions(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 { profile } = options.authorization;
+    requireProcessOwner(process, profile);
     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 resolved = await resolveProcessAccounts(ctx, process, profile, game, 'cancellation', game, 'For a Crafting Process belonging to the destroyed Starbase, use destroyCraftingProcess; do not cancel the Process.');
+    const gameAccount = requireAccount(resolved.extraAccount, game, `Configured Game ${game} is missing. Refresh the configured Game before retrying cancellation.`);
+    validateGameRead(gameAccount, 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({
+    return buildPlannerPlan({
         kind: 'crafting.cancel-process',
-        preconditions: await Promise.all(preconditions),
+        preconditions: await Promise.all([
+            ...processPreconditions(process, resolved, profile, [
+                {
+                    kind: 'starbase-system',
+                    address: process.system.address,
+                    game,
+                    starbaseSequenceId: process.starbaseSequenceId,
+                    describes: `Star System ${process.system.address} retains its canonical Game identity, active Starbase and sequence ${process.starbaseSequenceId}; unrelated shared activity may change.`,
+                },
+            ]),
+            accountStatePrecondition(gameAccount, `Game ${game} retains its pinned owner and account layout.`),
+        ]),
         steps: [
             {
                 describes: description,