@gearbox-protocol/sdk 16.0.0-next.5 → 16.0.0-next.50

package/dist/cjs/sdk/prepare/PrepareApi.js

@@ -1,22 +1,35 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_onchain_utils_hex = require("../../onchain/utils/hex.js");
 const require_onchain_base_MultichainConstruct = require("../../onchain/base/MultichainConstruct.js");
+const require_model_result = require("../../model/result.js");
+require("../../model/index.js");
+const require_onchain_validation_token = require("../../onchain/validation/token.js");
 const require_onchain_accounts_intents_utils_credit_account_slice = require("../../onchain/accounts/intents/utils/credit-account-slice.js");
 const require_onchain_accounts_intents_index = require("../../onchain/accounts/intents/index.js");
 require("../../onchain/index.js");
+const require_sdk_prepare_errors = require("./errors.js");
+const require_sdk_prepare_withdrawable_collaterals = require("./withdrawable-collaterals.js");
 //#region src/sdk/prepare/PrepareApi.ts
 /**
-* {@inheritDoc OpportunitiesPrepare}
+* {@inheritDoc IOpportunitiesPrepare}
 *
 * Holds no state of its own: it owns the mapping from the public,
 * read-model-shaped request to the engine's intent, and nothing else. All
 * protocol knowledge stays in `CreditAccountOperationsService` and
 * `PoolService`.
 *
-* A simulation names one chain, so it reads through
-* {@link MultichainConstruct.queryChain}: there is no second source to fall back
-* to, hence a chain the SDK does not cover, or one that fails the read, throws
-* rather than answering with empty metadata.
+* A prepared operation names one chain and reads it directly: there is no
+* second source to fall back to, so a chain the SDK does not cover, or one
+* that fails the read, is a failure of the whole request rather than a thinner
+* answer.
+*
+* No refusable async method here throws. Every way such a preparation can
+* fail — the market's own refusals, the ones the namespace decides itself, and
+* anything the chain or the engine raises — comes back in the failure half of
+* its `SDKReturn`, under the codes that method's signature names. A caller
+* writes one branch, not a branch and a `try`. The synchronous LP methods and
+* the bare `max*` reads throw on bugs and lifecycle errors instead, see
+* {@link IOpportunitiesPrepare}.
 **/
 var PrepareApi = class extends require_onchain_base_MultichainConstruct.MultichainConstruct {
 	#ensureFresh;
@@ -24,155 +37,169 @@ var PrepareApi = class extends require_onchain_base_MultichainConstruct.Multicha
 		super(sdk);
 		this.#ensureFresh = ensureFresh;
 	}
-	async queryChain(props) {
-		await this.#ensureFresh?.([this.sdk.chain(props.network).chainId]);
-		return super.queryChain(props);
+	/**
+	* The chain an async method reads, revalidated first so the state it is
+	* about to weigh is no older than the SDK's freshness bar.
+	**/
+	async #chain(chainId) {
+		await this.#ensureFresh?.([this.sdk.chain(chainId).chainId]);
+		return this.sdk.chain(chainId);
 	}
 	/**
-	* {@inheritDoc OpportunitiesPrepare.finalize}
+	* {@inheritDoc IOpportunitiesPrepare.finalize}
 	**/
 	async finalize(position, params) {
-		return this.queryChain({
-			network: position.chainId,
-			run: async (sdk) => {
-				const intent = resumable(params.intent ?? params.claimable.intent);
-				if (!intent) return {
-					ok: false,
-					reason: "noRecordedIntent"
-				};
-				return service(sdk).finishIntent({
-					intent,
-					claimable: params.claimable,
-					creditAccount: await slice(sdk, position.creditAccount),
-					sdk,
-					slippage: params.slippage,
-					quotaReserve: params.quotaReserve
-				});
-			}
-		});
+		try {
+			const sdk = await this.#chain(position.chainId);
+			const at = stateBlock(sdk);
+			const intent = resumable(params.intent ?? params.claimable.intent);
+			if (!intent) return require_model_result.sdkErr(require_sdk_prepare_errors.toRefusalError({
+				reason: "noRecordedIntent",
+				detail: void 0
+			}));
+			const creditAccount = await slice(sdk, position.creditAccount);
+			if (!creditAccount) return require_model_result.sdkErr(require_sdk_prepare_errors.creditAccountNotFound(position.creditAccount));
+			return finalized(await service(sdk).finishIntent({
+				intent,
+				claimable: toClaimableWithdrawal(params.claimable),
+				creditAccount,
+				sdk,
+				slippage: params.slippage,
+				quotaReserve: params.quotaReserve
+			}), at);
+		} catch (e) {
+			return require_model_result.sdkErr(require_sdk_prepare_errors.unexpectedFailure(e));
+		}
 	}
 	/**
-	* {@inheritDoc OpportunitiesPrepare.deposit}
+	* {@inheritDoc IOpportunitiesPrepare.deposit}
 	**/
-	deposit(pool, params) {
-		const { marketRegister, pools } = this.sdk.chain(pool.chainId);
-		const tokenIn = params.tokenIn ?? marketRegister.findByPool(pool.pool).pool.underlying;
-		const tokenOut = lpRoute(params.tokenOut, () => pools.getDepositTokensOut(pool.pool, tokenIn));
-		if (!tokenOut) return {
-			ok: false,
-			reason: "unsupportedTokenPair"
-		};
-		const preview = pools.simulateDeposit({
-			pool: pool.pool,
-			amount: params.amount,
-			tokenIn,
-			tokenOut
-		});
-		const call = pools.addLiquidity({
-			collateral: preview.tokenIn,
-			pool: pool.pool,
-			wallet: params.wallet,
-			meta: pools.getDepositMetadata(pool.pool, tokenIn, tokenOut)
-		});
-		if (!call) return {
-			ok: false,
-			reason: "unsupportedTokenPair"
-		};
-		return {
-			ok: true,
-			operations: [],
-			preview,
-			calls: call.calls
-		};
+	async deposit(pool, params) {
+		try {
+			const chain = await this.#chain(pool.chainId);
+			const { marketRegister, pools } = chain;
+			const tokenIn = params.tokenIn ?? marketRegister.findByPool(pool.pool).pool.underlying;
+			const tokenOut = lpRoute(params.tokenOut, () => pools.getDepositTokensOut(pool.pool, tokenIn));
+			if (!tokenOut) return unroutable(chain, tokenIn, void 0);
+			const state = pools.simulateDeposit({
+				pool: pool.pool,
+				amount: params.amount,
+				tokenIn,
+				tokenOut
+			});
+			const call = pools.addLiquidity({
+				collateral: {
+					token: state.tokenIn.token.address,
+					balance: state.tokenIn.value
+				},
+				pool: pool.pool,
+				wallet: params.wallet,
+				meta: pools.getDepositMetadata(pool.pool, tokenIn, tokenOut)
+			});
+			if (!call) return unroutable(chain, tokenIn, tokenOut);
+			return require_model_result.sdkOk({
+				operations: [],
+				state: await lpState(chain, pool.pool, params.wallet, state, { mints: state.tokenOut.value }),
+				calls: call.calls,
+				...stateBlock(chain)
+			});
+		} catch (e) {
+			return require_model_result.sdkErr(require_sdk_prepare_errors.unexpectedFailure(e));
+		}
 	}
 	/**
-	* {@inheritDoc OpportunitiesPrepare.withdraw}
+	* {@inheritDoc IOpportunitiesPrepare.withdraw}
 	**/
-	withdraw(pool, params) {
-		const { pools } = this.sdk.chain(pool.chainId);
-		const tokenIn = params.tokenIn ?? pool.pool;
-		const tokenOut = lpRoute(params.tokenOut, () => pools.getWithdrawalTokensOut(pool.pool, tokenIn));
-		if (!tokenOut) return {
-			ok: false,
-			reason: "unsupportedTokenPair"
-		};
-		const preview = pools.simulateWithdraw({
-			pool: pool.pool,
-			amount: params.amount,
-			tokenIn,
-			tokenOut
-		});
-		const { calls } = pools.removeLiquidity({
-			pool: pool.pool,
-			amount: params.amount,
-			wallet: params.wallet,
-			permit: void 0,
-			meta: pools.getWithdrawalMetadata(pool.pool, tokenIn, tokenOut),
-			mode: "withdraw"
-		});
-		return {
-			ok: true,
-			operations: [],
-			preview,
-			calls
-		};
+	async withdraw(pool, params) {
+		try {
+			const chain = await this.#chain(pool.chainId);
+			const { pools } = chain;
+			const tokenIn = params.tokenIn ?? pool.pool;
+			const tokenOut = lpRoute(params.tokenOut, () => pools.getWithdrawalTokensOut(pool.pool, tokenIn));
+			if (!tokenOut) return unroutable(chain, tokenIn, void 0);
+			const state = pools.simulateWithdraw({
+				pool: pool.pool,
+				amount: params.amount,
+				tokenIn,
+				tokenOut
+			});
+			const { calls } = pools.removeLiquidity({
+				pool: pool.pool,
+				amount: params.amount,
+				wallet: params.wallet,
+				permit: void 0,
+				meta: pools.getWithdrawalMetadata(pool.pool, tokenIn, tokenOut),
+				mode: "withdraw"
+			});
+			return require_model_result.sdkOk({
+				operations: [],
+				state: await lpState(chain, pool.pool, params.wallet, state, { burns: state.tokenIn.value }),
+				calls,
+				...stateBlock(chain)
+			});
+		} catch (e) {
+			return require_model_result.sdkErr(require_sdk_prepare_errors.unexpectedFailure(e));
+		}
 	}
 	/**
-	* {@inheritDoc OpportunitiesPrepare.redeem}
+	* {@inheritDoc IOpportunitiesPrepare.redeem}
 	**/
-	redeem(pool, params) {
-		const { pools } = this.sdk.chain(pool.chainId);
-		const tokenIn = params.tokenIn ?? pool.pool;
-		const tokenOut = lpRoute(params.tokenOut, () => pools.getWithdrawalTokensOut(pool.pool, tokenIn));
-		if (!tokenOut) return {
-			ok: false,
-			reason: "unsupportedTokenPair"
-		};
-		const preview = pools.simulateRedeem({
-			pool: pool.pool,
-			amount: params.amount,
-			tokenIn,
-			tokenOut
-		});
-		const { calls } = pools.removeLiquidity({
-			pool: pool.pool,
-			amount: params.amount,
-			wallet: params.wallet,
-			permit: void 0,
-			meta: pools.getWithdrawalMetadata(pool.pool, tokenIn, tokenOut),
-			mode: "redeem"
-		});
-		return {
-			ok: true,
-			operations: [],
-			preview,
-			calls
-		};
+	async redeem(pool, params) {
+		try {
+			const chain = await this.#chain(pool.chainId);
+			const { pools } = chain;
+			const tokenIn = params.tokenIn ?? pool.pool;
+			const tokenOut = lpRoute(params.tokenOut, () => pools.getWithdrawalTokensOut(pool.pool, tokenIn));
+			if (!tokenOut) return unroutable(chain, tokenIn, void 0);
+			const state = pools.simulateRedeem({
+				pool: pool.pool,
+				amount: params.amount,
+				tokenIn,
+				tokenOut
+			});
+			const { calls } = pools.removeLiquidity({
+				pool: pool.pool,
+				amount: params.amount,
+				wallet: params.wallet,
+				permit: void 0,
+				meta: pools.getWithdrawalMetadata(pool.pool, tokenIn, tokenOut),
+				mode: "redeem"
+			});
+			return require_model_result.sdkOk({
+				operations: [],
+				state: await lpState(chain, pool.pool, params.wallet, state, { burns: state.tokenIn.value }),
+				calls,
+				...stateBlock(chain)
+			});
+		} catch (e) {
+			return require_model_result.sdkErr(require_sdk_prepare_errors.unexpectedFailure(e));
+		}
 	}
 	/**
-	* {@inheritDoc OpportunitiesPrepare.openNewStrategy}
+	* {@inheritDoc IOpportunitiesPrepare.openNewStrategy}
 	**/
 	async openNewStrategy(strategy, params) {
-		return this.queryChain({
-			network: strategy.chainId,
-			run: (sdk) => {
-				const targetToken = params.targetToken ?? sdk.marketRegister.findCreditManager(strategy.creditManager).strategyTargetCollateral;
-				if (!targetToken) throw new Error(`credit manager ${strategy.creditManager} has no strategy target collateral`);
-				return service(sdk).openStrategyIntent({
-					sdk,
-					creditManager: strategy.creditManager,
-					collateral: params.collateral,
-					targetToken,
-					leverage: params.leverage,
-					leftoverBalances: params.leftoverBalances,
-					slippage: params.slippage,
-					quotaReserve: params.quotaReserve
-				});
-			}
-		});
+		try {
+			const sdk = await this.#chain(strategy.chainId);
+			const at = stateBlock(sdk);
+			const targetToken = params.targetToken ?? sdk.marketRegister.findCreditManager(strategy.creditManager).strategyTargetCollateral;
+			if (!targetToken) return require_model_result.sdkErr(require_sdk_prepare_errors.noStrategyTargetCollateral(strategy.creditManager));
+			return opened(await service(sdk).openStrategyIntent({
+				sdk,
+				creditManager: strategy.creditManager,
+				collateral: params.collateral,
+				targetToken,
+				leverage: params.leverage,
+				leftoverBalances: params.leftoverBalances,
+				slippage: params.slippage,
+				quotaReserve: params.quotaReserve
+			}), at);
+		} catch (e) {
+			return require_model_result.sdkErr(require_sdk_prepare_errors.unexpectedFailure(e));
+		}
 	}
 	/**
-	* {@inheritDoc OpportunitiesPrepare.depositStrategy}
+	* {@inheritDoc IOpportunitiesPrepare.depositStrategy}
 	**/
 	async depositStrategy(position, params) {
 		return this.#startIntent(position, params, {
@@ -185,7 +212,7 @@ var PrepareApi = class extends require_onchain_base_MultichainConstruct.Multicha
 		});
 	}
 	/**
-	* {@inheritDoc OpportunitiesPrepare.withdrawStrategy}
+	* {@inheritDoc IOpportunitiesPrepare.withdrawStrategy}
 	**/
 	async withdrawStrategy(position, params) {
 		return this.#startRoutes(position, params, {
@@ -197,19 +224,18 @@ var PrepareApi = class extends require_onchain_base_MultichainConstruct.Multicha
 		});
 	}
 	/**
-	* {@inheritDoc OpportunitiesPrepare.maxWithdraw}
+	* {@inheritDoc IOpportunitiesPrepare.maxWithdraw}
 	**/
 	async maxWithdraw(position) {
-		return this.queryChain({
-			network: position.chainId,
-			run: async (sdk) => service(sdk).maxWithdraw({
-				creditAccount: await slice(sdk, position.creditAccount),
-				sdk
-			})
+		const sdk = await this.#chain(position.chainId);
+		const creditAccount = await this.#account(sdk, position);
+		return service(sdk).maxWithdraw({
+			creditAccount,
+			sdk
 		});
 	}
 	/**
-	* {@inheritDoc OpportunitiesPrepare.repayStrategy}
+	* {@inheritDoc IOpportunitiesPrepare.repayStrategy}
 	**/
 	async repayStrategy(position, params) {
 		return this.#startIntent(position, params, {
@@ -220,19 +246,18 @@ var PrepareApi = class extends require_onchain_base_MultichainConstruct.Multicha
 		});
 	}
 	/**
-	* {@inheritDoc OpportunitiesPrepare.maxRepay}
+	* {@inheritDoc IOpportunitiesPrepare.maxRepay}
 	**/
 	async maxRepay(position) {
-		return this.queryChain({
-			network: position.chainId,
-			run: async (sdk) => service(sdk).maxRepay({
-				creditAccount: await slice(sdk, position.creditAccount),
-				sdk
-			})
+		const sdk = await this.#chain(position.chainId);
+		const creditAccount = await this.#account(sdk, position);
+		return service(sdk).maxRepay({
+			creditAccount,
+			sdk
 		});
 	}
 	/**
-	* {@inheritDoc OpportunitiesPrepare.adjustLeverage}
+	* {@inheritDoc IOpportunitiesPrepare.adjustLeverage}
 	**/
 	async adjustLeverage(position, params) {
 		return this.#startRoutes(position, params, {
@@ -242,7 +267,7 @@ var PrepareApi = class extends require_onchain_base_MultichainConstruct.Multicha
 		});
 	}
 	/**
-	* {@inheritDoc OpportunitiesPrepare.addCollateral}
+	* {@inheritDoc IOpportunitiesPrepare.addCollateral}
 	**/
 	async addCollateral(position, params) {
 		return this.#startIntent(position, params, {
@@ -253,7 +278,7 @@ var PrepareApi = class extends require_onchain_base_MultichainConstruct.Multicha
 		});
 	}
 	/**
-	* {@inheritDoc OpportunitiesPrepare.withdrawCollateral}
+	* {@inheritDoc IOpportunitiesPrepare.withdrawCollateral}
 	**/
 	async withdrawCollateral(position, params) {
 		return this.#startIntent(position, params, {
@@ -264,59 +289,120 @@ var PrepareApi = class extends require_onchain_base_MultichainConstruct.Multicha
 		});
 	}
 	/**
-	* {@inheritDoc OpportunitiesPrepare.maxWithdrawCollateral}
+	* {@inheritDoc IOpportunitiesPrepare.leverageBand}
 	**/
-	async maxWithdrawCollateral(position, token) {
-		return this.queryChain({
-			network: position.chainId,
-			run: async (sdk) => service(sdk).maxWithdrawCollateral({
-				creditAccount: await slice(sdk, position.creditAccount),
-				sdk,
-				token
-			})
+	leverageBand(strategy, collateral, targetHF) {
+		const sdk = this.sdk.chain(strategy.chainId);
+		return service(sdk).leverageBand({
+			sdk,
+			creditManager: strategy.creditManager,
+			collateral,
+			targetHF
+		});
+	}
+	/**
+	* {@inheritDoc IOpportunitiesPrepare.withdrawableCollaterals}
+	**/
+	withdrawableCollaterals(position) {
+		return require_sdk_prepare_withdrawable_collaterals.withdrawableCollaterals(this.sdk.chain(position.chainId), position);
+	}
+	/**
+	* {@inheritDoc IOpportunitiesPrepare.maxWithdrawCollateral}
+	**/
+	async maxWithdrawCollateral(position, token, targetHF) {
+		const sdk = await this.#chain(position.chainId);
+		const creditAccount = await this.#account(sdk, position);
+		return service(sdk).maxWithdrawCollateral({
+			creditAccount,
+			sdk,
+			token,
+			targetHF
 		});
 	}
 	/**
-	* Shared path of the two flows that sell a position asset, and therefore have
-	* two routes to offer: one account read, one intent, both routes quoted.
+	* The account a bare `max*` read weighs. These reads answer a number, not
+	* an envelope, so an account the markets do not hold is thrown rather than
+	* described, see {@link IOpportunitiesPrepare.maxWithdraw}.
+	**/
+	async #account(sdk, position) {
+		const creditAccount = await slice(sdk, position.creditAccount);
+		if (!creditAccount) throw new Error(require_sdk_prepare_errors.creditAccountNotFound(position.creditAccount).message);
+		return creditAccount;
+	}
+	/**
+	* Shared path of the two flows that sell a position asset, and therefore
+	* have two routes to offer: one account read, one intent, both routes
+	* quoted. Every refusal, the crash wrap included, carries `refused` so a
+	* form can say which routes were ruled out and why.
+	*
+	* @typeParam X - The codes the calling flow can raise beyond the shared
+	* ones, per the engine trace its signature spells out.
 	**/
 	async #startRoutes(position, options, intent) {
-		return this.queryChain({
-			network: position.chainId,
-			run: async (sdk) => service(sdk).intentRoutes({
+		try {
+			const sdk = await this.#chain(position.chainId);
+			const at = stateBlock(sdk);
+			const creditAccount = await slice(sdk, position.creditAccount);
+			if (!creditAccount) return neitherRoute(require_sdk_prepare_errors.creditAccountNotFound(position.creditAccount));
+			return routed(await service(sdk).intentRoutes({
 				intent,
-				creditAccount: await slice(sdk, position.creditAccount),
+				creditAccount,
 				sdk,
 				slippage: options.slippage,
 				quotaReserve: options.quotaReserve
-			})
-		});
+			}), at);
+		} catch (e) {
+			return neitherRoute(require_sdk_prepare_errors.unexpectedFailure(e));
+		}
 	}
 	/**
 	* Shared path of the five flows that act on an existing account: read the
-	* account, then run the intent through the engine.
+	* account, then run the intent through the engine. Whatever the chain or
+	* the engine throws on the way is described as `unexpectedFailure` instead
+	* of escaping, so the flow always answers.
+	*
+	* @typeParam X - The codes the calling flow can raise beyond the shared
+	* ones, per the engine trace its signature spells out.
 	**/
 	async #startIntent(position, options, intent) {
-		return this.queryChain({
-			network: position.chainId,
-			run: async (sdk) => {
-				const creditAccount = await slice(sdk, position.creditAccount);
-				return service(sdk).startIntent({
-					intent,
-					creditAccount,
-					sdk,
-					slippage: options.slippage,
-					quotaReserve: options.quotaReserve
-				});
-			}
-		});
+		try {
+			const sdk = await this.#chain(position.chainId);
+			const at = stateBlock(sdk);
+			const creditAccount = await slice(sdk, position.creditAccount);
+			if (!creditAccount) return require_model_result.sdkErr(require_sdk_prepare_errors.creditAccountNotFound(position.creditAccount));
+			return planned(await service(sdk).startIntent({
+				intent,
+				creditAccount,
+				sdk,
+				slippage: options.slippage,
+				quotaReserve: options.quotaReserve
+			}), at);
+		} catch (e) {
+			return require_model_result.sdkErr(require_sdk_prepare_errors.unexpectedFailure(e));
+		}
 	}
 };
 function service(sdk) {
 	return new require_onchain_accounts_intents_index.CreditAccountOperationsService(sdk);
 }
-function slice(sdk, creditAccount) {
-	return require_onchain_accounts_intents_utils_credit_account_slice.fetchCreditAccountSlice(sdk, creditAccount);
+/**
+* Reads the block the SDK's loaded state stands at — the same state every
+* preparation below is computed from, so it is the block the result reports.
+**/
+function stateBlock(sdk) {
+	return {
+		blockNumber: Number(sdk.currentBlock),
+		timestamp: Number(sdk.timestamp)
+	};
+}
+/**
+* The account the request names, or nothing where the markets this SDK is
+* connected to hold no such account — closed since it was listed, or named on
+* the wrong chain. Read rather than thrown, so the caller gets a code for it.
+**/
+async function slice(sdk, creditAccount) {
+	const data = await sdk.accounts.getCreditAccountData(creditAccount);
+	return data && require_onchain_accounts_intents_utils_credit_account_slice.toCreditAccountSlice(data);
 }
 /**
 * The operation a claim resumes, or `undefined` when there is none to resume:
@@ -328,9 +414,173 @@ function resumable(intent) {
 	return intent ?? void 0;
 }
 /**
+* Unwraps a read-model claimable withdrawal into the compressor shape the
+* intents engine plans from.
+**/
+function toClaimableWithdrawal(claimable) {
+	return {
+		token: claimable.sourceToken.address,
+		withdrawalPhantomToken: claimable.withdrawalPhantomToken.token.address,
+		withdrawalTokenSpent: claimable.withdrawalPhantomToken.value,
+		outputs: claimable.outputs.map((o) => ({
+			token: o.token.address,
+			amount: o.value,
+			isDelayed: o.isDelayed
+		})),
+		claimCalls: [{
+			target: claimable.claimCall.to,
+			callData: claimable.claimCall.callData
+		}],
+		redeemer: claimable.redeemer
+	};
+}
+/**
+* The engine's refusal as one flow's failure half.
+*
+* The engine answers with the open union of every reason it can raise
+* anywhere; which of them a given flow actually reaches is the engine trace
+* written into the public signatures. This cast is the one place the open
+* union is narrowed onto them — a code added to or removed from a flow has to
+* move its signature, which `types.test-d.ts` pins.
+**/
+function refusal(issue) {
+	return require_model_result.sdkErr(require_sdk_prepare_errors.toRefusalError(issue));
+}
+/**
+* A flow with two routes, refused before either could be quoted: the error is
+* the same one any other flow would report, with nothing to say about the
+* routes because neither was reached.
+**/
+function neitherRoute(error) {
+	return require_model_result.sdkErr({
+		...error,
+		refused: {
+			instant: void 0,
+			delayed: void 0
+		}
+	});
+}
+/**
+* The engine's answer, as the envelope the namespace speaks in: what the
+* operation comes to under `data`, stamped with the block it was computed
+* from, or the refusal as an error carrying its own numbers, see
+* {@link refusal}.
+*
+* The engine keeps its `ok` union — it is the shape the planners, the guards
+* and their tests are written against — and the boundary is the one place the
+* two vocabularies meet.
+**/
+function planned(result, at) {
+	if (!result.ok) return refusal(result);
+	const { operations, state, calls } = result;
+	return require_model_result.sdkOk({
+		operations,
+		state,
+		calls,
+		...at
+	});
+}
+/**
+* {@inheritDoc planned}
+*
+* A tail carries one thing the other results do not: whether the claim it was
+* built on finished the withdrawal, or left part of it queued for another one.
+**/
+function finalized(result, at) {
+	if (!result.ok) return refusal(result);
+	const { operations, state, calls, remainder } = result;
+	return require_model_result.sdkOk({
+		operations,
+		state,
+		calls,
+		remainder,
+		...at
+	});
+}
+/**
+* {@inheritDoc planned}
+**/
+function opened(result, at) {
+	return result.ok ? require_model_result.sdkOk({
+		state: result.state,
+		...at
+	}) : refusal(result);
+}
+/**
+* {@inheritDoc planned}
+*
+* Both routes are payload, refusal and all: `refused` says why a missing one is
+* missing, and it stays on the error when neither route answered, since that is
+* the same question asked of a request that has no viable half at all.
+**/
+function routed(result, at) {
+	if (!result.ok) {
+		const { refused, ...issue } = result;
+		return require_model_result.sdkErr({
+			...require_sdk_prepare_errors.toRefusalError(issue),
+			refused
+		});
+	}
+	const { instant, delayed, refused } = result;
+	return require_model_result.sdkOk({
+		instant: instant && {
+			operations: instant.operations,
+			state: instant.state,
+			calls: instant.calls,
+			...at
+		},
+		delayed: delayed && {
+			operations: delayed.operations,
+			state: delayed.state,
+			calls: delayed.calls,
+			delayed: delayed.delayed,
+			...at
+		},
+		refused,
+		...at
+	});
+}
+/**
+* The pool's own numbers as the namespace reports them: the trade the service
+* priced, the market it belongs to, and where the wallet's position lands.
+*
+* The position is measured in shares and converted once, rather than added up
+* in underlying, so the figure is exactly what a later
+* `sdk.positions.list()` will report — the same balance through the same rate.
+* A withdrawal larger than the position floors at nothing: the transaction
+* would revert long before it got there, and a negative holding is not a thing
+* a screen can show.
+**/
+async function lpState(sdk, pool, wallet, simulation, moved) {
+	const market = sdk.marketRegister.findByPool(pool);
+	const poolContract = market.pool.pool;
+	const after = await poolContract.getShareBalance(wallet) + (moved.mints ?? -moved.burns);
+	return {
+		...simulation,
+		curator: market.curator,
+		netValue: market.toUnderlyingAmount(poolContract.sharesToUnderlying(after > 0n ? after : 0n))
+	};
+}
+/**
+* A pool route the market does not offer, as the refusal a caller reads.
+*
+* `to` is absent where {@link lpRoute} found no output to name at all, which
+* is the usual way of it; both are present where a pair exists but nothing of
+* ours implements it.
+**/
+function unroutable(sdk, from, to) {
+	return require_model_result.sdkErr(require_sdk_prepare_errors.toRefusalError({
+		reason: "unsupportedTokenPair",
+		detail: {
+			from: require_onchain_validation_token.toToken(sdk, from),
+			to: to === void 0 ? void 0 : require_onchain_validation_token.toToken(sdk, to)
+		}
+	}));
+}
+/**
 * Picks the route the operation takes out of `tokenIn`, as a value rather than
 * an exception: an unroutable or ambiguous pair is a request the caller can
-* fix, so it belongs in the `ok: false` half alongside the strategy refusals.
+* fix, so it belongs in the failure half alongside the strategy refusals.
 *
 * A pool with no route out of the input reports it by throwing, hence the
 * catch; a requested output is checked against the list rather than trusted,