@strkfarm/sdk 2.0.0-dev.3 → 2.0.0-dev.31

package/src/strategies/vesu-extended-strategy/services/extended-vesu-state-manager.ts

@@ -0,0 +1,4087 @@
+import { ContractAddr, Web3Number } from "@/dataTypes";
+import { IConfig, TokenInfo } from "@/interfaces";
+import { PricerBase } from "@/modules/pricerBase";
+import { ERC20 } from "@/modules";
+import { assert, logger } from "@/utils";
+import { ExtendedAdapter } from "../../universal-adapters/extended-adapter";
+import { VesuMultiplyAdapter } from "../../universal-adapters/vesu-multiply-adapter";
+import { AssetOperationType, AssetOperationStatus } from "@/modules/ExtendedWrapperSDk";
+import { USDC_TOKEN_DECIMALS } from "../utils/constants";
+import {
+  calculateDeltaDebtAmount,
+  calculateExtendedLevergae,
+  calculateVesuLeverage,
+} from "../utils/helper";
+import { VesuConfig } from "../utils/config.runtime";
+import { rebalance, routableDrawAmount, type RebalanceDeltas } from "./ltv-imbalance-rebalance-math";
+
+// ─── State types ───────────────────────────────────────────────────────────────
+
+/**
+ * Snapshot of a single Vesu pool's position: collateral, debt, and their prices.
+ */
+export interface VesuPoolState {
+  poolId: ContractAddr;
+  collateralToken: TokenInfo;
+  debtToken: TokenInfo;
+  collateralAmount: Web3Number;
+  collateralUsdValue: number;
+  debtAmount: Web3Number;
+  debtUsdValue: number;
+  collateralPrice: number;
+  debtPrice: number;
+}
+
+/**
+ * Snapshot of a single Extended exchange open position.
+ */
+export interface ExtendedPositionState {
+  instrument: string;
+  side: string;
+  size: Web3Number;
+  valueUsd: Web3Number;
+  leverage: string;
+}
+
+/**
+ * Snapshot of the Extended exchange account-level balance.
+ */
+export interface ExtendedBalanceState {
+  equity: Web3Number;
+  availableForTrade: Web3Number;
+  availableForWithdrawal: Web3Number;
+  unrealisedPnl: Web3Number;
+  balance: Web3Number;
+  /**
+   * Funds in transit to/from Extended.
+   * Positive = deposit in transit (funds left wallet, not yet credited on Extended).
+   * Negative = withdrawal in transit (funds left Extended, not yet received in wallet).
+   */
+  pendingDeposit: Web3Number;
+}
+
+
+type Inputs = {
+  extAvlWithdraw: number;
+  extUpnl: number;
+  vaUsd: number;
+  walletUsd: number;
+  vesuBorrowCapacity: number;
+  vesuLeverage: number;
+  extendedLeverage: number;
+};
+
+type Deltas = {
+  dExtAvlWithdraw: number;
+  dExtUpnl: number;
+  dVaUsd: number;
+  dWalletUsd: number;
+  dVesuBorrowCapacity: number;
+  finalVaUsd: number;
+  finalExtended: number;
+  isExtendedToVesu: boolean;
+};
+
+/**
+ * Generic token balance with USD valuation.
+ */
+export interface TokenBalance {
+  token: TokenInfo;
+  amount: Web3Number;
+  usdValue: number;
+}
+
+// ─── Solve result types ────────────────────────────────────────────────────────
+
+/**
+ * Per-position exposure change on the Extended exchange.
+ * Positive delta = increase position size, negative = reduce.
+ */
+export interface ExtendedPositionDelta {
+  instrument: string;
+  delta: Web3Number;
+}
+
+/**
+ * Per-pool position change on Vesu.
+ * debtDelta: positive = borrow more, negative = repay.
+ * collateralDelta: positive = add collateral, negative = remove.
+ */
+export interface VesuPoolDelta {
+  poolId: ContractAddr;
+  collateralToken: TokenInfo;
+  debtToken: TokenInfo;
+  debtDelta: Web3Number;
+  collateralDelta: Web3Number;
+  collateralPrice: number;
+  debtPrice: number;
+}
+
+// ─── ExecutionRoute types ───────────────────────────────────────────────────────────────
+
+/**
+ * Enumerates all possible fund-routing paths used during execution.
+ */
+export enum RouteType {
+  /** Deposit USDC from operator wallet directly to Extended exchange */
+  WALLET_TO_EXTENDED = 'WALLET_TO_EXTENDED',
+  /** USDC from vault allocator → deposit to Extended (via manager) */
+  VA_TO_EXTENDED = 'VA_TO_EXTENDED',
+  /** Withdraw from Extended exchange → operator wallet */
+  EXTENDED_TO_WALLET = 'EXTENDED_TO_WALLET',
+  /** Swap USDC → BTC to deposit to Vesu */
+  AVNU_DEPOSIT_SWAP = 'AVNU_DEPOSIT_SWAP',
+  /** Increase leverage on Vesu i.e. deposit on vesu, borrow, in one go to create lever */
+  VESU_MULTIPLY_INCREASE_LEVER = 'VESU_MULTIPLY_INCREASE_LEVER',
+  /** Decrease leverage on Vesu i.e. withdraw from vesu, repay, in one go to reduce leverage */
+  VESU_MULTIPLY_DECREASE_LEVER = 'VESU_MULTIPLY_DECREASE_LEVER',
+  /** Swap BTC → USDC to withdraw from Vesu */
+  AVNU_WITHDRAW_SWAP = 'AVNU_WITHDRAW_SWAP',
+  /** Borrow additional USDC from Vesu (when wallet + VA insufficient for Extended) */
+  VESU_BORROW = 'VESU_BORROW',
+  /** Repay USDC debt to Vesu (debtDelta < 0) */
+  VESU_REPAY = 'VESU_REPAY',
+  /** Transfer USDC from operator wallet to vault allocator */
+  WALLET_TO_VA = 'WALLET_TO_VA',
+  /** Realize PnL on Extended exchange */
+  REALISE_PNL = 'REALISE_PNL',
+  /** Increase leverage on Extended exchange i.e. deposit on extended, in one go to create lever */
+  EXTENDED_INCREASE_LEVER = 'EXTENDED_INCREASE_LEVER',
+  /** Decrease leverage on Extended exchange i.e. withdraw from extended, in one go to reduce leverage */
+  EXTENDED_DECREASE_LEVER = 'EXTENDED_DECREASE_LEVER',
+
+  /** Increase leverage on Extended exchange to max leverage (e.g. 4x from 3x) */
+  CRISIS_INCREASE_EXTENDED_MAX_LEVERAGE = 'CRISIS_INCREASE_EXTENDER_MAX_LEVERAGE',
+  /** Undo max leverage on Extended exchange to reduce leverage (e.g. 4x to 3x) */
+  CRISIS_UNDO_EXTENDED_MAX_LEVERAGE = 'CRISIS_UNDO_EXTENDED_MAX_LEVERAGE',
+
+  /** Borrow beyyond target HF (e.g. 1.2 from 1.4) */
+  CRISIS_BORROW_BEYOND_TARGET_HF = 'CRISIS_BORROW_BEYOND_TARGET_HF',
+
+  /** Bring liquidity from vault allocator to vault contract (for user withdrawals) */
+  BRING_LIQUIDITY = 'BRING_LIQUIDITY',
+
+  // often a bridge tx is involved. when the solve cycle runs again
+  // bridges funds shall be handled again
+  RETURN_TO_WAIT = 'RETURN_TO_WAIT',
+}
+
+// ─── Per-route-type metadata ─────────────────────────────────────────────────
+
+/** Common fields shared by every route variant */
+interface RouteBase {
+  /** Execution order — lower values execute first */
+  priority: number;
+}
+
+/** Simple fund-transfer routes: WALLET_TO_EXTENDED, VA_TO_EXTENDED, EXTENDED_TO_WALLET, WALLET_TO_VA */
+export interface TransferRoute extends RouteBase {
+  type:
+  | RouteType.WALLET_TO_EXTENDED
+  | RouteType.VA_TO_EXTENDED
+  | RouteType.EXTENDED_TO_WALLET
+  | RouteType.WALLET_TO_VA;
+  /** Amount to transfer */
+  amount: Web3Number;
+}
+
+/** AVNU swap routes: AVNU_DEPOSIT_SWAP (USDC→BTC), AVNU_WITHDRAW_SWAP (BTC→USDC) */
+export interface SwapRoute extends RouteBase {
+  type: RouteType.AVNU_DEPOSIT_SWAP | RouteType.AVNU_WITHDRAW_SWAP;
+  /** Source token symbol */
+  fromToken: string;
+  /** Source amount */
+  fromAmount: Web3Number;
+  /** Destination token symbol */
+  toToken: string;
+  /** Exact output amount (if known; otherwise undefined means best-effort) */
+  toAmount?: Web3Number;
+}
+
+/** Vesu multiply lever routes: deposit+borrow or withdraw+repay in one go */
+export interface VesuMultiplyRoute extends RouteBase {
+  type: RouteType.VESU_MULTIPLY_INCREASE_LEVER | RouteType.VESU_MULTIPLY_DECREASE_LEVER;
+  /** Pool to interact with */
+  poolId: ContractAddr;
+  /** Collateral token info */
+  collateralToken: TokenInfo;
+  /** Collateral amount delta (positive = deposit, negative = withdraw) */
+  marginAmount: Web3Number; // in collateral token units
+  swappedCollateralAmount: Web3Number; // debt swapped, in collateral token units
+  /** Debt token info */
+  debtToken: TokenInfo;
+  /** Debt amount delta (positive = borrow, negative = repay) */
+  debtAmount: Web3Number;
+}
+
+/** Vesu single-side borrow / repay routes */
+export interface VesuDebtRoute extends RouteBase {
+  type: RouteType.VESU_BORROW | RouteType.VESU_REPAY;
+  /** Pool to interact with */
+  poolId: ContractAddr;
+  /** Amount to borrow (positive) or repay (negative) */
+  amount: Web3Number;
+  /** Collateral token info */
+  collateralToken: TokenInfo;
+  /** Debt token info */
+  debtToken: TokenInfo;
+}
+
+/** Realise PnL on Extended exchange */
+export interface RealisePnlRoute extends RouteBase {
+  type: RouteType.REALISE_PNL;
+  /** Amount of PnL to realise (the shortfall beyond available-to-withdraw) */
+  amount: Web3Number;
+  /** Extended instrument name (e.g. "BTC-USD") */
+  instrument: string;
+}
+
+/** Increase / decrease leverage on Extended exchange */
+export interface ExtendedLeverRoute extends RouteBase {
+  type: RouteType.EXTENDED_INCREASE_LEVER | RouteType.EXTENDED_DECREASE_LEVER;
+  /** Change in exposure denominated in the exposure token */
+  amount: Web3Number;
+  /** Extended instrument name (e.g. "BTC-USD") */
+  instrument: string;
+}
+
+/** Crisis: temporarily increase / undo max leverage on Extended — no args for now */
+export interface CrisisExtendedLeverRoute extends RouteBase {
+  type: RouteType.CRISIS_INCREASE_EXTENDED_MAX_LEVERAGE | RouteType.CRISIS_UNDO_EXTENDED_MAX_LEVERAGE;
+}
+
+/** Crisis: borrow beyond the normal target HF */
+export interface CrisisBorrowRoute extends RouteBase {
+  type: RouteType.CRISIS_BORROW_BEYOND_TARGET_HF;
+  /** Pool to borrow from */
+  poolId: ContractAddr;
+  /** Token being borrowed */
+  token: string;
+  /** Amount to borrow */
+  amount: Web3Number;
+}
+
+/** Bring liquidity from vault allocator to vault contract for user withdrawals */
+export interface BringLiquidityRoute extends RouteBase {
+  type: RouteType.BRING_LIQUIDITY;
+  /** Amount to bring */
+  amount: Web3Number;
+}
+
+/** Control routes: RETURN_TO_WAIT (stop execution, resume in next cycle) */
+export interface WaitRoute extends RouteBase {
+  type: RouteType.RETURN_TO_WAIT;
+}
+
+/**
+ * A single step in the execution plan produced by the solver.
+ * Discriminated union keyed on `type` — each variant carries only
+ * the metadata that specific route needs.
+ */
+export type ExecutionRoute =
+  | TransferRoute
+  | SwapRoute
+  | VesuMultiplyRoute
+  | VesuDebtRoute
+  | RealisePnlRoute
+  | ExtendedLeverRoute
+  | CrisisExtendedLeverRoute
+  | CrisisBorrowRoute
+  | BringLiquidityRoute
+  | WaitRoute;
+
+// ─── Case classification types ──────────────────────────────────────────────────
+
+/**
+ * Broad category of a detected case. Multiple categories may apply simultaneously.
+ */
+export enum CaseCategory {
+  LTV_REBALANCE = 'LTV_REBALANCE',
+  NEW_DEPOSITS = 'NEW_DEPOSITS',
+  WITHDRAWAL = 'WITHDRAWAL',
+  EXPOSURE_IMBALANCE = 'EXPOSURE_IMBALANCE',
+  MARGIN_CRISIS = 'MARGIN_CRISIS',
+}
+
+/**
+ * Specific case IDs corresponding to the situations defined in cases.json.
+ */
+export enum CaseId {
+  // LTV Rebalance
+  MANAGE_LTV = 'MANAGE_LTV',
+  /** @deprecated use MANAGE_LTV */ LTV_VESU_LOW_TO_EXTENDED = 'LTV_VESU_LOW_TO_EXTENDED',
+  /** @deprecated use MANAGE_LTV */ LTV_EXTENDED_PROFITABLE_AVAILABLE = 'LTV_EXTENDED_PROFITABLE_AVAILABLE',
+  /** @deprecated use MANAGE_LTV */ LTV_EXTENDED_PROFITABLE_REALIZE = 'LTV_EXTENDED_PROFITABLE_REALIZE',
+  /** @deprecated use MANAGE_LTV */ LTV_VESU_HIGH_USE_VA_OR_WALLET = 'LTV_VESU_HIGH_USE_VA_OR_WALLET',
+  /** @deprecated use MANAGE_LTV */ LTV_EXTENDED_HIGH_USE_VA_OR_WALLET = 'LTV_EXTENDED_HIGH_USE_VA_OR_WALLET',
+
+  // New Deposits / Excess Funds
+  DEPOSIT_FRESH_VAULT = 'DEPOSIT_FRESH_VAULT',
+  DEPOSIT_EXTENDED_AVAILABLE = 'DEPOSIT_EXTENDED_AVAILABLE',
+  DEPOSIT_VESU_BORROW_CAPACITY = 'DEPOSIT_VESU_BORROW_CAPACITY',
+  DEPOSIT_COMBINATION = 'DEPOSIT_COMBINATION',
+  // Withdrawal
+  WITHDRAWAL_SIMPLE = 'WITHDRAWAL_SIMPLE',
+  // Margin Crisis
+  MARGIN_CRISIS_EXTENDED = 'MARGIN_CRISIS_EXTENDED',
+  MARGIN_CRISIS_VESU = 'MARGIN_CRISIS_VESU',
+  // Exposure Imbalance
+  IMBALANCE_EXTENDED_EXCESS_SHORT_NO_FUNDS = 'IMBALANCE_EXTENDED_EXCESS_SHORT_NO_FUNDS',
+  IMBALANCE_EXTENDED_EXCESS_SHORT_HAS_FUNDS = 'IMBALANCE_EXTENDED_EXCESS_SHORT_HAS_FUNDS',
+  IMBALANCE_VESU_EXCESS_LONG_NO_FUNDS = 'IMBALANCE_VESU_EXCESS_LONG_NO_FUNDS',
+  IMBALANCE_VESU_EXCESS_LONG_HAS_FUNDS = 'IMBALANCE_VESU_EXCESS_LONG_HAS_FUNDS',
+}
+
+/**
+ * A detected case describing the current system state and the
+ * high-level steps required to resolve it.
+ */
+export interface SolveCase {
+  id: CaseId;
+  category: CaseCategory;
+  title: string;
+  description: string;
+  /** High-level steps describing what needs to happen for this case */
+  steps: string[];
+}
+
+/** Minimum USD amount to consider a case significant */
+const CASE_THRESHOLD_USD = 5;
+const CASE_MIN_BRIDING_USD = 10;
+/** Decimal places for rounding collateral / exposure deltas in token terms (e.g. BTC) */
+export const COLLATERAL_PRECISION = 4;
+
+/** Safely create a Web3Number from a float, avoiding >15 significant digit errors */
+function safeUsdcWeb3Number(value: number): Web3Number {
+  return new Web3Number(value.toFixed(USDC_TOKEN_DECIMALS), USDC_TOKEN_DECIMALS);
+}
+
+/**
+ * A single detected case with its metadata, amounts, and the execution
+ * routes that belong to this case.
+ */
+export interface SolveCaseEntry {
+  case: SolveCase;
+  additionalArgs: { amount?: Web3Number };
+  routes: ExecutionRoute[];
+}
+
+/**
+ * Maps each CaseId to the RouteTypes that are relevant for resolving it.
+ * Used to filter the global route list into per-case route subsets.
+ */
+export const CASE_ROUTE_TYPES: Record<CaseId, RouteType[]> = {
+  // LTV Rebalance — unified
+  [CaseId.MANAGE_LTV]: [
+    RouteType.REALISE_PNL, RouteType.EXTENDED_TO_WALLET, RouteType.RETURN_TO_WAIT,
+    RouteType.WALLET_TO_VA, RouteType.VESU_BORROW, RouteType.VESU_REPAY, RouteType.VA_TO_EXTENDED,
+    RouteType.VESU_MULTIPLY_DECREASE_LEVER, RouteType.VESU_MULTIPLY_INCREASE_LEVER,
+    RouteType.AVNU_DEPOSIT_SWAP,
+    RouteType.EXTENDED_DECREASE_LEVER, RouteType.EXTENDED_INCREASE_LEVER,
+    // Second-phase VA / Extended funding after lever routes (same types may repeat).
+    RouteType.RETURN_TO_WAIT, RouteType.WALLET_TO_VA, RouteType.VA_TO_EXTENDED,
+  ],
+  /** @deprecated */ [CaseId.LTV_VESU_HIGH_USE_VA_OR_WALLET]: [RouteType.WALLET_TO_VA, RouteType.VESU_REPAY],
+  /** @deprecated */ [CaseId.LTV_EXTENDED_PROFITABLE_AVAILABLE]: [RouteType.EXTENDED_TO_WALLET, RouteType.RETURN_TO_WAIT, RouteType.WALLET_TO_VA, RouteType.VESU_REPAY],
+  /** @deprecated */ [CaseId.LTV_EXTENDED_PROFITABLE_REALIZE]: [RouteType.REALISE_PNL, RouteType.EXTENDED_TO_WALLET, RouteType.RETURN_TO_WAIT, RouteType.WALLET_TO_VA, RouteType.VESU_REPAY],
+  /** @deprecated */ [CaseId.LTV_EXTENDED_HIGH_USE_VA_OR_WALLET]: [RouteType.VA_TO_EXTENDED, RouteType.WALLET_TO_EXTENDED],
+  /** @deprecated */ [CaseId.LTV_VESU_LOW_TO_EXTENDED]: [RouteType.VESU_BORROW, RouteType.VA_TO_EXTENDED],
+
+  // New Deposits
+  // @dev, when handling routes, after VA_TO_EXTENDED and/or WALLET_TO_EXTENDED, return. bcz, funds take time to reach extended. Anyways, in next cycle, these funds will be computed to increase lever
+  // Sequence: fund-movement transfers first (WALLET_TO_EXTENDED, VA_TO_EXTENDED, WALLET_TO_VA, EXTENDED_TO_WALLET),
+  //           then RETURN_TO_WAIT, then optional second WALLET_TO_VA + RETURN_TO_WAIT, then lever routes.
+  [CaseId.DEPOSIT_FRESH_VAULT]: [
+    // May repeat after MANAGE_LTV (VA top-up → Extended → wait → levers).
+    RouteType.WALLET_TO_VA,
+    RouteType.VA_TO_EXTENDED,
+    RouteType.RETURN_TO_WAIT,
+    RouteType.VA_TO_EXTENDED,
+    RouteType.VESU_BORROW,
+    RouteType.WALLET_TO_EXTENDED,
+    RouteType.VA_TO_EXTENDED,
+    RouteType.WALLET_TO_VA,
+    RouteType.EXTENDED_TO_WALLET,
+    RouteType.RETURN_TO_WAIT,
+    RouteType.WALLET_TO_VA,
+    RouteType.AVNU_DEPOSIT_SWAP,
+    RouteType.VESU_MULTIPLY_INCREASE_LEVER,
+    RouteType.EXTENDED_INCREASE_LEVER,
+  ],
+  [CaseId.DEPOSIT_EXTENDED_AVAILABLE]: [RouteType.EXTENDED_TO_WALLET, RouteType.RETURN_TO_WAIT, RouteType.WALLET_TO_VA, RouteType.AVNU_DEPOSIT_SWAP, RouteType.VESU_MULTIPLY_INCREASE_LEVER, RouteType.EXTENDED_INCREASE_LEVER],
+  [CaseId.DEPOSIT_VESU_BORROW_CAPACITY]: [RouteType.VESU_BORROW, RouteType.VA_TO_EXTENDED, RouteType.RETURN_TO_WAIT, RouteType.AVNU_DEPOSIT_SWAP, RouteType.VESU_MULTIPLY_INCREASE_LEVER, RouteType.EXTENDED_INCREASE_LEVER],
+  [CaseId.DEPOSIT_COMBINATION]: [], // exroutes to be computed on the fly based on above sub routes and where deposit is available
+  // Withdrawal
+  // Sequence: transfer out first (EXTENDED_TO_WALLET, RETURN_TO_WAIT, WALLET_TO_VA), then unwind lever, then BRING_LIQUIDITY
+  [CaseId.WITHDRAWAL_SIMPLE]: [RouteType.EXTENDED_TO_WALLET, RouteType.RETURN_TO_WAIT, RouteType.WALLET_TO_VA, RouteType.VESU_MULTIPLY_DECREASE_LEVER, RouteType.AVNU_WITHDRAW_SWAP, RouteType.EXTENDED_DECREASE_LEVER, RouteType.BRING_LIQUIDITY],
+
+  // Margin Crisis
+  // amounts must be chosen such that, when decresing lever, the LTV reached should be adequate, not high not low.
+  [CaseId.MARGIN_CRISIS_EXTENDED]: [RouteType.CRISIS_BORROW_BEYOND_TARGET_HF, RouteType.VA_TO_EXTENDED, RouteType.RETURN_TO_WAIT, RouteType.VESU_MULTIPLY_DECREASE_LEVER, RouteType.EXTENDED_DECREASE_LEVER, RouteType.CRISIS_UNDO_EXTENDED_MAX_LEVERAGE],
+  [CaseId.MARGIN_CRISIS_VESU]: [RouteType.CRISIS_INCREASE_EXTENDED_MAX_LEVERAGE, RouteType.EXTENDED_TO_WALLET, RouteType.WALLET_TO_VA, RouteType.VESU_MULTIPLY_DECREASE_LEVER, RouteType.EXTENDED_DECREASE_LEVER, RouteType.CRISIS_UNDO_EXTENDED_MAX_LEVERAGE],
+
+  // Exposure Imbalance
+  // try to use available funds in VA/Wallet to increase lever in vesu. if not possible, reduce lever on extended for remaining
+  [CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_HAS_FUNDS]: [RouteType.AVNU_DEPOSIT_SWAP, RouteType.VESU_MULTIPLY_INCREASE_LEVER, RouteType.EXTENDED_DECREASE_LEVER],
+
+  // no available funds in VA/Wallet to increase lever in vesu. reduce lever on extended for remaining
+  [CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_NO_FUNDS]: [RouteType.EXTENDED_DECREASE_LEVER],
+
+  // try to use available funds in VA/Wallet to increase lever in extended. if not possible, reduce lever on vesu for remaining
+  [CaseId.IMBALANCE_VESU_EXCESS_LONG_HAS_FUNDS]: [RouteType.VA_TO_EXTENDED, RouteType.WALLET_TO_EXTENDED, RouteType.RETURN_TO_WAIT, RouteType.EXTENDED_INCREASE_LEVER, RouteType.RETURN_TO_WAIT, RouteType.VESU_MULTIPLY_DECREASE_LEVER],
+
+  // no available funds in VA/Wallet to increase lever in extended. reduce lever on vesu for remaining
+  [CaseId.IMBALANCE_VESU_EXCESS_LONG_NO_FUNDS]: [RouteType.VESU_MULTIPLY_DECREASE_LEVER],
+};
+
+/** Minimum exposure imbalance fraction to flag an imbalance case */
+const IMBALANCE_THRESHOLD_FRACTION = 0.0002; // 0.02%
+
+/**
+ * Static case definitions derived from cases.json.
+ * Each entry maps a CaseId to its metadata and descriptive steps.
+ */
+const CASE_DEFINITIONS: Record<CaseId, SolveCase> = {
+  [CaseId.MANAGE_LTV]: {
+    id: CaseId.MANAGE_LTV,
+    category: CaseCategory.LTV_REBALANCE,
+    title: 'LTV Rebalance: Unified Vesu repay + Extended margin management',
+    description: 'Manages both Vesu high-LTV repayment and Extended low-margin funding in a single pass.',
+    steps: [
+      'Compute vesu repay needed and extended margin needed',
+      'Allocate funds: VA > Wallet > ExtAvl > ExtUpnl for Vesu; Wallet > VA > Borrow for Extended',
+      'Build combined transfer and repay/margin routes',
+    ],
+  },
+  [CaseId.LTV_VESU_LOW_TO_EXTENDED]: {
+    id: CaseId.LTV_VESU_LOW_TO_EXTENDED,
+    category: CaseCategory.LTV_REBALANCE,
+    title: 'LTV Rebalance: Vesu Low LTV → Extended (No BTC Imbalance)',
+    description: 'Exposures are balanced on both sides, but Vesu has low LTV (can borrow more). Extended needs additional margin.',
+    steps: [
+      'Borrow additional USDC from Vesu (up to target LTV)',
+      'Vault → Extended: Deposit borrowed USDC as margin',
+    ],
+  },
+  [CaseId.LTV_EXTENDED_PROFITABLE_AVAILABLE]: {
+    id: CaseId.LTV_EXTENDED_PROFITABLE_AVAILABLE,
+    category: CaseCategory.LTV_REBALANCE,
+    title: 'LTV Rebalance: Extended Profitable → Vesu (Funds Available to Withdraw)',
+    description: 'Exposures balanced. Extended is profitable with sufficient available-to-withdraw funds. Vesu needs more collateral.',
+    steps: [
+      'Withdraw USDC from Extended to Wallet',
+      'Wallet → Vault: Transfer USDC',
+      'Vault → Vesu: Deposit USDC to repay',
+    ],
+  },
+  [CaseId.LTV_EXTENDED_PROFITABLE_REALIZE]: {
+    id: CaseId.LTV_EXTENDED_PROFITABLE_REALIZE,
+    category: CaseCategory.LTV_REBALANCE,
+    title: 'LTV Rebalance: Extended Profitable → Vesu (Need to Realize PnL)',
+    description: 'Exposures balanced. Extended is profitable but available-to-withdraw is insufficient. Unrealized PnL needs to be realized.',
+    steps: [
+      'Partially close short BTC position on Extended (realize PnL)',
+      'Immediately reopen short BTC position on Extended (maintain exposure)',
+      'Withdraw realized USDC from Extended to Wallet',
+      'Wallet → Vault: Transfer USDC',
+      'Vault → Vesu: Deposit USDC as collateral',
+    ],
+  },
+  [CaseId.LTV_VESU_HIGH_USE_VA_OR_WALLET]: {
+    id: CaseId.LTV_VESU_HIGH_USE_VA_OR_WALLET,
+    category: CaseCategory.LTV_REBALANCE,
+    title: 'LTV Rebalance: Vesu High LTV (Use VA or Wallet)',
+    description: 'Vesu has high LTV (can repay debt). funds available in VA and/or Wallet can be used to repay debt.',
+    steps: [
+      'Wallet → Vesu -> Vesu: Repay using USDC',
+    ],
+  },
+  [CaseId.LTV_EXTENDED_HIGH_USE_VA_OR_WALLET]: {
+    id: CaseId.LTV_EXTENDED_HIGH_USE_VA_OR_WALLET,
+    category: CaseCategory.LTV_REBALANCE,
+    title: 'LTV Rebalance: Extended High LTV (Use VA or Wallet)',
+    description: 'Extended has high LTV (can borrow more). funds available in VA and/or Wallet can be used to add margin',
+    steps: [
+      'VA or Wallet → Extended -> Extended: Borrow using USDC',
+    ],
+  },
+  [CaseId.DEPOSIT_FRESH_VAULT]: {
+    id: CaseId.DEPOSIT_FRESH_VAULT,
+    category: CaseCategory.NEW_DEPOSITS,
+    title: 'New Deposits/Excess Funds: Fresh USDC in Vault',
+    description: 'Fresh USDC deposits received in Vault contract.',
+    steps: [
+      'Unused funds in Vault or in Wallet',
+      'Calculate allocation amounts for Extended and Vesu',
+      'Vault and/or Wallet → Extended: Deposit allocated USDC',
+      'Once extended receives the funds, open short BTC position',
+      'Vault and/or Wallet → Vesu: Deposit allocated USDC, borrow USDC, open long BTC position',
+    ],
+  },
+  [CaseId.DEPOSIT_EXTENDED_AVAILABLE]: {
+    id: CaseId.DEPOSIT_EXTENDED_AVAILABLE,
+    category: CaseCategory.NEW_DEPOSITS,
+    title: 'New Deposits/Excess Funds: Available to Withdraw from Extended',
+    description: 'Extended has excess available-to-withdraw funds that can be deployed without LTV rebalancing or BTC imbalance concerns.',
+    steps: [
+      'Calculate position increase amounts for both protocols',
+      'Withdraw portion of funds from Extended to Wallet (if needed for Vesu). If part of the required funds are in unrealised PnL, convert to realised PnL.',
+      'Once wallet receives the funds, use available funds on Extended to increase short BTC position',
+      'Wallet → Vault → Vesu: Deposit USDC as collateral',
+      'Borrow USDC from Vesu, open additional long BTC position',
+    ],
+  },
+  [CaseId.DEPOSIT_VESU_BORROW_CAPACITY]: {
+    id: CaseId.DEPOSIT_VESU_BORROW_CAPACITY,
+    category: CaseCategory.NEW_DEPOSITS,
+    title: 'New Deposits/Excess Funds: Available Borrowing Capacity on Vesu',
+    description: 'Vesu has low LTV with excess borrowing capacity that can be deployed for position expansion.',
+    steps: [
+      'Borrow additional USDC from Vesu (within safe LTV limits)',
+      'Calculate allocation for position expansion',
+      'Deposit portion of funds on Extended',
+      'Once extended receives the funds, open short BTC position',
+      'Use portion to open additional long BTC position on Vesu',
+    ],
+  },
+  [CaseId.DEPOSIT_COMBINATION]: {
+    id: CaseId.DEPOSIT_COMBINATION,
+    category: CaseCategory.NEW_DEPOSITS,
+    title: 'New Deposits/Excess Funds: Combination case',
+    description: 'Combination of new deposits/excess funds on vault/extended/vesu.',
+    steps: [
+      'Optimally distribute funds from multiple sources and create new positions. Avoid unnecessary routes.',
+    ],
+  },
+  [CaseId.WITHDRAWAL_SIMPLE]: {
+    id: CaseId.WITHDRAWAL_SIMPLE,
+    category: CaseCategory.WITHDRAWAL,
+    title: 'User Withdrawal: Simple Position Reduction',
+    description: 'User requests withdrawal with sufficient available funds to close positions proportionally.',
+    steps: [
+      'First check if any available funds can be used to settle the withdrawal (vault, available to withdraw or borrowing from vesu)',
+      'If yes, do necessary transfers such that funds are available in vault',
+      'If not or if more required, calculate position sizes to close on both sides',
+      'Close long BTC position on Vesu (partially or fully)',
+      'Repay borrowed USDC on Vesu',
+      'Withdraw collateral from Vesu to Vault',
+      'Close short BTC position on Extended',
+      'Withdraw margin from Extended to Wallet',
+      'Wallet → Vault: Transfer USDC',
+      'Vault → User: Process withdrawal',
+    ],
+  },
+  [CaseId.MARGIN_CRISIS_EXTENDED]: {
+    id: CaseId.MARGIN_CRISIS_EXTENDED,
+    category: CaseCategory.MARGIN_CRISIS,
+    title: 'Margin Crisis: LTV rebalance requires more funds than available, margin required on Extended',
+    description: 'LTV rebalance requires more funds than available on vault/extended/vesu. Extended needs margin urgently.',
+    steps: [
+      'Calculate required position reduction in vesu and extended',
+      'Borrow more on vesu such that HF can go max up to 1.2',
+      'Use the borrowed funds to settle margin requirements on Extended (vault to extended)',
+      'Once funds reach on extended, close portion of long BTC position on Vesu',
+      'Convert BTC to USDC',
+      'Repay portion of borrowed USDC on Vesu such that HF can go back to target',
+      'Close corresponding short BTC position on Extended (match reduced exposure)',
+    ],
+  },
+  [CaseId.MARGIN_CRISIS_VESU]: {
+    id: CaseId.MARGIN_CRISIS_VESU,
+    category: CaseCategory.MARGIN_CRISIS,
+    title: 'Margin Crisis: LTV rebalance requires more funds than available, margin required on Vesu',
+    description: 'LTV rebalance requires more funds than available on vault/extended/vesu. Vesu needs margin urgently.',
+    steps: [
+      'Calculate required position reduction in extended',
+      'Update leverage to 4x and try to use available to withdraw funds on extended',
+      'Wait until funds reach on wallet',
+      'Close portion of short BTC position on Extended',
+      'Move wallet to vault and use the USDC to repay on vesu',
+      'Reduce long position to match the short position on extended',
+    ],
+  },
+  [CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_NO_FUNDS]: {
+    id: CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_NO_FUNDS,
+    category: CaseCategory.EXPOSURE_IMBALANCE,
+    title: 'BTC Imbalance: Extended Has Excess Short (No funds to match)',
+    description: 'Extended has more short BTC exposure than Vesu long. No funds available to increase Vesu long.',
+    steps: [
+      'Reduce short BTC position on Extended to match the long position on Vesu',
+    ],
+  },
+  [CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_HAS_FUNDS]: {
+    id: CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_HAS_FUNDS,
+    category: CaseCategory.EXPOSURE_IMBALANCE,
+    title: 'BTC Imbalance: Extended Has Excess Short (Vault/Wallet Has Funds)',
+    description: 'Extended has more short BTC exposure than Vesu long. Use available funds to increase long on Vesu.',
+    steps: [
+      'Use available funds to increase long on Vesu as much as possible',
+      'If still not matched, reduce short BTC position on Extended to match the long position on Vesu',
+    ],
+  },
+  [CaseId.IMBALANCE_VESU_EXCESS_LONG_NO_FUNDS]: {
+    id: CaseId.IMBALANCE_VESU_EXCESS_LONG_NO_FUNDS,
+    category: CaseCategory.EXPOSURE_IMBALANCE,
+    title: 'BTC Imbalance: Vesu Has Excess Long (No funds to match)',
+    description: 'Vesu has more long BTC exposure than Extended short. Extended does not have enough available to trade funds.',
+    steps: [
+      'Reduce long BTC position on Vesu to match the short position on Extended',
+    ],
+  },
+  [CaseId.IMBALANCE_VESU_EXCESS_LONG_HAS_FUNDS]: {
+    id: CaseId.IMBALANCE_VESU_EXCESS_LONG_HAS_FUNDS,
+    category: CaseCategory.EXPOSURE_IMBALANCE,
+    title: 'BTC Imbalance: Vesu Has Excess Long (Extended has funds)',
+    description: 'Vesu has more long BTC exposure than Extended short. Extended has available to trade funds to match.',
+    steps: [
+      'Use available funds to increase short on Extended as much as possible',
+      'If still not matched, reduce long BTC position on Vesu to match the short position on Extended',
+    ],
+  },
+};
+
+/**
+ * Complete output from the solver describing all needed state changes.
+ *
+ * - cases:                    detected cases describing the system state and needed actions.
+ * - extendedDeposit:          positive = deposit USDC into Extended, negative = withdraw.
+ * - extendedPositionDeltas:   per-instrument exposure changes (with instrument id).
+ * - vesuDeltas:               per-pool debt & collateral changes (with pool id and token pair).
+ * - vesuAllocationUsd:        USDC directed to Vesu side (negative = unwind from Vesu).
+ * - extendedAllocationUsd:    USDC directed to Extended side (negative = withdraw from Extended).
+ * - bringLiquidityAmount:     amount VA should send via bringLiquidity to the vault
+ *                             (= withdrawAmount input; 0 during investment cycles).
+ */
+export interface SolveResult {
+  /** Detected cases describing the current situation, amounts, and per-case routes */
+  cases: SolveCaseEntry[];
+  extendedDeposit: Web3Number;
+  extendedPositionDeltas: ExtendedPositionDelta[];
+  vesuDepositAmount: Web3Number;
+  vesuDeltas: VesuPoolDelta[];
+  vesuAllocationUsd: Web3Number;
+  extendedAllocationUsd: Web3Number;
+  bringLiquidityAmount: Web3Number;
+  /**
+   * Net pending deposit for Extended.
+   * Positive = deposit in transit (wallet → Extended), negative = withdrawal in transit.
+   * Used by ExecutionService to avoid double-sending transfers.
+   */
+  pendingDeposit: Web3Number;
+}
+
+// ─── Config ────────────────────────────────────────────────────────────────────
+
+export interface StateManagerConfig {
+  pricer: PricerBase;
+  networkConfig: IConfig;
+  vesuAdapters: VesuMultiplyAdapter[];
+  extendedAdapter: ExtendedAdapter;
+  vaultAllocator: ContractAddr;
+  walletAddress: string;
+  /** Strategy / vault token — idle balance in the vault allocator is denominated in this asset */
+  assetToken: TokenInfo;
+  /**
+   * Native USDC (Starknet) — operator wallet stablecoin balance is always read for this token,
+   * independent of {@link assetToken} (e.g. when the strategy vault uses another asset).
+   */
+  usdcToken: TokenInfo;
+  /** Collateral token (e.g. WBTC) for wallet balance checks */
+  collateralToken: TokenInfo;
+  limitBalanceBufferFactor: number;
+}
+
+// ─── ExecutionRoute helpers ──────────────────────────────────────────────────────────────
+
+/**
+ * Returns a short human-readable summary of a route's key fields for logging.
+ */
+export function routeSummary(r: ExecutionRoute): string {
+  switch (r.type) {
+    case RouteType.WALLET_TO_EXTENDED:
+    case RouteType.VA_TO_EXTENDED:
+    case RouteType.EXTENDED_TO_WALLET:
+    case RouteType.WALLET_TO_VA:
+      return `${r.amount.toNumber()}`;
+    case RouteType.AVNU_DEPOSIT_SWAP:
+    case RouteType.AVNU_WITHDRAW_SWAP:
+      return `${r.fromAmount.toNumber()} ${r.fromToken}→${r.toToken}`;
+    case RouteType.VESU_MULTIPLY_INCREASE_LEVER:
+    case RouteType.VESU_MULTIPLY_DECREASE_LEVER:
+      return `coll=${r.marginAmount.toNumber()} [${r.marginAmount.decimals}] debt=${r.debtAmount.toNumber()} [${r.debtAmount.decimals}] (swapped ${r.swappedCollateralAmount.toNumber()} [${r.swappedCollateralAmount.decimals}]) pool=${r.poolId.shortString()}`;
+    case RouteType.VESU_BORROW:
+    case RouteType.VESU_REPAY:
+      return `${r.amount.toNumber()} ${r.debtToken.symbol} pool=${r.poolId.shortString()} [Collateral: ${r.collateralToken.symbol}]`;
+    case RouteType.REALISE_PNL:
+      return `${r.amount.toNumber()} ${r.instrument}`;
+    case RouteType.EXTENDED_INCREASE_LEVER:
+    case RouteType.EXTENDED_DECREASE_LEVER:
+      return `${r.amount.toNumber()} ${r.instrument}`;
+    case RouteType.CRISIS_INCREASE_EXTENDED_MAX_LEVERAGE:
+    case RouteType.CRISIS_UNDO_EXTENDED_MAX_LEVERAGE:
+      return '(no args)';
+    case RouteType.CRISIS_BORROW_BEYOND_TARGET_HF:
+      return `${r.amount.toNumber()} ${r.token} pool=${r.poolId.shortString()}`;
+    case RouteType.BRING_LIQUIDITY:
+      return `${r.amount.toNumber()}`;
+    case RouteType.RETURN_TO_WAIT:
+      return '(control)';
+    default:
+      return '';
+  }
+}
+
+// ─── Solve Budget ───────────────────────────────────────────────────────────────
+
+/**
+ * Single source of truth for all mutable state during a solve() call.
+ *
+ * Stores **raw** snapshots from refresh (no safety buffer applied in fields).
+ * Buffer {@link limitBalanceBufferFactor} is applied only in **getters** used
+ * during solve (caps, diagnostics). **Spend / add** methods mutate balances
+ * in **raw** USD only (no buffer on debits or credits).
+ *
+ * **Extended deposits** ({@link SolveBudget.addToExtAvailTrade}): while account equity is
+ * below required margin (Σ position value ÷ Extended leverage), incoming USDC is credited
+ * only to **balance** and **equity**. Only the excess is credited to **availableForWithdrawal**
+ * and **availableForTrade**, matching “margin first, then free collateral”.
+ */
+export class SolveBudget {
+  // ── Refreshed state (mutable during solve, raw on-chain / API values) ─
+  private unusedBalance: TokenBalance[];
+  private walletBalance: TokenBalance | null;
+  /**
+   * Idle non-stable {@link StateManagerConfig.assetToken} in the vault allocator.
+   * Null when asset and USDC are the same token (VA idle stablecoin is only in {@link vaultUsdcBalance}).
+   */
+  private vaultAssetBalance: TokenBalance | null;
+  /** Idle {@link StateManagerConfig.usdcToken} in the vault allocator (including when it is also the strategy asset). */
+  private vaultUsdcBalance: TokenBalance | null;
+  private extendedPositions: ExtendedPositionState[];
+  private extendedBalance: ExtendedBalanceState | null;
+  private vesuPoolStates: VesuPoolState[];
+  private vesuPerPoolDebtDeltasToBorrow: Web3Number[];
+  private shouldVesuRebalance: boolean[]; // should be same length as vesuPerPoolDebtDeltasToBorrow
+
+  readonly assetToken: TokenInfo;
+  readonly usdcToken: TokenInfo;
+
+  constructor(state: {
+    assetToken: TokenInfo;
+    usdcToken: TokenInfo;
+    unusedBalance: TokenBalance[];
+    walletBalance: TokenBalance | null;
+    vaultAssetBalance: TokenBalance | null;
+    vaultUsdcBalance: TokenBalance | null;
+    extendedPositions: ExtendedPositionState[];
+    extendedBalance: ExtendedBalanceState | null;
+    vesuPoolStates: VesuPoolState[];
+  }) {
+    this.assetToken = state.assetToken;
+    this.usdcToken = state.usdcToken;
+
+    const cloneTb = (b: TokenBalance): TokenBalance => ({
+      token: b.token,
+      amount: new Web3Number(b.amount.toFixed(b.token.decimals), b.token.decimals),
+      usdValue: b.usdValue,
+    });
+
+    this.unusedBalance = state.unusedBalance.map((item) => cloneTb(item));
+    this.walletBalance = state.walletBalance ? cloneTb(state.walletBalance) : null;
+    this.vaultAssetBalance = state.vaultAssetBalance ? cloneTb(state.vaultAssetBalance) : null;
+    this.vaultUsdcBalance = state.vaultUsdcBalance ? cloneTb(state.vaultUsdcBalance) : null;
+
+    // Deep-clone mutable Extended / Vesu snapshots so route-building dry-runs (e.g. _classifyLTV)
+    // cannot mutate shared objects when callers reuse the same fixture for multiple budgets.
+    this.extendedPositions = state.extendedPositions.map((p) => ({
+      ...p,
+      size: new Web3Number(p.size.toFixed(8), 8),
+      valueUsd: new Web3Number(p.valueUsd.toFixed(USDC_TOKEN_DECIMALS), USDC_TOKEN_DECIMALS),
+    }));
+    this.extendedBalance = state.extendedBalance
+      ? {
+        equity: new Web3Number(
+          state.extendedBalance.equity.toFixed(USDC_TOKEN_DECIMALS),
+          USDC_TOKEN_DECIMALS,
+        ),
+        availableForTrade: new Web3Number(
+          state.extendedBalance.availableForTrade.toFixed(USDC_TOKEN_DECIMALS),
+          USDC_TOKEN_DECIMALS,
+        ),
+        availableForWithdrawal: new Web3Number(
+          state.extendedBalance.availableForWithdrawal.toFixed(USDC_TOKEN_DECIMALS),
+          USDC_TOKEN_DECIMALS,
+        ),
+        unrealisedPnl: new Web3Number(
+          state.extendedBalance.unrealisedPnl.toFixed(USDC_TOKEN_DECIMALS),
+          USDC_TOKEN_DECIMALS,
+        ),
+        balance: new Web3Number(
+          state.extendedBalance.balance.toFixed(USDC_TOKEN_DECIMALS),
+          USDC_TOKEN_DECIMALS,
+        ),
+        pendingDeposit: new Web3Number(
+          state.extendedBalance.pendingDeposit.toFixed(USDC_TOKEN_DECIMALS),
+          USDC_TOKEN_DECIMALS,
+        ),
+      }
+      : null;
+    this.vesuPoolStates = state.vesuPoolStates.map((p) => ({
+      ...p,
+      collateralAmount: new Web3Number(
+        p.collateralAmount.toFixed(p.collateralToken.decimals),
+        p.collateralToken.decimals,
+      ),
+      debtAmount: new Web3Number(
+        p.debtAmount.toFixed(p.debtToken.decimals),
+        p.debtToken.decimals,
+      ),
+    }));
+    const vesuPerPoolDebtDeltasToBorrow = this._computeperPoolDebtDeltasToBorrow();
+    assert(vesuPerPoolDebtDeltasToBorrow.length === this.vesuPoolStates.length, 'vesuPerPoolDebtDeltasToBorrow length must match vesuPoolStates length');
+    this.vesuPerPoolDebtDeltasToBorrow = vesuPerPoolDebtDeltasToBorrow.map((item) => item.deltaDebt);
+    this.shouldVesuRebalance = vesuPerPoolDebtDeltasToBorrow.map((item) => item.shouldRebalance);
+  }
+
+  /** `1 - limitBalanceBufferFactor` — multiplier applied to raw notionals for “usable” USD. */
+  private _usableFraction(): number {
+    return 1;
+  }
+
+  /**
+   * Raw USD notional for a token row. USDC (and configured {@link usdcToken}) uses 1:1 from amount;
+   * non-stable assets (e.g. WBTC in VA) use {@link TokenBalance.usdValue} from the pricer at refresh.
+   */
+  private _rawTokenUsd(tb: TokenBalance | null | undefined): number {
+    if (!tb) return 0;
+    if (this.usdcToken.address.eq(tb.token.address)) {
+      return Number(tb.amount.toFixed(tb.token.decimals));
+    }
+    return tb.usdValue;
+  }
+
+  /** Apply safety buffer to a raw USD scalar. */
+  bufferedUsd(rawUsd: number): number {
+    return rawUsd * this._usableFraction();
+  }
+
+  /** Convert a buffered “usable” USD amount to raw nominal USD (inverse of {@link bufferedUsd}). */
+  rawUsdFromBuffered(bufferedUsd: number): number {
+    const bf = this._usableFraction();
+    assert(bf > 0, 'SolveBudget::rawUsdFromBuffered usable fraction must be positive');
+    return bufferedUsd / bf;
+  }
+
+  /** Buffered USD notional for one token balance row. */
+  bufferedTokenUsd(tb: TokenBalance | null | undefined): number {
+    return this.bufferedUsd(this._rawTokenUsd(tb));
+  }
+
+  logStateSummary() {
+    console.log("===== state summary =====");
+    const aggregatedData = {
+      unusedBalances: this.unusedBalance.map((b) => ({
+        token: b.token.symbol,
+        amount: b.amount.toNumber(),
+      })),
+      walletBalance: this.walletBalance
+        ? {
+          token: this.walletBalance.token.symbol,
+          amount: this.walletBalance.amount.toNumber(),
+        }
+        : undefined,
+      vaultAssetBalance: this.vaultAssetBalance
+        ? {
+          token: this.vaultAssetBalance.token.symbol,
+          amount: this.vaultAssetBalance.amount.toNumber(),
+        }
+        : undefined,
+      vaultUsdcBalance: this.vaultUsdcBalance
+        ? {
+          token: this.vaultUsdcBalance.token.symbol,
+          amount: this.vaultUsdcBalance.amount.toNumber(),
+        }
+        : undefined,
+      vesuPoolStates: this.vesuPoolStates.map((p) => ({
+        poolId: p.poolId,
+        collateralAmount: p.collateralAmount.toNumber(),
+        debtAmount: p.debtAmount.toNumber(),
+      })),
+      vesuBorrowCapacity: this.vesuBorrowCapacity,
+      vesuRebalance: this.shouldVesuRebalance,
+      vesuPerPoolDebtDeltasToBorrow: this.vesuPerPoolDebtDeltasToBorrow.map((d) => d.toNumber()),
+      extendedBalance: this.extendedBalance?.balance.toNumber(),
+      extendedEquity: this.extendedBalance?.equity.toNumber(),
+      extendedAvailableForTrade: this.extendedBalance?.availableForTrade.toNumber(),
+      extendedAvailableForWithdrawal: this.extendedBalance?.availableForWithdrawal.toNumber(),
+      extendedUnrealisedPnl: this.extendedBalance?.unrealisedPnl.toNumber(),
+      extendedPendingDeposit: this.extendedBalance?.pendingDeposit.toNumber(),
+      extendedPositions: this.extendedPositions.map((p) => ({
+        instrument: p.instrument,
+        size: p.size.toNumber(),
+        valueUsd: p.valueUsd.toNumber(),
+      })),
+    }
+    // unused balances
+    console.log(
+      "unused balances",
+      aggregatedData.unusedBalances
+        .map((b) => `${b.token}=${b.amount}`)
+        .join(", "),
+    );
+    console.log(
+      "wallet balance",
+      aggregatedData.walletBalance
+        ? `${aggregatedData.walletBalance.token}=${aggregatedData.walletBalance.amount}`
+        : undefined,
+    );
+    console.log(
+      "vault asset balance",
+      aggregatedData.vaultAssetBalance
+        ? `${aggregatedData.vaultAssetBalance.token}=${aggregatedData.vaultAssetBalance.amount}`
+        : undefined,
+    );
+    console.log(
+      "vault usdc balance",
+      aggregatedData.vaultUsdcBalance
+        ? `${aggregatedData.vaultUsdcBalance.token}=${aggregatedData.vaultUsdcBalance.amount}`
+        : undefined,
+    );
+
+    // vesu info
+    console.log(
+      "vesu pool states",
+      aggregatedData.vesuPoolStates
+        .map(
+          (p) =>
+            `${p.poolId.shortString()}=${p.collateralAmount} ${p.debtAmount}`,
+        )
+        .join(", "),
+    );
+    console.log("vesu borrow capacity", aggregatedData.vesuBorrowCapacity);
+    console.log(
+      "vesu rebalance",
+      aggregatedData.vesuRebalance.map(String).join(", "),
+    );
+    console.log("vesu per pool debt deltas to borrow", aggregatedData.vesuPerPoolDebtDeltasToBorrow.join(", "));
+    // extended info
+    console.log("extended balance", aggregatedData.extendedBalance);
+    console.log("extended equity", aggregatedData.extendedEquity);
+    console.log("extended available for trade", aggregatedData.extendedAvailableForTrade);
+    console.log("extended available for withdrawal", aggregatedData.extendedAvailableForWithdrawal);
+    console.log("extended unrealised pnl", aggregatedData.extendedUnrealisedPnl);
+    console.log("extended pending deposit", aggregatedData.extendedPendingDeposit);
+    console.log(
+      "extended positions",
+      aggregatedData.extendedPositions
+        .map(
+          (p) => `${p.instrument}=${p.size} ${p.valueUsd}`,
+        )
+        .join(", "),
+    );
+
+    return aggregatedData
+  }
+
+  /**
+   * Initialise derived views for a solve cycle. Mutates only when pending
+   * withdrawal from Extended is in transit (credits wallet raw balance).
+   */
+  initBudget(): void {
+    const pendingDeposit = this.extendedBalance?.pendingDeposit?.toNumber() ?? 0;
+    if (pendingDeposit < 0) {
+      const inTransit = Math.abs(pendingDeposit);
+      if (this.walletBalance) {
+        this._addUsdToTokenBalance(this.walletBalance, inTransit);
+      }
+      logger.debug(`SolveBudget::initBudget pendingDeposit=${pendingDeposit} -> increased wallet raw USD by ${inTransit}`);
+    }
+
+    this._recomputeUnusedBalance();
+  }
+
+  /**
+   * Apply a safety buffer to all liquid balances (VA, wallet, extended trade/withdraw/upnl,
+   * unused balances). Call after withdrawal classification but before LTV/deposit classifiers
+   * so that withdrawal uses full raw amounts while subsequent classifiers see buffered values.
+   */
+  applyBuffer(factor: number): void {
+    if (factor <= 0 || factor >= 1) return;
+    const mult = 1 - factor;
+
+    const scaleTokenBalance = (tb: TokenBalance | null) => {
+      if (!tb) return;
+      const newAmount = tb.amount.multipliedBy(mult);
+      tb.amount = new Web3Number(newAmount.toFixed(tb.token.decimals), tb.token.decimals);
+      tb.usdValue = tb.usdValue * mult;
+    };
+
+    scaleTokenBalance(this.vaultAssetBalance);
+    scaleTokenBalance(this.vaultUsdcBalance);
+    scaleTokenBalance(this.walletBalance);
+    for (const ub of this.unusedBalance) {
+      scaleTokenBalance(ub);
+    }
+
+    if (this.extendedBalance) {
+      this.extendedBalance.availableForTrade = this.extendedBalance.availableForTrade.multipliedBy(mult);
+      this.extendedBalance.availableForWithdrawal = this.extendedBalance.availableForWithdrawal.multipliedBy(mult);
+      this.extendedBalance.unrealisedPnl = this.extendedBalance.unrealisedPnl.multipliedBy(mult);
+    }
+
+    this._recomputeUnusedBalance();
+  }
+
+  get vesuPoolState(): VesuPoolState {
+    assert(this.vesuPoolStates.length === 1, 'SolveBudget::vesuPoolState: vesuPoolStates length must be 1');
+    return this.vesuPoolStates[0];
+  }
+
+  // ── Derived getters (buffered where applicable) ─────────────────────
+
+  /** Buffered VA USD: non-stable asset slot (if any) + USDC slot. */
+  get vaUsd(): number {
+    // return this.bufferedTokenUsd(this.vaultAssetBalance) + this.bufferedTokenUsd(this.vaultUsdcBalance);
+    return this.bufferedTokenUsd(this.vaultUsdcBalance); // we dont have swap routes and is not correct, to consider asset balance directlyt in strategy
+  }
+
+  /** Buffered USD in VA strategy-asset bucket only. */
+  get vaAssetUsd(): number {
+    return this.bufferedTokenUsd(this.vaultAssetBalance);
+  }
+
+  /** Buffered USD in VA USDC bucket (includes full VA idle when asset === USDC). */
+  get vaUsdcUsd(): number {
+    return this.bufferedTokenUsd(this.vaultUsdcBalance);
+  }
+
+  get walletUsd(): number {
+    return this.bufferedUsd(this._rawTokenUsd(this.walletBalance));
+  }
+
+  get vaWalletUsd(): number {
+    // va buffered + wallet raw
+    return this.vaUsd + this.walletUsd;
+  }
+
+  get extAvailWithdraw(): number {
+    const raw = this.extendedBalance?.availableForWithdrawal?.toNumber() ?? 0;
+    return this.bufferedUsd(raw);
+  }
+
+  get extAvailUpnl(): number {
+    const raw = this.extendedBalance?.unrealisedPnl?.toNumber() ?? 0;
+    return this.bufferedUsd(raw);
+  }
+
+  /**
+   * Buffered Extended available-for-trade plus positive {@link ExtendedBalanceState.pendingDeposit}
+   * (deposit in transit is usable the same way as the pre-buffer implementation).
+   */
+  get extAvailTrade(): number {
+    const raw = this.extendedBalance?.availableForTrade?.toNumber() ?? 0;
+    let v = this.bufferedUsd(raw);
+    const pd = this.extendedBalance?.pendingDeposit?.toNumber() ?? 0;
+    if (pd > 0) v += pd;
+    return v;
+  }
+
+  get extPendingDeposit(): number {
+    return this.extendedBalance?.pendingDeposit?.toNumber() ?? 0;
+  }
+
+  /**
+   * Aggregate positive per-pool borrow headroom (USD). Repay/borrow routes update
+   * {@link vesuPerPoolDebtDeltasToBorrow}; no separate counter.
+   */
+  get vesuBorrowCapacity(): number {
+    return this.vesuPerPoolDebtDeltasToBorrow.reduce(
+      (a, d) => a + Math.max(0, d.toNumber()),
+      0,
+    );
+  }
+
+  /** Diagnostic: buffered idle + positive debt delta + buffered Extended afT + in-flight deposit. */
+  get totalUnused(): number {
+    const debtSum = this.vesuPerPoolDebtDeltasToBorrow.reduce((a, b) => a + b.toNumber(), 0);
+    let u = this.unusedBalance.reduce((a, b) => a + this.bufferedTokenUsd(b), 0);
+    if (debtSum > 0) u += debtSum;
+    const rawAft = this.extendedBalance?.availableForTrade?.toNumber() ?? 0;
+    const aftBuf = this.bufferedUsd(rawAft);
+    if (aftBuf > 0) u += aftBuf;
+    const pd = this.extendedBalance?.pendingDeposit?.toNumber() ?? 0;
+    if (pd > 0) u += pd;
+    return u;
+  }
+
+  /** Sum of buffered USD across merged unused-balance rows (VA + wallet). */
+  get unusedBalancesBufferedUsdSum(): number {
+    return this.unusedBalance.reduce((a, b) => a + this.bufferedTokenUsd(b), 0);
+  }
+
+  /** Read-only snapshot view for validation / logging. */
+  get unusedBalanceRows(): readonly TokenBalance[] {
+    return this.unusedBalance;
+  }
+
+  /** Read-only Vesu pool view for solve computations. */
+  get vesuPools(): readonly VesuPoolState[] {
+    return this.vesuPoolStates;
+  }
+
+  /** Read-only Extended positions view for solve computations. */
+  get extendedPositionsView(): readonly ExtendedPositionState[] {
+    return this.extendedPositions;
+  }
+
+  /** Read-only Extended balance view for diagnostics / margin checks. */
+  get extendedBalanceView(): ExtendedBalanceState | null {
+    return this.extendedBalance;
+  }
+
+  /** Current debt deltas per pool (positive=borrow, negative=repay). */
+  get vesuDebtDeltas(): readonly Web3Number[] {
+    return this.vesuPerPoolDebtDeltasToBorrow;
+  }
+
+  /** Per-pool rebalance flags derived from target HF checks. */
+  get vesuRebalanceFlags(): readonly boolean[] {
+    return this.shouldVesuRebalance;
+  }
+
+  /** Raw USD in VA (USDC slot + non-stable asset slot when distinct); spend caps when executing transfers. */
+  private _vaRawUsd(): number {
+    // return this._rawTokenUsd(this.vaultUsdcBalance) + this._rawTokenUsd(this.vaultAssetBalance);
+    return this._rawTokenUsd(this.vaultUsdcBalance); // we dont have swap routes and is not correct, to consider asset balance directlyt in strategy
+  }
+
+  /** VA liquidity usable for repay / {@link spendVaRawUsd} (matches nominal balances after any {@link applyBuffer} scaling). */
+  get vaRawUsd(): number {
+    return this._vaRawUsd();
+  }
+
+  private _walletRawUsd(): number {
+    return this._rawTokenUsd(this.walletBalance);
+  }
+
+  // ── Token snapshot helpers (keep vault / wallet / unusedBalance aligned) ─
+
+  /** Remove up to `usd` notional from a token balance, scaling token amount proportionally. */
+  private _deductUsdFromTokenBalance(tb: TokenBalance, usd: number): void {
+    if (usd <= 0) return;
+    const take = Math.min(usd, tb.usdValue);
+    if (take <= 0) return;
+    const oldUsd = tb.usdValue;
+    const newUsd = Math.max(0, oldUsd - take);
+    tb.usdValue = newUsd;
+    if (oldUsd <= 0) return;
+    const ratio = newUsd / oldUsd;
+    tb.amount = new Web3Number(
+      (tb.amount.toNumber() * ratio).toFixed(tb.token.decimals),
+      tb.token.decimals,
+    );
+  }
+
+  /** Add USD notional; infers price from current amount/usd when possible, else 1:1. */
+  private _addUsdToTokenBalance(tb: TokenBalance, usd: number): void {
+    if (usd <= 0) return;
+    const amtNum = tb.amount.toNumber();
+    const price =
+      amtNum > 0 && tb.usdValue > 0 ? tb.usdValue / amtNum : 1;
+    const deltaTok = usd / price;
+    tb.usdValue += usd;
+    tb.amount = tb.amount.plus(
+      new Web3Number(deltaTok.toFixed(tb.token.decimals), tb.token.decimals),
+    );
+  }
+
+  /**
+   * Rebuilds {@link unusedBalance} from vault + wallet snapshots (same merge as refresh).
+   */
+  private _recomputeUnusedBalance(): void {
+    const balanceMap = new Map<string, TokenBalance>();
+
+    const merge = (b: TokenBalance | null) => {
+      if (!b) return;
+      const key = b.token.address.toString();
+      const row: TokenBalance = {
+        token: b.token,
+        amount: new Web3Number(b.amount.toFixed(b.token.decimals), b.token.decimals),
+        usdValue: b.usdValue,
+      };
+      const existing = balanceMap.get(key);
+      if (existing) {
+        existing.amount = new Web3Number(
+          existing.amount.plus(row.amount).toFixed(existing.token.decimals),
+          existing.token.decimals,
+        );
+        existing.usdValue += row.usdValue;
+      } else {
+        balanceMap.set(key, row);
+      }
+    };
+
+    merge(this.vaultAssetBalance);
+    merge(this.vaultUsdcBalance);
+    merge(this.walletBalance);
+
+    this.unusedBalance = Array.from(balanceMap.values());
+  }
+
+  // ── Spend methods (return amount consumed, auto-decrement totalUnused) ─
+
+  /**
+   * Spend VA **raw** USD (up to {@link vaRawUsd}). Prefer {@link vaultUsdcBalance} when present, then {@link vaultAssetBalance}.
+   */
+  spendVA(rawDesired: number): number {
+    const capRaw = this._vaRawUsd();
+    const usedRaw = Math.min(capRaw, Math.max(0, rawDesired));
+    if (usedRaw <= CASE_THRESHOLD_USD) return 0;
+    let rem = usedRaw;
+    if (rem > 0 && this.vaultUsdcBalance && this.vaultUsdcBalance.usdValue > 0) {
+      const fromUsdc = Math.min(rem, this.vaultUsdcBalance.usdValue);
+      this._deductUsdFromTokenBalance(this.vaultUsdcBalance, fromUsdc);
+      rem -= fromUsdc;
+    }
+    if (rem > 0 && this.vaultAssetBalance) {
+      // this._deductUsdFromTokenBalance(this.vaultAssetBalance, rem);
+      throw new Error(`Not implemented: spendVA with vaultAssetBalance`);
+    }
+    this._recomputeUnusedBalance();
+    logger.debug(`SolveBudget::spendVA usedRaw=${usedRaw}, vaUsd=${this.vaUsd}, totalUnused=${this.totalUnused}`);
+    return usedRaw;
+  }
+
+  /**
+   * Spend nominal/raw USD from VA (e.g. Vesu repay, on-chain USDC). Does not apply the safety buffer to the cap.
+   */
+  spendVaRawUsd(rawUsdDesired: number): number {
+    const capRaw =
+      // this._rawTokenUsd(this.vaultUsdcBalance) + this._rawTokenUsd(this.vaultAssetBalance);
+      this._rawTokenUsd(this.vaultUsdcBalance); // we dont have swap routes and is not correct, to consider asset balance directlyt in strategy
+    const usedRaw = Math.min(capRaw, Math.max(0, rawUsdDesired));
+    if (usedRaw <= CASE_THRESHOLD_USD) return 0;
+    let rem = usedRaw;
+    if (rem > 0 && this.vaultUsdcBalance && this.vaultUsdcBalance.usdValue > 0) {
+      const fromUsdc = Math.min(rem, this.vaultUsdcBalance.usdValue);
+      this._deductUsdFromTokenBalance(this.vaultUsdcBalance, fromUsdc);
+      rem -= fromUsdc;
+    }
+    if (rem > 0 && this.vaultAssetBalance) {
+      // this._deductUsdFromTokenBalance(this.vaultAssetBalance, rem);
+      throw new Error(`Not implemented: spendVaRawUsd with vaultAssetBalance`);
+    }
+    this._recomputeUnusedBalance();
+    logger.debug(`SolveBudget::spendVaRawUsd usedRaw=${usedRaw}, vaUsd=${this.vaUsd}, totalUnused=${this.totalUnused}`);
+    return usedRaw;
+  }
+
+  /**
+   * Add **raw nominal USD** to VA (borrow proceeds, wallet→VA in raw USDC, etc.).
+   */
+  addToVA(rawUsd: number): void {
+    assert(rawUsd >= 0, 'SolveBudget::addToVA amount must be positive');
+    if (rawUsd === 0) return;
+    if (this.vaultUsdcBalance) {
+      this._addUsdToTokenBalance(this.vaultUsdcBalance, rawUsd);
+    } else if (this.vaultAssetBalance) {
+      // this._addUsdToTokenBalance(this.vaultAssetBalance, rawUsd);
+      throw new Error(`Not implemented: addToVA with vaultAssetBalance`);
+    }
+    this._recomputeUnusedBalance();
+    logger.debug(`SolveBudget::addToVA rawUsd=${rawUsd}, vaUsd=${this.vaUsd}, totalUnused=${this.totalUnused}`);
+  }
+
+  spendWallet(rawDesired: number): number {
+    const capRaw = this._walletRawUsd();
+    const usedRaw = Math.min(capRaw, Math.max(0, rawDesired));
+    if (usedRaw <= CASE_THRESHOLD_USD) return 0;
+    if (this.walletBalance) {
+      this._deductUsdFromTokenBalance(this.walletBalance, usedRaw);
+    }
+    this._recomputeUnusedBalance();
+    logger.debug(`SolveBudget::spendWallet usedRaw=${usedRaw}, walletUsd=${this.walletUsd}, totalUnused=${this.totalUnused}`);
+    return usedRaw;
+  }
+
+  /** Add **raw nominal USD** to the operator wallet balance (e.g. Extended→wallet withdrawal). */
+  addToWallet(rawUsd: number): void {
+    assert(rawUsd >= 0, 'SolveBudget::addToWallet amount must be positive');
+    if (rawUsd === 0) return;
+    if (this.walletBalance) {
+      this._addUsdToTokenBalance(this.walletBalance, rawUsd);
+    }
+    this._recomputeUnusedBalance();
+    logger.debug(`SolveBudget::addToWallet rawUsd=${rawUsd}, walletUsd=${this.walletUsd}, totalUnused=${this.totalUnused}`);
+  }
+
+  spendVAWallet(rawDesired: number): number {
+    let remaining = Math.max(0, rawDesired);
+    const vaSpent = this.spendVA(remaining);
+    remaining -= vaSpent;
+    const walletSpent = this.spendWallet(remaining);
+    return vaSpent + walletSpent;
+  }
+
+  private _updateExtAvailWithdraw(desiredRaw: number, isSpend: boolean): number {
+    assert(desiredRaw > 0, 'SolveBudget::_updateExtAvailWithdraw amount must be positive');
+    let rawDelta: number;
+    if (isSpend) {
+      const capRaw = this.extendedBalance?.availableForWithdrawal?.toNumber() ?? 0;
+      const useRaw = Math.min(capRaw, desiredRaw);
+      if (useRaw <= 0) return 0;
+      rawDelta = -useRaw;
+    } else {
+      rawDelta = desiredRaw;
+    }
+
+    if (this.extendedBalance) {
+      this.extendedBalance.availableForWithdrawal = safeUsdcWeb3Number(this.extendedBalance.availableForWithdrawal.toNumber() + rawDelta);
+      this.extendedBalance.availableForTrade = safeUsdcWeb3Number(this.extendedBalance.availableForTrade.toNumber() + rawDelta);
+      this.extendedBalance.balance = safeUsdcWeb3Number(this.extendedBalance.balance.toNumber() + rawDelta);
+      this.extendedBalance.equity = safeUsdcWeb3Number(this.extendedBalance.equity.toNumber() + rawDelta);
+    }
+    logger.debug(`SolveBudget::updateExtAvailWithdraw rawDelta=${rawDelta}, extAvailWithdraw=${this.extAvailWithdraw}, totalUnused=${this.totalUnused}`);
+    return rawDelta;
+  }
+
+  private _updateExtAvailUpnl(desiredRaw: number, isSpend: boolean): number {
+    assert(desiredRaw > 0, 'SolveBudget::_updateExtAvailUpnl amount must be positive');
+    let rawDelta: number;
+    if (isSpend) {
+      const capRaw = this.extendedBalance?.unrealisedPnl?.toNumber() ?? 0;
+      const useRaw = Math.min(capRaw, desiredRaw);
+      if (useRaw <= 0) return 0;
+      rawDelta = -useRaw;
+    } else {
+      rawDelta = desiredRaw;
+    }
+
+    if (this.extendedBalance) {
+      this.extendedBalance.unrealisedPnl = safeUsdcWeb3Number(this.extendedBalance.unrealisedPnl.toNumber() + rawDelta);
+      this.extendedBalance.balance = safeUsdcWeb3Number(this.extendedBalance.balance.toNumber() + rawDelta);
+      this.extendedBalance.equity = safeUsdcWeb3Number(this.extendedBalance.equity.toNumber() + rawDelta);
+      this.extendedBalance.availableForTrade = safeUsdcWeb3Number(this.extendedBalance.availableForTrade.toNumber() + rawDelta);
+    }
+    logger.debug(`SolveBudget::updateExtAvailUpnl rawDelta=${rawDelta}, extAvailUpnl=${this.extAvailUpnl}, totalUnused=${this.totalUnused}`);
+    return rawDelta;
+  }
+
+  spendExtAvailTrade(rawDesired: number): number {
+    const usedWd = this._updateExtAvailWithdraw(rawDesired, true);
+    const tookWd = Math.abs(usedWd);
+    const rem = rawDesired - tookWd;
+    const usedUpnl = rem > 0 ? this._updateExtAvailUpnl(rem, true) : 0;
+    logger.debug(`SolveBudget::updateExtAvailTrade rawSum=${usedWd + usedUpnl}, extAvailTrade=${this.extAvailTrade}, totalUnused=${this.totalUnused}`);
+    return usedWd + usedUpnl;
+  }
+
+  // simply reduces available amounts, but maintains equity and balance.
+  spendExtAvailTradeToEquityOnly(rawDesired: number): number {
+    const used = this._updateExtAvailWithdraw(rawDesired, true);
+    const remaining = rawDesired - Math.abs(used);
+    const usedUpnl = remaining > 0 ? this._updateExtAvailUpnl(remaining, true) : 0;
+    if (this.extendedBalance) {
+      // add whats subtracted earlier to equity
+      const net = Math.abs(used) + Math.abs(usedUpnl);
+      if (net.toFixed(0) != rawDesired.toFixed(0)) {
+        throw new Error(`SolveBudget::spendExtAvailTradeToEquityOnly net=${net} != rawDesired=${rawDesired}`);
+      }
+      this.extendedBalance.equity = safeUsdcWeb3Number(this.extendedBalance.equity.toNumber() + net);
+      this.extendedBalance.balance = safeUsdcWeb3Number(this.extendedBalance.balance.toNumber() + net);
+    }
+    logger.debug(`SolveBudget::updateExtAvailTrade rawSum=${used + usedUpnl}, extAvailTrade=${this.extAvailTrade}, totalUnused=${this.totalUnused}`);
+    return used + usedUpnl;
+  }
+
+  spendExtAvailWithdraw(rawDesired: number): number {
+    return this._updateExtAvailWithdraw(rawDesired, true);
+  }
+
+  spendExtAvailUpnl(rawDesired: number): number {
+    return this._updateExtAvailUpnl(rawDesired, true);
+  }
+
+  /**
+   * Withdraw from Extended **withdrawal bucket only** to operator wallet (planning).
+   * Used when VA must be funded from Extended and withdraw should be exhausted before unrealised PnL.
+   */
+  spendAvailWithdrawToWallet(rawDesired: number): number {
+    const want = Math.max(0, rawDesired);
+    if (want <= CASE_THRESHOLD_USD) return 0;
+    const rawDelta = this._updateExtAvailWithdraw(want, true);
+    if (rawDelta === 0) return 0;
+    const used = -rawDelta;
+    this.addToWallet(used);
+    return used;
+  }
+
+  /**
+   * Required Extended equity (USD) for current open positions: total notional ÷ strategy leverage.
+   * Same basis as {@link ExtendedSVKVesuStateManager._classifyLtvExtended} margin check.
+   */
+  private _extendedMarginRequirementUsd(): number {
+    const lev = calculateExtendedLevergae();
+    if (lev <= 0 || this.extendedPositions.length === 0) return 0;
+    const totalPosUsd = this.extendedPositions.reduce(
+      (s, p) => s + p.valueUsd.toNumber(),
+      0,
+    );
+    return totalPosUsd / lev;
+  }
+
+  /** How much more equity is needed before deposits should increase withdraw / trade availability. */
+  private _extendedEquityShortfallUsd(): number {
+    if (!this.extendedBalance) return 0;
+    const req = this._extendedMarginRequirementUsd();
+    const eq = this.extendedBalance.equity.toNumber();
+    return Math.max(0, req - eq);
+  }
+
+  /**
+   * Credits a USDC inflow on Extended. Fills margin shortfall (balance+equity only) first;
+   * any remainder is credited across balance, equity, availableForWithdrawal, and availableForTrade.
+   */
+  addToExtAvailTrade(rawUsd: number): void {
+    assert(rawUsd >= 0, 'SolveBudget::addToExtAvailTrade amount must be non-negative');
+    if (rawUsd <= CASE_THRESHOLD_USD) return;
+    if (!this.extendedBalance) {
+      logger.warn('SolveBudget::addToExtAvailTrade skipped — no extendedBalance');
+      return;
+    }
+
+    const shortfall = this._extendedEquityShortfallUsd();
+    const toMargin = Math.min(rawUsd, shortfall);
+    const toLiquid = rawUsd - toMargin;
+
+    if (toMargin > CASE_THRESHOLD_USD) {
+      const b = this.extendedBalance.balance.toNumber();
+      const e = this.extendedBalance.equity.toNumber();
+      this.extendedBalance.balance = safeUsdcWeb3Number(b + toMargin);
+      this.extendedBalance.equity = safeUsdcWeb3Number(e + toMargin);
+      logger.debug(
+        `SolveBudget::addToExtAvailTrade margin-first rawUsd=${toMargin} ` +
+        `(shortfallBefore=${shortfall}, balance=${b + toMargin}, equity=${e + toMargin})`,
+      );
+    }
+
+    if (toLiquid > CASE_THRESHOLD_USD) {
+      this._updateExtAvailWithdraw(toLiquid, false);
+    }
+
+    logger.debug(
+      `SolveBudget::addToExtAvailTrade total rawUsd=${rawUsd} toLiquid=${toLiquid} ` +
+      `extAvailTrade=${this.extAvailTrade}, totalUnused=${this.totalUnused}`,
+    );
+  }
+
+  spendVesuBorrowCapacity(desired: number): { used: number, spendsByPool: Omit<VesuDebtRoute, 'priority' | 'type'>[] } {
+    const used = Math.min(this.vesuBorrowCapacity, Math.max(0, desired));
+
+    let spendsByPool: Omit<VesuDebtRoute, 'priority' | 'type'>[] = [];
+    // reduce the debt delta for the pool
+    for (let index = 0; index < this.vesuPerPoolDebtDeltasToBorrow.length; index++) {
+      const d = this.vesuPerPoolDebtDeltasToBorrow[index];
+      if (d.toNumber() <= CASE_THRESHOLD_USD) continue;
+      const borrowed = Math.min(d.toNumber(), used);
+      this.vesuPerPoolDebtDeltasToBorrow[index] = d.minus(safeUsdcWeb3Number(borrowed));
+      this.vesuPoolStates[index].debtAmount = safeUsdcWeb3Number(this.vesuPoolStates[index].debtAmount.toNumber() + borrowed);
+      this.vesuPoolStates[index].debtUsdValue = this.vesuPoolStates[index].debtAmount.toNumber() * this.vesuPoolStates[index].debtPrice;
+      spendsByPool.push({ poolId: this.vesuPoolStates[index].poolId, amount: safeUsdcWeb3Number(borrowed), collateralToken: this.vesuPoolStates[index].collateralToken, debtToken: this.vesuPoolStates[index].debtToken });
+    }
+
+    logger.debug(`SolveBudget::spendVesuBorrowCapacity used=${used}, vesuBorrowCapacity=${this.vesuBorrowCapacity}, totalUnused=${this.totalUnused}`);
+    return { used, spendsByPool };
+  }
+
+  repayVesuBorrowCapacity(desired: number): { used: number, spendsByPool: Omit<VesuDebtRoute, 'priority' | 'type'>[] } {
+    assert(desired > 0, 'SolveBudget::repayVesuBorrowCapacity desired must be positive');
+    const used = desired;
+
+    const spendsByPool: Omit<VesuDebtRoute, 'priority' | 'type'>[] = [];
+    for (let index = 0; index < this.vesuPerPoolDebtDeltasToBorrow.length; index++) {
+      const d = this.vesuPerPoolDebtDeltasToBorrow[index];
+      if (d.toNumber() >= -CASE_THRESHOLD_USD) continue; // positive means, dont repay
+      const repaid = Math.min(Math.abs(d.toNumber()), used);
+      this.vesuPerPoolDebtDeltasToBorrow[index] = d.plus(safeUsdcWeb3Number(repaid));
+      this.vesuPoolStates[index].debtAmount = safeUsdcWeb3Number(this.vesuPoolStates[index].debtAmount.toNumber() - repaid);
+      spendsByPool.push({ poolId: this.vesuPoolStates[index].poolId, amount: safeUsdcWeb3Number(-repaid), collateralToken: this.vesuPoolStates[index].collateralToken, debtToken: this.vesuPoolStates[index].debtToken });
+    }
+
+    logger.debug(`SolveBudget::repayVesuBorrowCapacity used=${used}, vesuBorrowCapacity=${this.vesuBorrowCapacity}, totalUnused=${this.totalUnused}`);
+    return { used, spendsByPool };
+  }
+
+  // ── State mutation ──────────────────────────────────────────────────
+
+  /** Update a Vesu pool's collateral and debt after a lever / borrow / repay route. */
+  applyVesuDelta(poolId: ContractAddr, collToken: TokenInfo, debtToken: TokenInfo, collDelta: Web3Number, debtDelta: Web3Number): void {
+    const pool = this.vesuPoolStates.find(
+      (p) => p.poolId.toString() === poolId.toString() && p.collateralToken.symbol === collToken.symbol && p.debtToken.symbol === debtToken.symbol,
+    );
+    if (!pool) throw new Error(`SolveBudget::applyVesuDelta pool not found: poolId=${poolId.toString()}, collToken=${collToken.symbol}, debtToken=${debtToken.symbol}`);
+    pool.collateralAmount = new Web3Number(
+      pool.collateralAmount.plus(collDelta).toFixed(pool.collateralToken.decimals),
+      pool.collateralToken.decimals,
+    );
+    pool.collateralUsdValue = pool.collateralAmount.toNumber() * pool.collateralPrice;
+    pool.debtAmount = new Web3Number(
+      pool.debtAmount.plus(debtDelta).toFixed(pool.debtToken.decimals),
+      pool.debtToken.decimals,
+    );
+    pool.debtUsdValue = pool.debtAmount.toNumber() * pool.debtPrice;
+
+    // recompute per pool deltas here
+    const vesuPerPoolDebtDeltasToBorrow = this._computeperPoolDebtDeltasToBorrow();
+    this.vesuPerPoolDebtDeltasToBorrow = vesuPerPoolDebtDeltasToBorrow.map((item) => item.deltaDebt);
+    this.shouldVesuRebalance = vesuPerPoolDebtDeltasToBorrow.map((item) => item.shouldRebalance);
+  }
+
+  /**
+   * Update Extended position size after a lever route; sync {@link ExtendedPositionState.valueUsd}
+   * and margin buckets (released USD on decrease, locked USD on increase).
+   *
+   * @param collateralPriceUsd BTC collateral price for notional / margin math; if omitted, uses
+   *        existing valueUsd / |size| or the first Vesu pool collateral price.
+   */
+  applyExtendedExposureDelta(
+    instrument: string,
+    sizeDelta: Web3Number,
+    collateralPriceUsd?: number,
+  ): void {
+    const btcEps = 10 ** -COLLATERAL_PRECISION;
+    const lev = calculateExtendedLevergae();
+
+    let pos = this.extendedPositions.find((p) => p.instrument === instrument);
+    const oldAbs = pos ? Math.abs(pos.size.toNumber()) : 0;
+    const oldValUsd = pos ? pos.valueUsd.toNumber() : 0;
+
+    if (pos) {
+      pos.size = new Web3Number(pos.size.plus(sizeDelta).toFixed(8), 8);
+    } else if (sizeDelta.toNumber() !== 0) {
+      this.extendedPositions.push({
+        instrument,
+        side: 'SHORT',
+        size: sizeDelta,
+        valueUsd: new Web3Number(0, USDC_TOKEN_DECIMALS),
+        leverage: '0',
+      });
+      pos = this.extendedPositions[this.extendedPositions.length - 1];
+    } else {
+      return;
+    }
+
+    const newAbs = Math.abs(pos.size.toNumber());
+    let price = collateralPriceUsd;
+    if (price === undefined || price <= 0) {
+      price = oldAbs > btcEps ? oldValUsd / oldAbs : (this.vesuPoolStates[0]?.collateralPrice ?? 0);
+    }
+
+    if (price > 0) {
+      pos.valueUsd = new Web3Number(
+        (newAbs * price).toFixed(USDC_TOKEN_DECIMALS),
+        USDC_TOKEN_DECIMALS,
+      );
+    }
+
+    if (!this.extendedBalance || lev <= 0 || price <= 0) return;
+
+    const dAbs = newAbs - oldAbs;
+    if (dAbs < -btcEps) {
+      const releasedUsd = (-dAbs) * price / lev;
+      if (releasedUsd > CASE_THRESHOLD_USD) {
+        this.addToExtAvailTrade(releasedUsd);
+      }
+    } else if (dAbs > btcEps) {
+      const lockedUsd = dAbs * price / lev;
+      if (lockedUsd > CASE_THRESHOLD_USD) {
+        this._lockExtendedMarginUsd(lockedUsd);
+      }
+    }
+  }
+
+  /** Pull margin for larger Extended exposure from liquid buckets, then balance/equity. */
+  private _lockExtendedMarginUsd(lockedUsd: number): void {
+    if (lockedUsd <= CASE_THRESHOLD_USD || !this.extendedBalance) return;
+    let rem = lockedUsd;
+
+    const uw = Math.min(rem, Math.max(0, this.extendedBalance.availableForWithdrawal.toNumber()));
+    if (uw > 0) {
+      this._updateExtAvailWithdraw(uw, true);
+      rem -= uw;
+    }
+    if (rem > 0) {
+      const uu = Math.min(rem, Math.max(0, this.extendedBalance.unrealisedPnl.toNumber()));
+      if (uu > 0) {
+        this._updateExtAvailUpnl(uu, true);
+        rem -= uu;
+      }
+    }
+    if (rem > 0) {
+      const b = this.extendedBalance.balance.toNumber();
+      const e = this.extendedBalance.equity.toNumber();
+      this.extendedBalance.balance = safeUsdcWeb3Number(b - rem);
+      this.extendedBalance.equity = safeUsdcWeb3Number(e - rem);
+    }
+  }
+
+
+  /**
+   * For each Vesu pool, computes the debt delta needed to bring the position
+   * back to the target health factor.
+   *
+   * Positive = can borrow more, negative = need to repay.
+   */
+  private _computeperPoolDebtDeltasToBorrow(): { deltaDebt: Web3Number, shouldRebalance: boolean }[] {
+    const output = this.vesuPoolStates.map((pool) =>
+      calculateDeltaDebtAmount(
+        pool.collateralAmount,
+        pool.debtAmount,
+        pool.debtPrice,
+        pool.collateralPrice,
+      ),
+    );
+
+    // assert al pools share same collateral and debt tokens
+    const collateralToken = this.vesuPoolStates[0].collateralToken;
+    const debtToken = this.vesuPoolStates[0].debtToken;
+    for (const pool of this.vesuPoolStates) {
+      if (pool.collateralToken.symbol !== collateralToken.symbol || pool.debtToken.symbol !== debtToken.symbol) {
+        // not yet handled in code with multiple pool types. will be handled in future.
+        throw new Error(`SolveBudget::_computeperPoolDebtDeltasToBorrow: All pools must share same collateral and debt tokens`);
+      }
+    }
+    return output;
+  }
+}
+
+export function createSolveBudgetFromRawState(params: {
+  assetToken: TokenInfo;
+  usdcToken: TokenInfo;
+  unusedBalance: TokenBalance[];
+  walletBalance: TokenBalance | null;
+  vaultAssetBalance: TokenBalance | null;
+  vaultUsdcBalance: TokenBalance | null;
+  extendedPositions: ExtendedPositionState[];
+  extendedBalance: ExtendedBalanceState | null;
+  vesuPoolStates: VesuPoolState[];
+  limitBalanceBufferFactor?: number;
+}): SolveBudget {
+  const budget = new SolveBudget({
+    assetToken: params.assetToken,
+    usdcToken: params.usdcToken,
+    unusedBalance: params.unusedBalance,
+    walletBalance: params.walletBalance,
+    vaultAssetBalance: params.vaultAssetBalance,
+    vaultUsdcBalance: params.vaultUsdcBalance,
+    extendedPositions: params.extendedPositions,
+    extendedBalance: params.extendedBalance,
+    vesuPoolStates: params.vesuPoolStates,
+  });
+  if (params.limitBalanceBufferFactor && params.limitBalanceBufferFactor > 0) {
+    budget.applyBuffer(params.limitBalanceBufferFactor);
+  }
+  return budget;
+}
+
+// ─── State Manager ─────────────────────────────────────────────────────────────
+
+/**
+ * Reads all on-chain / off-chain state for the Extended + SVK + Vesu strategy,
+ * then solves for the optimal rebalancing deltas.
+ *
+ * Usage:
+ *   const manager = new ExtendedSVKVesuStateManager(config);
+ *   const result  = await manager.solve();
+ */
+export class ExtendedSVKVesuStateManager {
+  private readonly _config: StateManagerConfig;
+  private readonly _tag = "ExtendedSVKVesuStateManager";
+
+  /** Single mutable state holder — initialised by _refresh(), budget by initBudget(). */
+  private _budget!: SolveBudget;
+
+  constructor(config: StateManagerConfig) {
+    this._config = config;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Public API
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Main entry point. Refreshes all state, then computes and returns
+   * the optimal deltas for rebalancing the strategy.
+   *
+   * @param withdrawAmount — amount (in vault asset, e.g. USDC) the user wants
+   *   to withdraw. When > 0 the solver shrinks protocol allocations so that the
+   *   vault allocator ends up with enough balance to execute bringLiquidity.
+   *   Pass 0 (default) for normal investment / rebalancing cycles.
+   */
+  async solve(
+    withdrawAmount: Web3Number = new Web3Number(0, USDC_TOKEN_DECIMALS),
+  ): Promise<SolveResult | null> {
+    await this._refresh();
+    if (Math.abs(this._budget.extPendingDeposit) > 0) {
+      logger.warn(`${this._tag}::solve extPendingDeposit=${this._budget.extPendingDeposit}`);
+      return null;
+    }
+    this._validateRefreshedState();
+
+    // // Step 1: For each Vesu pool, compute debt delta needed for LTV maintenance
+    // const perPoolDebtDeltasToBorrow = this._computeperPoolDebtDeltasToBorrow();
+
+    // // Step 2: Determine distributable capital after debt and withdrawal adjustments
+    // const distributableAmount = this._computeDistributableAmount(
+    //   perPoolDebtDeltasToBorrow,
+    //   withdrawAmount,
+    // );
+
+    // // Step 3: Split distributable capital between Vesu and Extended allocations
+    // const { vesuAllocationUsd, extendedAllocationUsd } =
+    //   this._computeAllocationSplit(distributableAmount, perPoolDebtDeltasToBorrow);
+
+    // // Step 4: Convert Vesu allocation to per-pool collateral deltas
+    // const vesuDeltas =
+    //   this._computePerPoolCollateralDeltas(vesuAllocationUsd, perPoolDebtDeltasToBorrow);
+
+    // // Step 5: Compute Extended position deltas for delta-neutral matching
+    // const extendedPositionDeltas =
+    //   this._computeExtendedPositionDeltas(vesuDeltas);
+    // console.log({ extendedPositionDeltas: extendedPositionDeltas.map((delta) => ({
+    //   instrument: delta.instrument,
+    //   delta: delta.delta.toNumber(),
+    // })) });
+
+    // // Step 6: Compute net deposit/withdrawal change for Extended platform
+    // const extendedDeposit =
+    //   this._computeExtendedDepositDelta(extendedAllocationUsd);
+    // console.log({ extendedDeposit: extendedDeposit.toNumber() });
+
+    // // Step 7: compute vesu deposit amount (i.e. collateral required to open position may be)
+    // const vesuDepositAmount =
+    //   this._computeVesuDepositAmount(vesuDeltas);
+
+    // // Step 7: Compute bringLiquidity amount (= withdrawAmount for the vault)
+    // const bringLiquidityAmount =
+    //   this._computeBringLiquidityAmount(withdrawAmount);
+    // console.log({ bringLiquidityAmount: bringLiquidityAmount.toNumber() });
+
+    // Step 8: Classify state into actionable cases — each case carries
+    //   its own routes with amounts and state info.
+    const cases = this._classifyCases(withdrawAmount);
+
+    const result: SolveResult = {
+      cases,
+      // ignore these fields for now. only cases are relevant.
+      extendedDeposit: safeUsdcWeb3Number(0),
+      extendedPositionDeltas: [],
+      vesuDepositAmount: safeUsdcWeb3Number(0),
+      vesuDeltas: [],
+      vesuAllocationUsd: safeUsdcWeb3Number(0),
+      extendedAllocationUsd: safeUsdcWeb3Number(0),
+      bringLiquidityAmount: safeUsdcWeb3Number(0),
+      pendingDeposit: safeUsdcWeb3Number(0),
+    };
+
+    this._logSolveResult(result);
+    return result;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — state refresh
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Reads all on-chain and off-chain state in parallel and stores
+   * results in private instance variables.
+   */
+  private async _refresh(): Promise<void> {
+    logger.info(`${this._tag}::_refresh starting`);
+
+    const [
+      vaultAssetBalance,
+      vaultUsdcBalance,
+      walletBalance,
+      vesuPoolStates,
+      extendedBalance,
+      extendedPositions,
+    ] = await Promise.all([
+      this._fetchVaultAllocatorAssetBalance(),
+      this._fetchVaultAllocatorUsdcBalanceIfDistinct(),
+      this._fetchWalletBalances(),
+      this._fetchAllVesuPoolStates(),
+      this._fetchExtendedBalance(),
+      this._fetchExtendedPositions(),
+    ]);
+
+    logger.verbose(
+      `${this._tag}::_refresh ` +
+      `${vaultAssetBalance ? `VA asset ${vaultAssetBalance.token.symbol}=$${vaultAssetBalance.usdValue.toFixed(2)}, ` : ""}` +
+      `VA USDC=${vaultUsdcBalance.usdValue.toFixed(2)}` +
+      `, wallet=${walletBalance.usdValue}`,
+    );
+    const unusedBalance = this._computeUnusedBalances(
+      vaultAssetBalance,
+      vaultUsdcBalance,
+      walletBalance,
+    );
+
+    this._budget = createSolveBudgetFromRawState({
+      assetToken: this._config.assetToken,
+      usdcToken: this._config.usdcToken,
+      unusedBalance,
+      walletBalance,
+      vaultAssetBalance,
+      vaultUsdcBalance,
+      extendedPositions,
+      extendedBalance: {
+        availableForTrade:
+          extendedBalance?.availableForTrade ||
+          new Web3Number(0, USDC_TOKEN_DECIMALS),
+        availableForWithdrawal:
+          extendedBalance?.availableForWithdrawal ||
+          new Web3Number(0, USDC_TOKEN_DECIMALS),
+        unrealisedPnl:
+          extendedBalance?.unrealisedPnl ||
+          new Web3Number(0, USDC_TOKEN_DECIMALS),
+        balance:
+          extendedBalance?.balance || new Web3Number(0, USDC_TOKEN_DECIMALS),
+        equity:
+          extendedBalance?.equity || new Web3Number(0, USDC_TOKEN_DECIMALS),
+        pendingDeposit:
+          extendedBalance?.pendingDeposit ||
+          new Web3Number(0, USDC_TOKEN_DECIMALS),
+      },
+      vesuPoolStates,
+    });
+    this._budget.logStateSummary();
+
+    const totalUnusedUsd = unusedBalance.reduce(
+      (acc, b) => acc + b.usdValue,
+      0,
+    );
+    logger.info(
+      `${this._tag}::_refresh completed — ` +
+      `unusedBalances: ${unusedBalance.length} tokens [${unusedBalance.map((b) => `${b.token.symbol}=$${b.usdValue.toFixed(2)}`).join(', ')}], ` +
+      `totalUnusedUsd: ${totalUnusedUsd.toFixed(2)}, ` +
+      `extendedPositions: ${extendedPositions.length} [${extendedPositions.map((p) => `${p.instrument}=${p.size.toFixed(6)} ${p.side}, ${p.valueUsd.toFixed(6)} ${p.instrument}`).join(', ')}], ` +
+      `vesuPools: ${vesuPoolStates.length} [${vesuPoolStates.map((p) => `${p.poolId.shortString()}=${p.debtAmount.toFixed(6)} ${p.debtToken.symbol}, ${p.collateralAmount.toFixed(6)} ${p.collateralToken.symbol}`).join(', ')}], ` +
+      `availableForTrade: ${extendedBalance?.availableForTrade.toNumber()} - ` +
+      `availableForWithdrawal: ${extendedBalance?.availableForWithdrawal.toNumber()} - ` +
+      `unrealisedPnl: ${extendedBalance?.unrealisedPnl.toNumber()} - ` +
+      `extendedBalance::balance: ${extendedBalance?.balance.toNumber()} - ` +
+      `extendedBalance::pendingDeposit: ${extendedBalance?.pendingDeposit.toNumber()} - ` +
+      `extendedBalance::equity: ${extendedBalance?.equity.toNumber()}`,
+    );
+  }
+
+  // todo add communication check with python server of extended. if not working, throw error in solve function.
+
+  /** True when strategy asset and USDC share one token — VA idle balance is tracked as USDC, not as asset. */
+  private _vaultAssetAndUsdcAreSameToken(): boolean {
+    return this._config.assetToken.address.eq(this._config.usdcToken.address);
+  }
+
+  /**
+   * Reads idle {@link StateManagerConfig.assetToken} in the vault allocator when it differs from USDC.
+   * When asset and USDC are the same token, returns null (that balance is reported via {@link _fetchVaultAllocatorUsdcBalanceIfDistinct} only).
+   */
+  private async _fetchVaultAllocatorAssetBalance(): Promise<TokenBalance | null> {
+    if (this._vaultAssetAndUsdcAreSameToken()) {
+      return null;
+    }
+    const { assetToken, vaultAllocator, networkConfig, pricer } = this._config;
+    const balance = await new ERC20(networkConfig).balanceOf(
+      assetToken.address,
+      vaultAllocator,
+      assetToken.decimals,
+    );
+    const price = await pricer.getPrice(assetToken.symbol);
+    const usdValue =
+      Number(balance.toFixed(assetToken.decimals)) * price.price;
+
+    return { token: assetToken, amount: balance, usdValue };
+  }
+
+  /**
+   * Reads {@link StateManagerConfig.usdcToken} idle in the vault allocator (always — distinct asset or USDC-as-asset).
+   */
+  private async _fetchVaultAllocatorUsdcBalanceIfDistinct(): Promise<TokenBalance> {
+    const { usdcToken, vaultAllocator, networkConfig, pricer } = this._config;
+    const balance = await new ERC20(networkConfig).balanceOf(
+      usdcToken.address,
+      vaultAllocator,
+      usdcToken.decimals,
+    );
+    const tokenPrice = await pricer.getPrice(
+      usdcToken.priceProxySymbol || usdcToken.symbol,
+    );
+    const usdValue =
+      Number(balance.toFixed(usdcToken.decimals)) * tokenPrice.price;
+
+    return { token: usdcToken, amount: balance, usdValue };
+  }
+
+  /**
+   * Merges vault-allocator asset (if any), vault-allocator USDC, and operator wallet
+   * balances into entries keyed by token address.
+   */
+  private _computeUnusedBalances(
+    vaultAssetBalance: TokenBalance | null,
+    vaultUsdcBalance: TokenBalance,
+    walletBalance: TokenBalance,
+  ): TokenBalance[] {
+    const balanceMap = new Map<string, TokenBalance>();
+
+    const put = (tb: TokenBalance) => {
+      balanceMap.set(tb.token.address.toString(), {
+        token: tb.token,
+        amount: tb.amount,
+        usdValue: tb.usdValue,
+      });
+    };
+
+    if (vaultAssetBalance) put(vaultAssetBalance);
+    put(vaultUsdcBalance);
+
+    // Merge wallet balances by token address
+    const key = walletBalance.token.address.toString();
+    const existing = balanceMap.get(key);
+    if (existing) {
+      existing.amount = new Web3Number(
+        existing.amount.plus(walletBalance.amount).toFixed(existing.token.decimals),
+        existing.token.decimals,
+      );
+      existing.usdValue += walletBalance.usdValue;
+    } else {
+      balanceMap.set(key, {
+        token: walletBalance.token,
+        amount: walletBalance.amount,
+        usdValue: walletBalance.usdValue,
+      });
+    }
+
+    return Array.from(balanceMap.values());
+  }
+
+  /**
+   * Reads the operator wallet balance for {@link StateManagerConfig.usdcToken} only
+   * (wallet stablecoin is always USDC, regardless of strategy {@link StateManagerConfig.assetToken}).
+   */
+  private async _fetchWalletBalances(): Promise<TokenBalance> {
+    const {
+      networkConfig,
+      pricer,
+      walletAddress,
+      usdcToken,
+    } = this._config;
+    const erc20 = new ERC20(networkConfig);
+
+    const [balance, tokenPrice] =
+      await Promise.all([
+        erc20.balanceOf(
+          usdcToken.address,
+          walletAddress,
+          usdcToken.decimals,
+        ),
+        pricer.getPrice(usdcToken.priceProxySymbol || usdcToken.symbol),
+      ]);
+
+    return {
+      token: usdcToken,
+      amount: balance,
+      usdValue:
+        Number(balance.toFixed(usdcToken.decimals)) * tokenPrice.price,
+    };
+  }
+
+  /**
+   * Reads the Extended exchange account-level balance (equity, available for
+   * trade/withdrawal, etc.). Returns null if the API call fails.
+   */
+  private async _fetchExtendedBalance(): Promise<ExtendedBalanceState | null> {
+    const [holdings, pendingDeposit] = await Promise.all([
+      this._config.extendedAdapter.getExtendedDepositAmount(),
+      this._fetchPendingDeposit(),
+    ]);
+    if (!holdings) return null;
+
+    return {
+      equity: new Web3Number(holdings.equity, USDC_TOKEN_DECIMALS),
+      availableForTrade: new Web3Number(
+        holdings.availableForTrade,
+        USDC_TOKEN_DECIMALS,
+      ),
+      availableForWithdrawal: new Web3Number(
+        holdings.availableForWithdrawal,
+        USDC_TOKEN_DECIMALS,
+      ),
+      unrealisedPnl: new Web3Number(holdings.unrealisedPnl, USDC_TOKEN_DECIMALS),
+      balance: new Web3Number(holdings.balance, USDC_TOKEN_DECIMALS),
+      pendingDeposit,
+    };
+  }
+
+  /**
+   * Computes the net pending deposit by subtracting pending withdrawals from
+   * pending deposits. Uses the Extended exchange asset operations API.
+   *
+   * Positive = deposit in transit (wallet → Extended).
+   * Negative = withdrawal in transit (Extended → wallet).
+   */
+  private async _fetchPendingDeposit(): Promise<Web3Number> {
+    try {
+      const client = this._config.extendedAdapter.client;
+      const [pendingDeposits, pendingWithdrawals] = await Promise.all([
+        client.getAssetOperations({
+          operationsType: [AssetOperationType.DEPOSIT],
+          operationsStatus: [AssetOperationStatus.IN_PROGRESS],
+        }),
+        client.getAssetOperations({
+          operationsType: [AssetOperationType.WITHDRAWAL],
+          operationsStatus: [AssetOperationStatus.IN_PROGRESS],
+        }),
+      ]);
+
+      const depositTotal = pendingDeposits.data.reduce(
+        (sum, op) => sum + parseFloat(op.amount || '0'), 0,
+      );
+      const withdrawTotal = pendingWithdrawals.data.reduce(
+        (sum, op) => sum + parseFloat(op.amount || '0'), 0,
+      );
+
+      const net = depositTotal - withdrawTotal;
+      logger.info(
+        `${this._tag}::_fetchPendingDeposit deposits=${depositTotal}, withdrawals=${withdrawTotal}, net=${net}`,
+      );
+      return new Web3Number(net.toFixed(USDC_TOKEN_DECIMALS), USDC_TOKEN_DECIMALS);
+    } catch (err) {
+      logger.error(`${this._tag}::_fetchPendingDeposit error: ${err}`);
+      return new Web3Number(0, USDC_TOKEN_DECIMALS);
+    }
+  }
+
+  /**
+   * Reads all open positions on the Extended exchange. Each position
+   * includes instrument, side, size, USD value, and leverage.
+   */
+  private async _fetchExtendedPositions(): Promise<ExtendedPositionState[]> {
+    const positions =
+      await this._config.extendedAdapter.getAllOpenPositions();
+    if (!positions) return [];
+
+    return positions.map((position) => ({
+      instrument: position.market,
+      side: position.side,
+      size: new Web3Number(position.size, USDC_TOKEN_DECIMALS), // though in different token terms, this wont matter from DEX perspective, hence 6decimals is ok
+      valueUsd: new Web3Number(position.value, USDC_TOKEN_DECIMALS),
+      leverage: position.leverage,
+    }));
+  }
+
+  /**
+   * Reads a single Vesu pool's position data: collateral amount/price,
+   * debt amount/price.
+   */
+  private async _fetchSingleVesuPoolState(
+    adapter: VesuMultiplyAdapter,
+  ): Promise<VesuPoolState> {
+    const assetPrices = await adapter._vesuAdapter.getAssetPrices();
+    return {
+      poolId: adapter.config.poolId,
+      collateralToken: adapter.config.collateral,
+      debtToken: adapter.config.debt,
+      collateralAmount: assetPrices.collateralTokenAmount,
+      collateralUsdValue: assetPrices.collateralUSDAmount,
+      debtAmount: assetPrices.debtTokenAmount,
+      debtUsdValue: assetPrices.debtUSDAmount,
+      collateralPrice: assetPrices.collateralPrice,
+      debtPrice: assetPrices.debtPrice,
+    };
+  }
+
+  /**
+   * Reads all Vesu pool states in parallel (one per configured adapter).
+   */
+  private async _fetchAllVesuPoolStates(): Promise<VesuPoolState[]> {
+    return Promise.all(
+      this._config.vesuAdapters.map((adapter) =>
+        this._fetchSingleVesuPoolState(adapter),
+      ),
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — validation
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Validates that all critical refreshed state is present and contains
+   * finite, sensible values. Throws on invalid state.
+   */
+  private _validateRefreshedState(): void {
+    if (this._budget.unusedBalanceRows.length === 0) {
+      throw new Error(
+        `${this._tag}: unusedBalance is empty after refresh`,
+      );
+    }
+    for (const balance of this._budget.unusedBalanceRows) {
+      this._validateTokenBalanceOrThrow(
+        balance,
+        `unusedBalance[${balance.token.symbol}]`,
+      );
+    }
+    this._validateVesuPoolPricesOrThrow();
+    this._validateExtendedBalanceOrThrow();
+  }
+
+  private _validateTokenBalanceOrThrow(
+    balance: TokenBalance | null,
+    label: string,
+  ): void {
+    if (!balance) {
+      throw new Error(`${this._tag}: ${label} is null after refresh`);
+    }
+    if (!Number.isFinite(balance.usdValue) || balance.usdValue < 0) {
+      throw new Error(
+        `${this._tag}: ${label} has invalid usdValue: ${balance.usdValue}`,
+      );
+    }
+  }
+
+  private _validateVesuPoolPricesOrThrow(): void {
+    for (const pool of this._budget.vesuPools) {
+      const poolLabel = pool.poolId.shortString();
+      this._assertPositiveFinite(
+        pool.collateralPrice,
+        `Vesu pool ${poolLabel} collateralPrice`,
+      );
+      this._assertPositiveFinite(
+        pool.debtPrice,
+        `Vesu pool ${poolLabel} debtPrice`,
+      );
+    }
+  }
+
+  private _validateExtendedBalanceOrThrow(): void {
+    if (!this._budget.extendedBalanceView) return; // null is acceptable; treated as zero
+
+    const { equity, availableForTrade } = this._budget.extendedBalanceView;
+    if (
+      !Number.isFinite(equity.toNumber()) ||
+      !Number.isFinite(availableForTrade.toNumber())
+    ) {
+      throw new Error(
+        `${this._tag}: Extended balance contains non-finite values — ` +
+        `equity: ${equity.toNumber()}, availableForTrade: ${availableForTrade.toNumber()}`,
+      );
+    }
+  }
+
+  private _assertPositiveFinite(value: number, label: string): void {
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new Error(
+        `${this._tag}: ${label} is invalid (${value}). Expected finite positive number.`,
+      );
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 1: per-pool debt deltas (LTV maintenance)
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 2: distributable amount
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Computes total distributable capital by combining idle vault balance
+   * and Extended available balance, then adjusting for aggregate debt
+   * delta and any pending withdrawal.
+   *
+   * When withdrawAmount > 0 the distributable pool shrinks, forcing the
+   * allocation split to produce smaller (or negative) allocations — which
+   * in turn causes protocol positions to unwind and free capital for the
+   * vault allocator to execute bringLiquidity.
+   */
+  private _computeDistributableAmount(
+    perPoolDebtDeltasToBorrow: readonly Web3Number[],
+    withdrawAmount: Web3Number,
+  ): Web3Number {
+    const totalInvestable = this._computeTotalInvestableAmount();
+    const aggregateDebtAdjustment = this._sumDebtDeltas(perPoolDebtDeltasToBorrow);
+    return new Web3Number(
+      totalInvestable
+        .plus(aggregateDebtAdjustment)
+        .minus(withdrawAmount)
+        .toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+  }
+
+  /**
+   * Total investable = vault allocator balance + Extended available-for-trade +
+   * buffered unrealised PnL, matching `deposit_cases_extended_vesu.xlsx`:
+   * `(VA + wallet + EXT_WITH_AVL + EXT_UPNL) * (1 − buffer)`.
+   * Positive {@link ExtendedBalanceState.pendingDeposit} stays on the afT leg only (see {@link SolveBudget.extAvailTrade}).
+   */
+  private _computeTotalInvestableAmount(): Web3Number {
+    const totalUnusedUsd = this._budget.unusedBalancesBufferedUsdSum;
+    logger.debug(
+      `${this._tag}::_computeTotalInvestableAmount unusedBalances=` +
+      `${JSON.stringify(this._budget.unusedBalanceRows.map((b) => ({ token: b.token.symbol, amount: b.amount.toNumber(), usdValue: b.usdValue })))}`,
+    );
+    const extBal = this._budget.extendedBalanceView;
+    const rawAft = extBal?.availableForWithdrawal?.toNumber() ?? 0;
+    const rawUpnl = extBal?.unrealisedPnl?.toNumber() ?? 0;
+    let extBuffered =
+      this._budget.bufferedUsd(rawAft) + this._budget.bufferedUsd(rawUpnl);
+    const pd = extBal?.pendingDeposit?.toNumber() ?? 0;
+    if (pd > 0) extBuffered += pd;
+    const extendedAvailable = new Web3Number(
+      extBuffered.toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+    logger.verbose(`_computeTotalInvestableAmount totalUnusedUsd: ${totalUnusedUsd}, extendedAvailable: ${extendedAvailable.toNumber()}`);
+    return new Web3Number(totalUnusedUsd.toFixed(USDC_TOKEN_DECIMALS), USDC_TOKEN_DECIMALS)
+      .plus(extendedAvailable)
+  }
+
+  private _sumDebtDeltas(deltas: readonly Web3Number[]): Web3Number {
+    return deltas.reduce(
+      (sum, delta) => sum.plus(delta),
+      new Web3Number(0, USDC_TOKEN_DECIMALS),
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 3: allocation split
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Splits distributable capital between Vesu and Extended using leverage
+   * ratios and existing exposure to match delta-neutral targets.
+   *
+   * Formula (from existing strategy):
+   *   ExtendedAlloc = (vL * distributable + vesuExposure - extendedExposure) / (vL + eL)
+   *   VesuAlloc     = distributable - ExtendedAlloc
+   */
+  private _computeAllocationSplit(distributableAmount: Web3Number, deltaVesuCollateral = 0, deltaExtendedCollateral = 0, isRecursive = false): {
+    vesuAllocationUsd: Web3Number;
+    extendedAllocationUsd: Web3Number;
+    vesuPositionDelta: number;
+    extendedPositionDelta: number;
+  } {
+    if (this._hasNoVesuAdapters()) {
+      throw new Error(`${this._tag}: No Vesu adapters found`);
+    }
+
+    const vesuLeverage = calculateVesuLeverage();
+    const extendedLeverage = calculateExtendedLevergae();
+    const denominator = vesuLeverage + extendedLeverage;
+
+    if (denominator === 0) {
+      throw new Error(`${this._tag}: Denominator is zero`);
+    }
+
+    // get long/short exposures on both sides
+    const collateralPrice = this._budget.vesuPools[0]?.collateralPrice ?? 0;
+    const totalVesuExposureUsd = this._totalVesuCollateralUsd().plus(new Web3Number((deltaVesuCollateral * collateralPrice).toFixed(6), USDC_TOKEN_DECIMALS));
+    const totalExtendedExposureUsd = this._totalExtendedExposureUsd().plus(new Web3Number((deltaExtendedCollateral * collateralPrice).toFixed(6), USDC_TOKEN_DECIMALS));
+
+    const numerator =
+      vesuLeverage * distributableAmount.toNumber() +
+      totalVesuExposureUsd.toNumber() -
+      totalExtendedExposureUsd.toNumber();
+
+    const extendedAllocationUsd = new Web3Number(
+      (numerator / denominator).toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+    let vesuAllocationUsd = new Web3Number(
+      distributableAmount
+        .minus(extendedAllocationUsd)
+        .toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+
+    // add debt repayments to vesu allocation (-1 to convert to repay amount)
+    // const perPoolDebtDeltasToBorrow = this._budget.vesuDebtDeltas;
+    // const debtDeltasSum = this._sumDebtDeltas(perPoolDebtDeltasToBorrow);
+    // if (debtDeltasSum.toNumber() > 0) {
+    // vesuAllocationUsd = vesuAllocationUsd.plus(this._sumDebtDeltas(perPoolDebtDeltasToBorrow).multipliedBy(-1));
+
+    let vesuPositionDelta = Number((new Web3Number((vesuAllocationUsd.toNumber() * (vesuLeverage) / collateralPrice).toFixed(6), 6)).toFixedRoundDown(COLLATERAL_PRECISION));
+    let extendedPositionDelta = Number((new Web3Number((extendedAllocationUsd.toNumber() * (extendedLeverage) / collateralPrice).toFixed(6), 6)).toFixedRoundDown(COLLATERAL_PRECISION));
+
+    // for the first call, reconsider the newly created position delta to actually recompute the allocation split
+    if (!isRecursive) {
+      return this._computeAllocationSplit(distributableAmount, vesuPositionDelta, extendedPositionDelta, true);
+    }
+
+    // subtract any deltas passed
+    // throw new Error(`${this._tag}: Recursive allocation vesuPositionDelta: ${vesuPositionDelta}, extendedPositionDelta: ${extendedPositionDelta}, vesuAllocationUsd: ${vesuAllocationUsd.toNumber()}, extendedAllocationUsd: ${extendedAllocationUsd.toNumber()}`);
+    return { vesuAllocationUsd, extendedAllocationUsd, vesuPositionDelta, extendedPositionDelta };
+  }
+
+  private _hasNoVesuAdapters(): boolean {
+    return this._config.vesuAdapters.length === 0;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 4: per-pool collateral deltas
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Distributes the total Vesu USD allocation across pools proportionally
+   * by existing collateral value, then converts each share to collateral
+   * token units.
+   */
+  private _computePerPoolCollateralDeltas(
+    vesuAllocationUsd: Web3Number
+  ): VesuPoolDelta[] {
+    const vesuLeverage = calculateVesuLeverage();
+
+    const availableVesuCollateralAllocationUsd = vesuAllocationUsd;
+    const postLeverageAllocationUsd = availableVesuCollateralAllocationUsd.multipliedBy(vesuLeverage);
+    const totalCollateralExisting = this._totalVesuCollateral();
+
+    return this._budget.vesuPools.map((pool, index) => {
+      const _postLeverageAllocation = postLeverageAllocationUsd.dividedBy(pool.collateralPrice);
+
+      const postLeverageAllocation = new Web3Number((
+        (
+          _postLeverageAllocation.plus(totalCollateralExisting)
+        ).toFixedRoundDown(COLLATERAL_PRECISION)
+      ), pool.collateralToken.decimals
+      ).minus(totalCollateralExisting);
+      const _poolCollateralDelta = this._computePoolCollateralShare(
+        pool,
+        totalCollateralExisting,
+        postLeverageAllocation,
+      );
+      const poolCollateralDelta = new Web3Number(
+        _poolCollateralDelta.toFixed(COLLATERAL_PRECISION),
+        pool.collateralToken.decimals,
+      );
+
+      // the excess collateral should come from debt.
+      const newDebt = (postLeverageAllocation.multipliedBy(pool.collateralPrice)).minus(availableVesuCollateralAllocationUsd).dividedBy(pool.debtPrice);
+      return {
+        poolId: pool.poolId,
+        collateralToken: pool.collateralToken,
+        debtToken: pool.debtToken,
+        debtDelta: newDebt,
+        collateralDelta: poolCollateralDelta,
+        collateralPrice: pool.collateralPrice,
+        debtPrice: pool.debtPrice,
+      };
+    });
+  }
+
+  /**
+   * Determines how much of the total Vesu allocation goes to a single pool.
+   * Single-pool or zero-total cases get the entire allocation.
+   * Multi-pool cases split proportionally by current collateral USD value.
+   */
+  private _computePoolCollateralShare(
+    pool: VesuPoolState,
+    totalCollateral: Web3Number,
+    totalVesuAllocation: Web3Number,
+  ): Web3Number {
+    const isSinglePoolOrZeroTotal =
+      this._budget.vesuPools.length === 1 ||
+      totalCollateral.toNumber() === 0;
+
+    if (isSinglePoolOrZeroTotal) return totalVesuAllocation;
+
+    const poolWeight = pool.collateralAmount.dividedBy(totalCollateral);
+
+    return new Web3Number(
+      totalVesuAllocation
+        .multipliedBy(poolWeight)
+        .toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 6: extended position deltas
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Computes per-position exposure deltas for delta neutrality.
+   * Target: total Extended short exposure = total projected Vesu collateral
+   * exposure (current + collateral deltas).
+   */
+  private _computeExtendedPositionDeltas(
+    vesuDeltas: VesuPoolDelta[],
+  ): ExtendedPositionDelta[] {
+    const targetExposure =
+      this._computeTargetExtendedExposure(vesuDeltas);
+    const currentExposure = this._totalExtendedExposure();
+    logger.debug(
+      `${this._tag}::_computeExtendedPositionDeltas targetExposure=${targetExposure.toNumber()}, currentExposure=${currentExposure.toNumber()}`,
+    );
+    const totalExposureDelta = new Web3Number(
+      targetExposure
+        .minus(currentExposure)
+        .toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+
+    if (this._hasNoExtendedPositions()) {
+      return this._singleInstrumentDelta(totalExposureDelta);
+    }
+
+    return this._distributeExposureDeltaAcrossPositions(totalExposureDelta);
+  }
+
+  /**
+   * Target Extended exposure = sum of (current collateral + collateralDelta)
+   * * price, across all Vesu pools.
+   */
+  private _computeTargetExtendedExposure(
+    vesuDeltas: VesuPoolDelta[],
+  ): Web3Number {
+    let totalExposureCollateral = new Web3Number(0, USDC_TOKEN_DECIMALS); // just some decimals is ok
+
+    for (let i = 0; i < this._budget.vesuPools.length; i++) {
+      const pool = this._budget.vesuPools[i];
+      const delta = vesuDeltas[i];
+      logger.debug(
+        `${this._tag}::_computeTargetExtendedExposure poolId=${pool.poolId.toString()}, collateralAmount=${pool.collateralAmount.toNumber()}, collateralDelta=${delta.collateralDelta.toNumber()}`,
+      );
+      const projectedCollateral = pool.collateralAmount.plus(
+        delta.collateralDelta,
+      );
+      totalExposureCollateral = totalExposureCollateral.plus(
+        projectedCollateral,
+      );
+    }
+
+    return new Web3Number(
+      totalExposureCollateral.toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+  }
+
+  private _hasNoExtendedPositions(): boolean {
+    return this._budget.extendedPositionsView.length === 0;
+  }
+
+  /**
+   * Creates a single-element delta array for the default instrument
+   * when no Extended positions currently exist.
+   */
+  private _singleInstrumentDelta(
+    delta: Web3Number,
+  ): ExtendedPositionDelta[] {
+    return [
+      {
+        instrument: this._config.extendedAdapter.config.extendedMarketName,
+        delta: new Web3Number(
+          delta.toFixedRoundDown(COLLATERAL_PRECISION),
+          USDC_TOKEN_DECIMALS,
+        ),
+      },
+    ];
+  }
+
+  /**
+   * Distributes a total exposure delta proportionally across existing
+   * positions by their current USD value share.
+   */
+  private _distributeExposureDeltaAcrossPositions(
+    totalDelta: Web3Number,
+  ): ExtendedPositionDelta[] {
+    const totalExposure = this._totalExtendedExposure();
+
+    return this._budget.extendedPositionsView.map((position) => {
+      const share = this._positionExposureShareFraction(
+        position,
+        totalExposure,
+      );
+      return {
+        instrument: position.instrument,
+        delta: new Web3Number(
+          totalDelta.multipliedBy(share).toFixedRoundDown(COLLATERAL_PRECISION),
+          USDC_TOKEN_DECIMALS,
+        ),
+      };
+    });
+  }
+
+  /**
+   * Returns the fraction (0–1) of total Extended exposure held by
+   * a single position. Returns 1 when there is only one position
+   * or when total exposure is zero.
+   */
+  private _positionExposureShareFraction(
+    position: ExtendedPositionState,
+    totalExposure: Web3Number,
+  ): number {
+    const isSingleOrZero =
+      totalExposure.toNumber() === 0 ||
+      this._budget.extendedPositionsView.length === 1;
+    if (isSingleOrZero) return 1;
+    return position.valueUsd.dividedBy(totalExposure).toNumber();
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 7: extended deposit delta
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Net deposit change = allocation target − currently available for trade.
+   * Positive = need to deposit more, negative = can withdraw excess.
+   */
+  private _computeExtendedDepositDelta(
+    extendedAllocationUsd: Web3Number,
+  ): Web3Number {
+    const currentAvailableForTrade = new Web3Number(
+      this._budget.extAvailTrade.toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+
+    return new Web3Number(
+      extendedAllocationUsd
+        .minus(currentAvailableForTrade)
+        .toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+  }
+
+  private _computeVesuDepositAmount(vesuDeltas: VesuPoolDelta[]): Web3Number {
+    let totalVesuCollateral = new Web3Number(0, USDC_TOKEN_DECIMALS); // just some decimals is ok
+    for (let i = 0; i < this._budget.vesuPools.length; i++) {
+      const pool = this._budget.vesuPools[i];
+      const delta = vesuDeltas[i];
+      totalVesuCollateral = totalVesuCollateral.plus(delta.collateralDelta.multipliedBy(pool.collateralPrice));
+      totalVesuCollateral = totalVesuCollateral.minus(delta.debtDelta.multipliedBy(pool.debtPrice));
+    }
+    return totalVesuCollateral;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 8: wallet delta
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * The wallet is a pass-through for USDC flows between the vault allocator
+   * and the Extended exchange.
+   *
+   * Positive = vault allocator → wallet → Extended (deposit)
+   * Negative = Extended → wallet → vault allocator (withdrawal)
+   */
+  private _deriveWalletDelta(extendedDeposit: Web3Number): Web3Number {
+    return extendedDeposit;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 9: bring liquidity
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * The bringLiquidity amount is the USDC that the vault allocator must
+   * transfer back to the vault contract for the user's withdrawal.
+   * Equals the withdrawAmount passed into solve(); 0 during investment cycles.
+   */
+  private _computeBringLiquidityAmount(
+    withdrawAmount: Web3Number,
+  ): Web3Number {
+    return withdrawAmount;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — case classification (modular)
+  //
+  // Cases are the source of truth. Each case carries its own routes
+  // with amounts and state info. There is no global routes array —
+  // consumers flatten case routes as needed.
+  // ═══════════════════════════════════════════════════════════════════════════
+
+
+  // ── ExecutionRoute-building helpers ─────────────────────────────────────────────
+
+  // ── Atomic route builders ────────────────────────────────────────────
+
+  private _buildVesuRepayRoutes(totalUsd: number, routes: ExecutionRoute[]): void {
+    // Repay consumes VA USDC/asset; do not plan more than the budget VA holds after prior
+    // routes (borrow→VA, Vesu→VA, wallet→VA, etc.). Otherwise repayVesuBorrowCapacity would
+    // mutate Vesu debt while spendVaRawUsd could not fund it.
+    const vaCap = this._budget.vaRawUsd;
+    const repayUsd = Math.min(totalUsd, vaCap);
+    if (repayUsd <= CASE_THRESHOLD_USD) return;
+
+    const { used, spendsByPool } = this._budget.repayVesuBorrowCapacity(repayUsd);
+    for (const route of spendsByPool) {
+      routes.push({ type: RouteType.VESU_REPAY as const, ...route, priority: routes.length });
+    }
+
+    this._budget.spendVaRawUsd(used);
+  }
+
+  private _buildVesuBorrowRoutes(
+    totalUsd: number,
+    routes: ExecutionRoute[],
+    opts?: { maxBorrowUsd?: number },
+  ): { routes: ExecutionRoute[], remaining: number } {
+    let borrowable = this._budget.vesuBorrowCapacity;
+    if (opts?.maxBorrowUsd !== undefined) {
+      borrowable = Math.min(borrowable, Math.max(0, opts.maxBorrowUsd));
+    }
+    if (totalUsd <= CASE_THRESHOLD_USD) return { routes, remaining: totalUsd };
+    if (borrowable <= CASE_THRESHOLD_USD) return { routes, remaining: totalUsd };
+
+    const borrowTarget = Math.min(totalUsd, borrowable);
+    const { used, spendsByPool } = this._budget.spendVesuBorrowCapacity(borrowTarget);
+    for (const route of spendsByPool) {
+      routes.push({ type: RouteType.VESU_BORROW as const, ...route, priority: routes.length });
+    }
+
+    this._budget.addToVA(used);
+    return { routes, remaining: totalUsd - used };
+  }
+
+  // private _buildExtendedDepositRoutes(totalUsd: number): TransferRoute[] {
+  //   const routes: TransferRoute[] = [];
+  //   let rem = totalUsd;
+  //   const walletBal = this._budget.walletBalance?.amount?.toNumber() ?? 0;
+  //   if (walletBal > 0 && rem > 0) {
+  //     const use = Math.min(walletBal, rem);
+  //     routes.push({ type: RouteType.WALLET_TO_EXTENDED, amount: safeUsdcWeb3Number(use), priority: routes.length });
+  //     this._budget.applyExtendedBalanceChange(use);
+  //     rem -= use;
+  //   }
+  //   if (rem > 0) {
+  //     routes.push({ type: RouteType.VA_TO_EXTENDED, amount: safeUsdcWeb3Number(rem), priority: routes.length });
+  //     this._budget.applyExtendedBalanceChange(rem);
+  //   }
+  //   return routes;
+  // }
+
+  // private _buildVesuIncreaseLeverRoutes(vesuDeltas: VesuPoolDelta[]): VesuMultiplyRoute[] {
+  //   return vesuDeltas
+  //     .filter((d) => d.collateralDelta.greaterThan(0))
+  //     .map((d) => {
+  //       this._budget.applyVesuDelta(d.poolId, d.collateralDelta, d.debtDelta);
+  //       return {
+  //         type: RouteType.VESU_MULTIPLY_INCREASE_LEVER as const,
+  //         poolId: d.poolId,
+  //         collateralToken: d.collateralToken,
+  //         collateralAmount: d.collateralDelta,
+  //         debtToken: d.debtToken,
+  //         debtAmount: d.debtDelta,
+  //         priority: 0,
+  //       };
+  //     });
+  // }
+
+  // private _buildVesuDecreaseLeverRoutes(vesuDeltas: Web3Number[]): VesuMultiplyRoute[] {
+  //   return vesuDeltas
+  //     .filter((d) => d.collateralDelta.isNegative())
+  //     .map((d) => {
+  //       this._budget.applyVesuDelta(d.poolId, d.collateralDelta, d.debtDelta);
+  //       return {
+  //         type: RouteType.VESU_MULTIPLY_DECREASE_LEVER as const,
+  //         poolId: d.poolId,
+  //         collateralToken: d.collateralToken,
+  //         collateralAmount: d.collateralDelta,
+  //         debtToken: d.debtToken,
+  //         debtAmount: d.debtDelta,
+  //         priority: 0,
+  //       };
+  //     });
+  // }
+
+  private _getWalletToVARoute(tryAmount: number, routes: ExecutionRoute[]): { routes: ExecutionRoute[], remaining: number } {
+    const usableRaw = Math.min(tryAmount, this._budget.walletUsd);
+    if (usableRaw > CASE_THRESHOLD_USD) {
+      const walletUsed = this._budget.spendWallet(usableRaw);
+      this._budget.addToVA(walletUsed);
+      const route: TransferRoute = { type: RouteType.WALLET_TO_VA, amount: safeUsdcWeb3Number(walletUsed), priority: routes.length };
+      routes.push(route);
+      return { routes, remaining: tryAmount - walletUsed };
+    }
+    return { routes, remaining: tryAmount };
+  }
+
+  private _getWalletToEXTENDEDRoute(tryAmount: number, routes: ExecutionRoute[], shouldAddWaitRoute = true): { routes: ExecutionRoute[], remaining: number } {
+    const usableRaw = Math.min(tryAmount, this._budget.walletUsd);
+    if (usableRaw > CASE_THRESHOLD_USD) {
+      const walletUsed = this._budget.spendWallet(usableRaw);
+      this._budget.addToExtAvailTrade(walletUsed);
+      routes.push({ type: RouteType.WALLET_TO_EXTENDED, amount: safeUsdcWeb3Number(walletUsed), priority: routes.length } as TransferRoute);
+
+      if (shouldAddWaitRoute) {
+        routes.push({ type: RouteType.RETURN_TO_WAIT, priority: routes.length });
+      }
+      return { routes, remaining: tryAmount - walletUsed };
+    }
+    return { routes, remaining: tryAmount };
+  }
+
+  private _getVAToEXTENDEDRoute(tryAmount: number, routes: ExecutionRoute[], shouldAddWaitRoute = true): { routes: ExecutionRoute[], remaining: number } {
+    const usable = Math.min(tryAmount, this._budget.vaUsdcUsd);
+    if (usable > CASE_THRESHOLD_USD) {
+      const vaUsed = this._budget.spendVA(usable);
+      this._budget.addToExtAvailTrade(vaUsed);
+
+      // add extended deposit route
+      const route: TransferRoute = { type: RouteType.VA_TO_EXTENDED, amount: safeUsdcWeb3Number(vaUsed), priority: routes.length };
+      routes.push(route);
+
+      // should follow up by a returning to wait route
+      if (shouldAddWaitRoute) {
+        routes.push({ type: RouteType.RETURN_TO_WAIT, priority: routes.length });
+      }
+      return { routes, remaining: tryAmount - vaUsed };
+    }
+    return { routes, remaining: tryAmount };
+  }
+
+  private _getExtendedToWalletRoute(tryAmount: number, routes: ExecutionRoute[], shouldAddWaitRoute = true): { routes: ExecutionRoute[], remaining: number } {
+    if (tryAmount <= CASE_THRESHOLD_USD) return { routes, remaining: tryAmount };
+    const rawCap = this._budget.extAvailWithdraw + Math.max(0, this._budget.extAvailUpnl);
+    const rawSpend = Math.min(tryAmount, rawCap);
+    if (rawSpend <= CASE_THRESHOLD_USD) return { routes, remaining: tryAmount };
+    const rawOut = this._budget.spendExtAvailTrade(rawSpend);
+    this._budget.addToWallet(Math.abs(rawOut));
+    const route: TransferRoute = { type: RouteType.EXTENDED_TO_WALLET, amount: safeUsdcWeb3Number(rawSpend), priority: routes.length };
+    routes.push(route);
+
+    if (shouldAddWaitRoute) {
+      routes.push({ type: RouteType.RETURN_TO_WAIT, priority: routes.length });
+    }
+    return { routes, remaining: tryAmount - rawSpend };
+  }
+
+  private _getWALLETToVARoute(tryAmount: number, routes: ExecutionRoute[]): { routes: ExecutionRoute[], remaining: number } {
+    if (tryAmount <= CASE_THRESHOLD_USD) return { routes, remaining: tryAmount };
+    const usableRaw = Math.min(tryAmount, this._budget.walletUsd);
+    if (usableRaw <= CASE_THRESHOLD_USD) return { routes, remaining: tryAmount };
+    const walletUsed = this._budget.spendWallet(usableRaw);
+    this._budget.addToVA(walletUsed);
+    const route: TransferRoute = { type: RouteType.WALLET_TO_VA, amount: safeUsdcWeb3Number(walletUsed), priority: routes.length };
+    routes.push(route);
+    return { routes, remaining: tryAmount - walletUsed };
+  }
+
+  private _getUpnlRoute(tryAmount: number, routes: ExecutionRoute[]): { routes: ExecutionRoute[], remaining: number } {
+    const rawUpnl = this._budget.extAvailUpnl;
+    const usableRaw = Math.min(tryAmount, rawUpnl);
+    if (usableRaw <= 0) return { routes, remaining: tryAmount };
+
+    // if fails, ensure there is a way to choose the positio to use to create realised pnl
+    // until then, only 1 position is supported
+    this._budget.spendExtAvailUpnl(usableRaw);
+    this._budget.addToExtAvailTrade(usableRaw);
+    assert(this._budget.extendedPositionsView.length == 1, 'SolveBudget::_getUpnlRoute: extendedPositions length must be 1');
+    routes.push({
+      type: RouteType.REALISE_PNL,
+      amount: safeUsdcWeb3Number(usableRaw),
+      instrument: this._budget.extendedPositionsView[0].instrument,
+      priority: routes.length,
+    } as RealisePnlRoute);
+    return { routes, remaining: tryAmount - usableRaw };
+  }
+
+  // ── Sub-classifiers ────────────────────────────────────────────────────
+  // Each sub-classifier builds routes directly from contextual data.
+
+  /**
+  * 1. Withdrawal — source funds in priority order:
+  *    1) VA balance  2) Wallet  3) Vesu borrow capacity
+  *    4) Extended available-for-withdrawal + unrealised PnL
+  *    5) Unwind positions on both sides (freed funds handled next cycle)
+  */
+  private _classifyWithdrawal(
+    withdrawAmount: Web3Number
+  ): SolveCaseEntry[] {
+    if (!withdrawAmount.greaterThan(CASE_THRESHOLD_USD)) return [];
+
+    const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+    const routes: ExecutionRoute[] = [];
+    let remaining = withdrawAmount.toNumber();
+
+    // ── Step 1: VA balance ────────────────────────────────────────────────
+    // VA funds are already in the vault allocator — no transfer route needed.
+    const vaUsed = this._budget.spendVA(remaining);
+    remaining -= vaUsed;
+
+    let totalExtUsed = 0;
+
+    // ── Step 2: Wallet balance → VA ──────────────────────────────────────
+    if (remaining > CASE_THRESHOLD_USD) {
+      const { remaining: walletToVaRemaining } = this._getWALLETToVARoute(remaining, routes);
+      remaining = walletToVaRemaining;
+    }
+
+    // ── Step 3: Borrow from Vesu (positive debt delta = borrowable) ──────
+    if (remaining > CASE_THRESHOLD_USD) {
+      const { remaining: borrowRemaining } = this._buildVesuBorrowRoutes(remaining, routes);
+      remaining = borrowRemaining;
+    }
+
+    // ── Step 4: Extended available-for-withdrawal, then unrealised PnL ───
+    if (remaining > CASE_THRESHOLD_USD) {
+      const usableWithrawAmount = Math.min(remaining, this._budget.extAvailWithdraw);
+      remaining -= usableWithrawAmount;
+
+      let upnlUsed = 0;
+      if (remaining > CASE_THRESHOLD_USD) {
+        const { remaining: upnlRemaining } = this._getUpnlRoute(remaining, routes);
+        upnlUsed = remaining - upnlRemaining;
+        remaining = upnlRemaining;
+      }
+
+      // keep track of total extended used
+      totalExtUsed = usableWithrawAmount + upnlUsed;
+    }
+
+    // ── Step 5: Unwind positions ────────────────────────────────────────
+    // Handle imbalance first (unwind from larger side), then equal unwind.
+    // VESU_MULTIPLY_DECREASE_LEVER handles the BTC→USDC swap internally.
+    if (remaining > CASE_THRESHOLD_USD) {
+      assert(this._budget.vesuPools.length == 1, 'SolveBudget::_classifyWithdrawal: vesuPoolStates length must be 1');
+      const vesuAdapter = this._config.vesuAdapters[0];
+      const avgCollPrice = this._budget.vesuPools[0]?.collateralPrice ?? 1;
+      const vesuLeverage = calculateVesuLeverage();
+      const extLeverage = calculateExtendedLevergae();
+      const freedPerBtcVesu = avgCollPrice / vesuLeverage;
+      const freedPerBtcExt = avgCollPrice / extLeverage;
+
+      const vesuColBtc = this._budget.vesuPools[0].collateralAmount.toNumber();
+      const extPosBtc = this._totalExtendedExposure().toNumber();
+      let stillNeeded = remaining;
+      let vesuBtcDelta = 0;
+      let extBtcDelta = 0;
+      let extFreed = 0;
+
+      const roundUpBtc = (x: number): number => {
+        const factor = 10 ** COLLATERAL_PRECISION;
+        return Math.ceil(x * factor) / factor;
+      };
+
+      // Step 5a: Handle imbalance
+      const diff = vesuColBtc - extPosBtc;
+      let currentVesuBtc = vesuColBtc;
+      let currentExtBtc = extPosBtc;
+
+      if (Math.abs(diff) > 1e-8) {
+        if (diff > 0) {
+          const btcRaw = stillNeeded / freedPerBtcVesu;
+          const btc = Math.min(roundUpBtc(Math.min(Math.abs(diff), btcRaw, currentVesuBtc)), currentVesuBtc);
+          vesuBtcDelta += btc;
+          stillNeeded -= btc * freedPerBtcVesu;
+          currentVesuBtc -= btc;
+        } else {
+          const btcRaw = stillNeeded / freedPerBtcExt;
+          const btc = Math.min(roundUpBtc(Math.min(Math.abs(diff), btcRaw, currentExtBtc)), currentExtBtc);
+          extBtcDelta += btc;
+          extFreed += btc * freedPerBtcExt;
+          stillNeeded -= btc * freedPerBtcExt;
+          currentExtBtc -= btc;
+        }
+      }
+
+      // todo rereviewe logic on how neg upnl gets handled
+      // esp when equity is below ideal margin, 0 ext withdraw,
+      // and how does closing free capital.
+
+      // Step 5b: Equal unwind from both sides
+      if (stillNeeded > CASE_THRESHOLD_USD) {
+        const combinedFreed = freedPerBtcVesu + freedPerBtcExt;
+        const maxBtc = Math.min(currentVesuBtc, currentExtBtc);
+        const btcRaw = stillNeeded / combinedFreed;
+        const btc = Math.min(roundUpBtc(Math.min(btcRaw, maxBtc)), maxBtc);
+        vesuBtcDelta += btc;
+        extBtcDelta += btc;
+        extFreed += btc * freedPerBtcExt;
+      }
+
+      const r6 = (n: number) => Number(n.toFixed(6));
+
+      // Emit VESU_MULTIPLY_DECREASE_LEVER (handles swap internally, freed funds go to VA)
+      if (vesuBtcDelta > 0) {
+        const totalVesuBtcSigned = -vesuBtcDelta;
+        const targetLtv = 1 - 1 / vesuLeverage; // vesuLeverage = 1/(1-ltv), so ltv = 1-1/lev
+        const debtDelta = r6(totalVesuBtcSigned * avgCollPrice * targetLtv);
+        // Same convention as LTV rebalance: no separate margin BTC; full Vesu reduction is the swap leg.
+        const marginBtc = 0;
+        const swappedBtc = Number(vesuBtcDelta.toFixed(COLLATERAL_PRECISION));
+
+        routes.push({
+          type: RouteType.VESU_MULTIPLY_DECREASE_LEVER,
+          poolId: vesuAdapter.config.poolId,
+          collateralToken: vesuAdapter.config.collateral,
+          marginAmount: new Web3Number(marginBtc.toFixed(COLLATERAL_PRECISION), vesuAdapter.config.collateral.decimals),
+          swappedCollateralAmount: new Web3Number(swappedBtc.toFixed(COLLATERAL_PRECISION), vesuAdapter.config.collateral.decimals),
+          debtToken: vesuAdapter.config.debt,
+          debtAmount: new Web3Number(debtDelta, USDC_TOKEN_DECIMALS),
+          priority: routes.length,
+        } as VesuMultiplyRoute);
+        this._budget.applyVesuDelta(
+          vesuAdapter.config.poolId, vesuAdapter.config.collateral, vesuAdapter.config.debt,
+          new Web3Number(r6(totalVesuBtcSigned), USDC_TOKEN_DECIMALS),
+          new Web3Number(debtDelta, USDC_TOKEN_DECIMALS),
+        );
+        this._budget.addToVA(vesuBtcDelta * freedPerBtcVesu);
+      }
+
+      // Emit EXTENDED_DECREASE_LEVER
+      if (extBtcDelta > 0) {
+        routes.push({
+          type: RouteType.EXTENDED_DECREASE_LEVER,
+          amount: safeUsdcWeb3Number(-r6(extBtcDelta)),
+          instrument,
+          priority: routes.length,
+        });
+        this._budget.applyExtendedExposureDelta(
+          instrument,
+          safeUsdcWeb3Number(-r6(extBtcDelta)),
+          avgCollPrice,
+        );
+        totalExtUsed += extFreed;
+      }
+    }
+
+    // Bridge extended funds to VA (availableForTrade → wallet → VA)
+    if (totalExtUsed > CASE_THRESHOLD_USD) {
+      this._getExtendedToWalletRoute(totalExtUsed, routes);
+      this._getWALLETToVARoute(totalExtUsed, routes);
+    }
+
+    // ── Bring liquidity for whatever was sourced in steps 1-4 ────────────
+    routes.push({
+      type: RouteType.BRING_LIQUIDITY,
+      amount: withdrawAmount,
+      priority: routes.length,
+    });
+    this._budget.spendVA(withdrawAmount.toNumber() - vaUsed);
+
+    routes.forEach((r, i) => { r.priority = i; });
+
+    return [{
+      case: CASE_DEFINITIONS[CaseId.WITHDRAWAL_SIMPLE],
+      additionalArgs: { amount: withdrawAmount },
+      routes,
+    }];
+  }
+
+  /**
+   * 2a. LTV Rebalance — Vesu side
+   *
+   * Triggered when vesuPerPoolDebtDeltasToBorrow sum is negative (high LTV, needs repayment).
+   * Sources funds to VA so the subsequent deposit classifier can build the correct lever routes.
+   *
+   * Priority: 1) VA + Wallet (no routes)  2) Extended available-for-withdrawal
+   *           3) Extended uPnL  4) Margin crisis (future)
+   *
+   * Design: accumulate all ext-to-wallet moves, add transfer routes at the end (principle #3).
+   */
+  /**
+   * Unified LTV / exposure classifier: `rebalance()` drives both LTV (debt, margin,
+   * funding) and Vesu↔Extended position alignment. There is no separate imbalance pass.
+   * Computes both Vesu repay and Extended margin needs,
+   * then builds all routes in a single pass with no duplicate transfers.
+   *
+   * Vesu repay priority: VA > Wallet > ExtAvl > ExtUpnl
+   * Extended margin priority: Wallet > VA > VesuBorrow
+   * Shared sources consumed by Vesu first (higher priority).
+   */
+  private _classifyLTV(): SolveCaseEntry[] {
+    assert(this._budget.vesuPools.length === 1, `${this._tag}::_classifyLTV expects exactly one Vesu pool`);
+    const d = rebalance(this._ltvRebalanceInputsFromBudget());
+    if (this._isLtvRebalanceNoop(d)) return [];
+
+    logger.info(
+      `${this._tag}::_classifyLTV deltas extPos=${d.dExtPosition} vesuPos=${d.dVesuPosition} `
+      + `vesuDebt=${d.dVesuDebt} va=${d.dVaUsd} wallet=${d.dWalletUsd} borrow=${d.dVesuBorrowCapacity} `
+      + `T=${d.dTransferVesuToExt}`,
+    );
+
+    const routes = this._buildLtvRoutesFromRebalanceDeltas(d);
+    if (routes.length === 0) return [];
+
+    const amountUsd =
+      Math.abs(d.dVaUsd)
+      + Math.abs(d.dWalletUsd)
+      + Math.abs(d.dVesuBorrowCapacity)
+      + Math.abs(d.dExtAvlWithdraw)
+      + Math.abs(d.dExtUpnl)
+      + Math.abs(d.dTransferVesuToExt);
+
+    routes.forEach((r, i) => { r.priority = i; });
+    return [{
+      case: CASE_DEFINITIONS[CaseId.MANAGE_LTV],
+      additionalArgs: { amount: safeUsdcWeb3Number(amountUsd) },
+      routes,
+    }];
+  }
+
+  private _ltvRebalanceInputsFromBudget() {
+    const pool = this._budget.vesuPools[0];
+    const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+    const extPosBtc = this._budget.extendedPositionsView
+      .filter(p => p.instrument === instrument)
+      .reduce((s, p) => s + Math.abs(p.size.toNumber()), 0);
+    const targetHF = VesuConfig.maxLtv / VesuConfig.targetLtv;
+
+    return {
+      ext: {
+        positionBtc: extPosBtc,
+        equity: this._budget.extendedBalanceView?.equity?.toNumber() ?? 0,
+        avlWithdraw: this._budget.extAvailWithdraw,
+        upnl: this._budget.extAvailUpnl,
+        leverage: calculateExtendedLevergae(),
+      },
+      vesu: {
+        positionBtc: pool.collateralAmount.toNumber(),
+        debt: pool.debtAmount.toNumber(),
+        debtPrice: pool.debtPrice,
+        maxLTV: VesuConfig.maxLtv,
+        targetHF,
+      },
+      btcPrice: pool.collateralPrice,
+      funding: {
+        vaUsd: this._budget.vaUsd,
+        walletUsd: this._budget.walletUsd,
+        vesuBorrowCapacity: this._budget.vesuBorrowCapacity,
+        extAvlWithdraw: this._budget.extAvailWithdraw,
+        extUpnl: this._budget.extAvailUpnl,
+      },
+      config: {
+        positionPrecision: COLLATERAL_PRECISION,
+        hfBuffer: 0.05,
+        minRoutableUsd: CASE_THRESHOLD_USD,
+      },
+    };
+  }
+
+  private _isLtvRebalanceNoop(d: RebalanceDeltas): boolean {
+    const btcEps = 10 ** -COLLATERAL_PRECISION;
+    const usdEps = CASE_THRESHOLD_USD;
+    return (
+      Math.abs(d.dExtPosition) < btcEps
+      && Math.abs(d.dVesuPosition) < btcEps
+      && Math.abs(d.dVesuDebt) < 1e-6
+      && Math.abs(d.dExtAvlWithdraw) < usdEps
+      && Math.abs(d.dExtUpnl) < usdEps
+      && Math.abs(d.dVaUsd) < usdEps
+      && Math.abs(d.dWalletUsd) < usdEps
+      && Math.abs(d.dVesuBorrowCapacity) < usdEps
+      && Math.abs(d.dTransferVesuToExt) < usdEps
+    );
+  }
+
+  /**
+   * Turn pure rebalance() deltas into execution routes.
+   * Order: Vesu multiply decrease → Extended decrease → aggregated transfers
+   * (REALISE_PNL, EXTENDED_TO_WALLET + WAIT, WALLET_TO_VA, VESU_BORROW, VESU_REPAY, VA_TO_EXTENDED),
+   * then Vesu multiply increase and Extended increase (need VA / Extended funded first).
+   */
+  private _buildLtvRoutesFromRebalanceDeltas(d: RebalanceDeltas): ExecutionRoute[] {
+    const routes: ExecutionRoute[] = [];
+    const pool = this._budget.vesuPools[0];
+    const vesuAdapter = this._config.vesuAdapters[0];
+    const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+    const price = pool.collateralPrice;
+    const debtPrice = pool.debtPrice;
+    const targetLtv = VesuConfig.targetLtv;
+    const btcEps = 10 ** -COLLATERAL_PRECISION;
+
+    let multiplyDebtRepayUsd = 0;
+
+    logger.info(`${this._tag}::_buildLtvRoutesFromRebalanceDeltas d=${JSON.stringify(d)}`);
+
+    // ── 1) Vesu multiply decrease (free collateral / repay) ─────────────
+    if (d.dVesuPosition < -btcEps) {
+      const xBtc = -d.dVesuPosition;
+      // When Vesu sends USD to Extended (dTransferVesuToExt > 0), part of the BTC cut must be the
+      // multiply "margin" leg so USDC lands in VA and can be routed VA_TO_EXTENDED (adapter uses sub_margin).
+      const transferUsdFromVesu = Math.max(0, d.dTransferVesuToExt);
+      let marginBtc = 0;
+      let swappedBtc = Number(xBtc.toFixed(COLLATERAL_PRECISION));
+      if (transferUsdFromVesu > CASE_THRESHOLD_USD && price > 0) {
+        const marginCapFromTransfer = transferUsdFromVesu / price;
+        marginBtc = Number(
+          Math.min(xBtc, marginCapFromTransfer).toFixed(COLLATERAL_PRECISION),
+        );
+        swappedBtc = Number((xBtc - marginBtc).toFixed(COLLATERAL_PRECISION));
+      }
+      // Swap leg repays at most (swapped BTC notional in USD); any extra debt reduction
+      // is a separate VESU_REPAY (see multiplyDebtRepayUsd / standaloneRepayUsd below).
+      const swapLegMaxRepayUsd = swappedBtc * price * debtPrice;
+      const debtUsdFallback = swappedBtc * price * targetLtv;
+      let debtTokenDelta: number;
+      if (d.dVesuDebt < 0) {
+        const needRepayUsd = -d.dVesuDebt * debtPrice;
+        const multiplyRepayUsd = Math.min(needRepayUsd, swapLegMaxRepayUsd);
+        logger.info(`${this._tag}::_buildLtvRoutesFromRebalanceDeltas ${JSON.stringify({
+          needRepayUsd,
+          multiplyRepayUsd,
+        })}`);
+        debtTokenDelta = -(multiplyRepayUsd / debtPrice);
+      } else {
+        debtTokenDelta = -debtUsdFallback;
+      }
+
+      const debtAmtW3 = new Web3Number(debtTokenDelta.toFixed(USDC_TOKEN_DECIMALS), USDC_TOKEN_DECIMALS);
+      multiplyDebtRepayUsd = Math.abs(debtTokenDelta) * debtPrice;
+      logger.info(`${this._tag}::_buildLtvRoutesFromRebalanceDeltas ${JSON.stringify({
+        debtTokenDelta,
+        debtUsdFallback,
+        swapLegMaxRepayUsd,
+        xBtc,
+        marginBtc,
+        swappedBtc,
+        transferUsdFromVesu,
+        debtPrice,
+        targetLtv,
+        multiplyDebtRepayUsd,
+      })}`);
+      routes.push({
+        type: RouteType.VESU_MULTIPLY_DECREASE_LEVER,
+        poolId: vesuAdapter.config.poolId,
+        collateralToken: vesuAdapter.config.collateral,
+        marginAmount: new Web3Number(marginBtc.toFixed(COLLATERAL_PRECISION), vesuAdapter.config.collateral.decimals),
+        swappedCollateralAmount: new Web3Number(swappedBtc.toFixed(COLLATERAL_PRECISION), vesuAdapter.config.collateral.decimals),
+        debtToken: vesuAdapter.config.debt,
+        debtAmount: debtAmtW3,
+        priority: routes.length,
+      } as VesuMultiplyRoute);
+      this._budget.applyVesuDelta(
+        vesuAdapter.config.poolId,
+        vesuAdapter.config.collateral,
+        vesuAdapter.config.debt,
+        new Web3Number((-xBtc).toFixed(COLLATERAL_PRECISION), vesuAdapter.config.collateral.decimals),
+        debtAmtW3,
+      );
+      if (transferUsdFromVesu > CASE_THRESHOLD_USD) {
+        this._budget.addToVA(transferUsdFromVesu);
+      }
+    }
+
+    // ── 2) Extended decrease lever only (increase after VA→Ext funding) ─
+    if (d.dExtPosition < -btcEps) {
+      const amt = new Web3Number(d.dExtPosition.toFixed(COLLATERAL_PRECISION), 8);
+      routes.push({
+        type: RouteType.EXTENDED_DECREASE_LEVER,
+        amount: amt,
+        instrument,
+        priority: routes.length,
+      } as ExtendedLeverRoute);
+      this._budget.applyExtendedExposureDelta(instrument, amt, price);
+    }
+
+    // ── 3) Aggregated transfers (no WALLET_TO_EXTENDED; Ext only via VA) ─
+    const negUpnl = Math.min(0, d.dExtUpnl);
+    const negExtAvl = Math.min(0, d.dExtAvlWithdraw);
+    let hadExtendedOut = false;
+
+    if (negUpnl < -CASE_THRESHOLD_USD) {
+      this._getUpnlRoute(Math.abs(negUpnl), routes);
+      hadExtendedOut = true;
+    }
+
+    const extToWalletUsd = (negExtAvl < -CASE_THRESHOLD_USD ? Math.abs(negExtAvl) : 0)
+      + (negUpnl < -CASE_THRESHOLD_USD ? Math.abs(negUpnl) : 0);
+    logger.info(`${this._tag}::_buildLtvRoutesFromRebalanceDeltas extToWalletUsd=${extToWalletUsd}, negExtAvl=${negExtAvl}, negUpnl=${negUpnl}`);
+    if (extToWalletUsd > CASE_THRESHOLD_USD) {
+      this._getExtendedToWalletRoute(extToWalletUsd, routes);
+      hadExtendedOut = true;
+    } else {
+      // too small to withdraw from extended
+      // reduce any vesu debt
+      // else further repay from va will fail
+      if (d.dVesuDebt < 0) {
+        d.dVesuDebt += (negExtAvl < 0 && negExtAvl > -CASE_THRESHOLD_USD ? Math.abs(negExtAvl) : 0)
+        + (negUpnl < 0 && negUpnl > -CASE_THRESHOLD_USD ? Math.abs(negUpnl) : 0);
+      }
+    }
+
+    logger.info(`${this._tag}::_buildLtvRoutesFromRebalanceDeltas d=${JSON.stringify(d)}`);
+
+    const walletPull = Math.abs(Math.min(0, d.dWalletUsd));
+    const walletToVaUsd = walletPull + extToWalletUsd;
+    if (walletToVaUsd > CASE_THRESHOLD_USD) {
+      this._getWALLETToVARoute(walletToVaUsd, routes);
+    }
+
+    if (d.dVesuBorrowCapacity < -CASE_THRESHOLD_USD) {
+      this._buildVesuBorrowRoutes(Math.abs(d.dVesuBorrowCapacity), routes);
+    }
+
+    const totalDebtRepayUsd = d.dVesuDebt < 0 ? -d.dVesuDebt * debtPrice : 0;
+    logger.info(`${this._tag}::_buildLtvRoutesFromRebalanceDeltas totalDebtRepayUsd=${totalDebtRepayUsd}`);
+    let standaloneRepayUsd = Math.max(0, totalDebtRepayUsd - multiplyDebtRepayUsd);
+    logger.info(`${this._tag}::_buildLtvRoutesFromRebalanceDeltas standaloneRepayUsd=${standaloneRepayUsd}`);
+    if (standaloneRepayUsd > this._budget.vaRawUsd) {
+      if (Math.abs(standaloneRepayUsd - this._budget.vaRawUsd) < CASE_THRESHOLD_USD) {
+        standaloneRepayUsd = this._budget.vaRawUsd;
+      } else {
+        throw new Error(`${this._tag}::_buildLtvRoutesFromRebalanceDeltas standaloneRepayUsd=${standaloneRepayUsd} > vaRawUsd=${this._budget.vaRawUsd}`);
+      }
+    }
+    if (standaloneRepayUsd > CASE_THRESHOLD_USD) {
+      this._buildVesuRepayRoutes(standaloneRepayUsd, routes);
+    }
+
+    const posExtEq = Math.max(0, d.dExtAvlWithdraw);
+    const vaToExtUsd = posExtEq > CASE_THRESHOLD_USD ? posExtEq : 0;
+    if (vaToExtUsd > CASE_THRESHOLD_USD) {
+      this._getVAToEXTENDEDRoute(vaToExtUsd, routes, hadExtendedOut);
+    }
+
+    // ── Vesu / Extended increase lever: require prior VA funding & VA→Extended where applicable
+    if (d.dVesuPosition > btcEps) {
+      const vesuDepositAmount = new Web3Number(
+        (d.dVesuPosition * price * (1 - targetLtv)).toFixed(USDC_TOKEN_DECIMALS),
+        USDC_TOKEN_DECIMALS,
+      );
+      if (vesuDepositAmount.toNumber() > CASE_THRESHOLD_USD) {
+        // routes.push({
+        //   type: RouteType.AVNU_DEPOSIT_SWAP,
+        //   priority: routes.length,
+        //   fromToken: vesuAdapter.config.collateral.symbol,
+        //   fromAmount: vesuDepositAmount,
+        //   toToken: vesuAdapter.config.debt.symbol,
+        // });
+      }
+      const collateralDelta = new Web3Number(
+        d.dVesuPosition.toFixed(COLLATERAL_PRECISION),
+        vesuAdapter.config.collateral.decimals,
+      );
+      const availableBorrowCapacity = this._budget.vesuBorrowCapacity;
+      const externalDepositAmount = vesuDepositAmount.minus(
+        new Web3Number(Math.min(availableBorrowCapacity, vesuDepositAmount.toNumber()).toFixed(USDC_TOKEN_DECIMALS), USDC_TOKEN_DECIMALS),
+      );
+      const collPx = pool.collateralPrice || 1;
+      const marginUsdAmount = externalDepositAmount.toNumber() * (pool.debtPrice ?? 1);
+      const swappedAmount = new Web3Number(
+        ((marginUsdAmount / collPx)).toFixed(6),
+        vesuAdapter.config.collateral.decimals,
+      );
+      const debtDeltaTokens = new Web3Number(
+        (d.dVesuDebt).toFixed(USDC_TOKEN_DECIMALS),
+        USDC_TOKEN_DECIMALS,
+      );
+      routes.push({
+        type: RouteType.VESU_MULTIPLY_INCREASE_LEVER,
+        priority: routes.length,
+        collateralToken: vesuAdapter.config.collateral,
+        debtToken: vesuAdapter.config.debt,
+        marginAmount: swappedAmount,
+        swappedCollateralAmount: collateralDelta.minus(swappedAmount),
+        debtAmount: debtDeltaTokens.plus(new Web3Number(Math.min(availableBorrowCapacity, vesuDepositAmount.toNumber()).toFixed(USDC_TOKEN_DECIMALS), USDC_TOKEN_DECIMALS)),
+        poolId: vesuAdapter.config.poolId,
+      } as VesuMultiplyRoute);
+      this._budget.applyVesuDelta(
+        vesuAdapter.config.poolId,
+        vesuAdapter.config.collateral,
+        vesuAdapter.config.debt,
+        collateralDelta,
+        debtDeltaTokens,
+      );
+      this._budget.spendVA(marginUsdAmount);
+    }
+    if (d.dExtPosition > btcEps) {
+      const amt = new Web3Number(d.dExtPosition.toFixed(COLLATERAL_PRECISION), 8);
+      routes.push({
+        type: RouteType.EXTENDED_INCREASE_LEVER,
+        amount: amt,
+        instrument,
+        priority: routes.length,
+      } as ExtendedLeverRoute);
+      this._budget.applyExtendedExposureDelta(instrument, amt, price);
+    }
+
+    return routes;
+  }
+
+  // ── LTV Vesu route builders ───────────────────────────────────────────
+
+  /**
+   * LTV_EXTENDED_PROFITABLE_AVAILABLE:
+   * Extended has enough available-to-withdraw → withdraw, move to VA, repay Vesu.
+   * Routes: [EXTENDED_TO_WALLET, WALLET_TO_VA, VESU_REPAY]
+   */
+  // private _buildLtvVesuRepayFromExtendedRoutes(amountUsd: number, vesuDeltas: Web3Number[]): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = [];
+  //   const amt = safeUsdcWeb3Number(amountUsd);
+
+  //   // Withdraw from Extended → operator wallet
+  //   routes.push({ type: RouteType.EXTENDED_TO_WALLET, amount: amt, priority: routes.length });
+  //   this._budget.applyExtendedBalanceChange(-amountUsd);
+
+  //   // Wait for Extended withdrawal to settle before using wallet funds
+  //   routes.push({ type: RouteType.RETURN_TO_WAIT, priority: routes.length });
+
+  //   // Operator wallet → VA
+  //   routes.push({ type: RouteType.WALLET_TO_VA, amount: amt, priority: routes.length });
+
+  //   // Repay Vesu debt from VA funds
+  //   routes.push(...this._buildVesuRepayRoutesss(amountUsd, vesuDeltas)); // wrong
+
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  /**
+   * LTV_EXTENDED_PROFITABLE_REALIZE:
+   * Extended has unrealised PnL → realise it first, then withdraw + repay.
+   * Routes: [REALISE_PNL, EXTENDED_TO_WALLET, WALLET_TO_VA, VESU_REPAY]
+   */
+  // private _buildLtvVesuRepayRealiseRoutes(amountUsd: number, availWithdrawUsd: number, vesuDeltas: Web3Number[]): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = [];
+  //   const amt = safeUsdcWeb3Number(amountUsd);
+  //   const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+  //   const upnlRequired = amountUsd - availWithdrawUsd;
+
+  //   // Realise PnL to make funds available for withdrawal
+  //   routes.push({ type: RouteType.REALISE_PNL, amount: safeUsdcWeb3Number(upnlRequired), instrument, priority: routes.length });
+
+  //   // Withdraw realised funds from Extended → operator wallet
+  //   routes.push({ type: RouteType.EXTENDED_TO_WALLET, amount: amt, priority: routes.length });
+  //   this._budget.applyExtendedBalanceChange(-amountUsd);
+
+  //   // Wait for Extended withdrawal to settle
+  //   routes.push({ type: RouteType.RETURN_TO_WAIT, priority: routes.length });
+
+  //   // Operator wallet → VA
+  //   routes.push({ type: RouteType.WALLET_TO_VA, amount: amt, priority: routes.length });
+
+  //   // Repay Vesu debt from VA funds
+  //   routes.push(...this._buildVesuRepayRoutesss(amountUsd, vesuDeltas)); // wrong
+
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  /**
+   * MARGIN_CRISIS_VESU:
+   * Neither VA/Wallet nor Extended withdrawal covers the shortfall.
+   * Temporarily increase Extended leverage to free margin, withdraw to VA, then
+   * decrease Vesu lever to bring LTV back in range.
+   * Routes: [CRISIS_INCREASE_EXTENDED_MAX_LEVERAGE, EXTENDED_TO_WALLET, WALLET_TO_VA,
+   *          VESU_MULTIPLY_DECREASE_LEVER, EXTENDED_DECREASE_LEVER, CRISIS_UNDO_EXTENDED_MAX_LEVERAGE]
+   */
+  // private _buildMarginCrisisVesuRoutes(neededUsd: number, vesuDeltas: Web3Number[]): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = [];
+  //   const amt = safeUsdcWeb3Number(neededUsd);
+  //   const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+
+  //   // Temporarily boost Extended leverage to free margin
+  //   routes.push({ type: RouteType.CRISIS_INCREASE_EXTENDED_MAX_LEVERAGE, priority: routes.length });
+
+  //   // Withdraw freed margin from Extended → wallet
+  //   routes.push({ type: RouteType.EXTENDED_TO_WALLET, amount: amt, priority: routes.length });
+  //   this._budget.applyExtendedBalanceChange(-neededUsd);
+
+  //   // Wallet → VA
+  //   routes.push({ type: RouteType.WALLET_TO_VA, amount: amt, priority: routes.length });
+
+  //   // Decrease Vesu leverage to reduce LTV
+  //   // todo to verify if this is correct.
+  //   routes.push(...this._buildVesuDecreaseLeverRoutes(vesuDeltas));
+
+  //   // Decrease Extended exposure to match reduced Vesu position
+  //   // ! todo incorrect, to fix
+  //   routes.push({ type: RouteType.EXTENDED_DECREASE_LEVER, amount: safeUsdcWeb3Number(0), instrument, priority: routes.length });
+  //   this._budget.applyExtendedExposureDelta(instrument, safeUsdcWeb3Number(0));
+
+  //   // Revert Extended leverage back to normal
+  //   routes.push({ type: RouteType.CRISIS_UNDO_EXTENDED_MAX_LEVERAGE, priority: routes.length });
+
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  // _classifyLtvExtended has been merged into the unified _classifyLTV above.
+
+  // ── LTV Extended route builders ───────────────────────────────────────
+
+  /**
+   * LTV_EXTENDED_HIGH_USE_VA_OR_WALLET:
+   * VA/Wallet has funds → route them to Extended.
+   * Routes: [VA_TO_EXTENDED, WALLET_TO_EXTENDED] (wallet-first, then VA for remainder)
+   */
+  // private _buildLtvExtendedDepositFromVARoutes(amountUsd: number): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = this._buildExtendedDepositRoutes(amountUsd);
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  /**
+   * LTV_VESU_LOW_TO_EXTENDED:
+   * Borrow USDC from Vesu, route through VA to Extended.
+   * Routes: [VESU_BORROW, VA_TO_EXTENDED]
+   */
+  // private _buildLtvExtendedBorrowFromVesuRoutes(borrowUsd: number, vesuDeltas: Web3Number[]): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = [];
+  //   const amt = safeUsdcWeb3Number(borrowUsd);
+
+  //   // Borrow USDC from Vesu (lands in VA)
+  //   const { routes: borrowRoutes } = this._buildVesuBorrowRoutes(borrowUsd, vesuDeltas);
+  //   routes.push(...borrowRoutes);
+
+  //   // VA → Extended
+  //   routes.push({ type: RouteType.VA_TO_EXTENDED, amount: amt, priority: routes.length });
+  //   this._budget.applyExtendedBalanceChange(borrowUsd);
+
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  /**
+   * MARGIN_CRISIS_EXTENDED:
+   * Borrow beyond target HF on Vesu to free USDC, deposit to Extended,
+   * then decrease Vesu/Extended lever, undo crisis leverage.
+   * Routes: [CRISIS_BORROW_BEYOND_TARGET_HF, VA_TO_EXTENDED,
+   *          VESU_MULTIPLY_DECREASE_LEVER, EXTENDED_DECREASE_LEVER,
+   *          CRISIS_UNDO_EXTENDED_MAX_LEVERAGE]
+   */
+  // private _buildMarginCrisisExtendedRoutes(neededUsd: number, vesuDeltas: VesuPoolDelta[]): ExecutionRoute[] {
+  //   // ! todo need to verify this case properly
+
+  //   const routes: ExecutionRoute[] = [];
+  //   const amt = safeUsdcWeb3Number(neededUsd);
+  //   const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+
+  //   // Borrow beyond normal target HF to free USDC
+  //   const pool = vesuDeltas.find((d) => d.debtDelta.greaterThan(0)) ?? vesuDeltas[0];
+  //   routes.push({
+  //     type: RouteType.CRISIS_BORROW_BEYOND_TARGET_HF,
+  //     poolId: pool?.poolId ?? ('' as unknown as ContractAddr),
+  //     token: pool?.debtToken?.symbol ?? this._config.assetToken.symbol,
+  //     amount: amt,
+  //     priority: routes.length,
+  //   });
+
+  //   // Borrowed USDC (now in VA) → Extended
+  //   routes.push({ type: RouteType.VA_TO_EXTENDED, amount: amt, priority: routes.length });
+  //   this._budget.applyExtendedBalanceChange(neededUsd);
+
+  //   // Wait for Extended deposit to be credited
+  //   routes.push({ type: RouteType.RETURN_TO_WAIT, priority: routes.length });
+
+  //   // Decrease Vesu leverage
+  //   routes.push(...this._buildVesuDecreaseLeverRoutes(vesuDeltas));
+
+  //   // Decrease Extended exposure to match
+  //   routes.push({ type: RouteType.EXTENDED_DECREASE_LEVER, amount: amt, instrument, priority: routes.length });
+  //   this._budget.applyExtendedExposureDelta(instrument, new Web3Number(amt.negated().toFixed(USDC_TOKEN_DECIMALS), USDC_TOKEN_DECIMALS));
+
+  //   // Revert crisis leverage
+  //   routes.push({ type: RouteType.CRISIS_UNDO_EXTENDED_MAX_LEVERAGE, priority: routes.length });
+
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  // ! todo implement max lever amount per execution cycle
+
+  private _rebalanceFunds({
+    extAvlWithdraw,
+    extUpnl,
+    vaUsd,
+    walletUsd,
+    vesuBorrowCapacity,
+    vesuLeverage,
+    extendedLeverage,
+  }: Inputs): Deltas {
+    const total = extAvlWithdraw + extUpnl + vaUsd + walletUsd + vesuBorrowCapacity;
+
+    // Target eco split
+    const extendedTarget = (total) / (1 + extendedLeverage / vesuLeverage);
+    const extendedInitial = extAvlWithdraw + extUpnl;
+
+    let delta = extendedTarget - extendedInitial;
+
+    // Initialize deltas (0 = no change)
+    let dExtAvlWithdraw = 0,
+      dExtUpnl = 0,
+      dVaUsd = 0,
+      dWalletUsd = 0,
+      dVesuBorrowCapacity = 0,
+      finalVaUsd = vaUsd,
+      finalExtended = extAvlWithdraw + (Math.max(extUpnl, 0));
+
+    // --- Case 1: eco1 needs MORE funds (pull from eco2)
+    if (delta > 0) {
+      let need = delta;
+      const eps = CASE_THRESHOLD_USD;
+
+      const takeWalletUsd = routableDrawAmount(walletUsd, need, eps);
+      dWalletUsd -= takeWalletUsd;
+      need -= takeWalletUsd;
+
+      const takeVaUsd = routableDrawAmount(vaUsd, need, eps);
+      dVaUsd -= takeVaUsd;
+      need -= takeVaUsd;
+
+      finalVaUsd -= takeVaUsd; // remove, bcz its sent to extended and wont be available for vesu multiply
+      finalVaUsd += walletUsd - takeWalletUsd; // add remaining wallet usd to va
+      // dWallet
+
+      const takeVesuBorrowCapacity = routableDrawAmount(vesuBorrowCapacity, need, eps);
+      dVesuBorrowCapacity -= takeVesuBorrowCapacity;
+      need -= takeVesuBorrowCapacity;
+
+      finalVaUsd += vesuBorrowCapacity - takeVesuBorrowCapacity; // add remaining vesu borrow capacity to va
+
+      // Received into eco1 → distribute proportionally into E1/E2
+      const received = delta - need;
+      const eco1Sum = extAvlWithdraw + extUpnl;
+      finalExtended += received;
+
+      if (eco1Sum >= 0) {
+        // any received amount is always given to extended avl withdaw only. upnl wont change
+        dExtAvlWithdraw += received;
+      } else {
+        // Negative Extended "liquid" (withdraw + uPnL): cover uPnL deficit first, then avl withdraw.
+        const hole = -eco1Sum;
+        const fillUpnl = Math.min(received, hole);
+        dExtUpnl += fillUpnl;
+        dExtAvlWithdraw += received - fillUpnl;
+        finalExtended -= fillUpnl;
+      }
+
+      if (need > CASE_THRESHOLD_USD) {
+        throw new Error(`${this._tag}: Insufficient funds to cover margin needs`);
+      }
+    }
+
+    // --- Case 2: eco2 needs MORE funds (push from eco1)
+    else if (delta < 0) {
+      let need = -delta;
+
+      const takeExtAvlWithdraw = Math.min(Math.max(extAvlWithdraw, 0), need);
+      dExtAvlWithdraw -= takeExtAvlWithdraw;
+
+      const takeExtUpnl = Math.min(Math.max(extUpnl, 0), need);
+      dExtUpnl -= takeExtUpnl;
+
+      const netDrawableAmount = takeExtAvlWithdraw + takeExtUpnl;
+      if (netDrawableAmount > CASE_THRESHOLD_USD) {
+        need -= netDrawableAmount;
+        finalExtended -= netDrawableAmount;
+      }
+
+      const sent = -delta - need;
+
+      // Distribute into eco2 proportionally (optional design choice)
+      const eco2Sum = vaUsd + walletUsd + vesuBorrowCapacity;
+
+      const netWalletUsd = walletUsd < CASE_THRESHOLD_USD ? 0 : walletUsd;
+      finalVaUsd += sent + netWalletUsd;
+
+      if (eco2Sum >= 0) {
+        // all amount is sent to wallet only
+        dWalletUsd += sent;
+      } else {
+        // dont think it can be negative
+        throw new Error(`${this._tag}: Unexpected case`);
+      }
+
+      if (need > CASE_THRESHOLD_USD) {
+        throw new Error(`${this._tag}: Insufficient funds to cover margin needs`);
+      }
+    }
+
+    return { dExtAvlWithdraw, dExtUpnl, dVaUsd, dWalletUsd, dVesuBorrowCapacity, finalVaUsd, finalExtended, isExtendedToVesu: delta < 0 };
+  }
+
+  private _scaleVesuPoolDeltasByFactor(deltas: VesuPoolDelta[], scale: number): VesuPoolDelta[] {
+    if (scale >= 1 - 1e-15) return deltas;
+    return deltas.map((d) => ({
+      ...d,
+      collateralDelta: new Web3Number(
+        (d.collateralDelta.toNumber() * scale).toFixed(COLLATERAL_PRECISION),
+        d.collateralToken.decimals,
+      ),
+      debtDelta: new Web3Number(
+        (d.debtDelta.toNumber() * scale).toFixed(USDC_TOKEN_DECIMALS),
+        USDC_TOKEN_DECIMALS,
+      ),
+    }));
+  }
+
+  /**
+   * 3. New Deposits / Excess Funds
+   *
+   * Computes how much exposure to create on Vesu and Extended, then
+   * distributes available funds using shortest-path priority chains:
+   *   Extended margin:  Wallet → VA → Vesu borrow
+   *   Vesu margin:      VA → Wallet → Extended
+   */
+  /**
+   * 3. New Deposits / Excess Funds
+   *
+   * Computes allocation split between Vesu and Extended, then sources
+   * funds and creates lever-increase routes.
+   *
+   * Order: {@link _rebalanceFunds} first → project VA / Extended liquid after the same funding
+   * routes (wallet→VA, borrow→VA, VA→Extended, Extended→wallet→VA) → ideal Vesu/Extended deltas
+   * from distributable split → cap common BTC by min(Vesu fundable, Extended fundable) → scale
+   * Vesu deltas and recompute Extended deltas so both sides stay matched.
+   *
+   * Fund flow (single pass — avoid VA→Extended then Extended→wallet round-trips):
+   *   1) Treat Vesu borrow headroom that the multiply route will consume as covering
+   *      part of the Vesu USDC need (no standalone VESU_BORROW for that slice). Cap
+   *      standalone VESU_BORROW→VA→Extended by remaining headroom.
+   *   2) Cover Extended deposit delta: REALISE_PNL first, then withdrawal→avail-trade,
+   *      then wallet→Extended, then VA→Extended only up to VA surplus above the USDC
+   *      that must remain for Vesu (after step 1), then borrow→VA→Extended.
+   *   3) Cover Vesu VA shortfall: wallet→VA, Extended withdrawal→wallet→VA, REALISE_PNL,
+   *      then combined Extended→wallet→VA for the remainder.
+   *   4) RETURN_TO_WAIT when needed; then AVNU + VESU_MULTIPLY + EXTENDED_INCREASE.
+   */
+  /**
+   * @param skipAvnuDepositSwap Omit AVNU before Vesu multiply when LTV cases already ran this cycle
+   *   (matrix tests expect deposit routes without that step).
+   */
+  private _classifyDeposits(
+    withdrawAmount: Web3Number,
+    skipAvnuDepositSwap = false,
+  ): SolveCaseEntry[] {
+    if (withdrawAmount.toNumber() > CASE_THRESHOLD_USD) return [];
+
+    const distributableAmount = this._computeDistributableAmount(
+      this._budget.vesuDebtDeltas, withdrawAmount,
+    );
+    if (distributableAmount.toNumber() <= CASE_THRESHOLD_USD) return [];
+
+    const vesuLeverage = calculateVesuLeverage();
+    const extendedLeverage = calculateExtendedLevergae();
+
+    const { dExtAvlWithdraw, dExtUpnl, dVaUsd, dWalletUsd, dVesuBorrowCapacity, isExtendedToVesu, finalVaUsd, finalExtended } = this._rebalanceFunds({
+      extAvlWithdraw: this._budget.extAvailWithdraw,
+      extUpnl: this._budget.extAvailUpnl,
+      vaUsd: this._budget.vaUsd,
+      walletUsd: this._budget.walletUsd,
+      vesuBorrowCapacity: this._budget.vesuBorrowCapacity,
+      vesuLeverage,
+      extendedLeverage,
+    });
+    logger.info(`${this._tag}::_classifyDeposits dExtAvlWithdraw=${dExtAvlWithdraw}, dExtUpnl=${dExtUpnl}, dVaUsd=${dVaUsd}, dWalletUsd=${dWalletUsd}, dVesuBorrowCapacity=${dVesuBorrowCapacity}, isExtendedToVesu=${isExtendedToVesu}, finalVaUsd=${finalVaUsd}`);
+
+    // const { vesuAllocationUsd } = this._computeAllocationSplit(distributableAmount);
+
+    let vesuDeltas = this._computePerPoolCollateralDeltas(new Web3Number(finalVaUsd.toFixed(USDC_TOKEN_DECIMALS), USDC_TOKEN_DECIMALS));
+    const collateralPrice = this._budget.vesuPools[0]?.collateralPrice ?? 0;
+    const collateralDecimals = this._budget.vesuPools[0]?.collateralToken.decimals ?? 0;
+    let _extendedPositionDelta = new Web3Number((finalExtended * extendedLeverage / collateralPrice).toFixed(USDC_TOKEN_DECIMALS), collateralDecimals).toFixedRoundDown(COLLATERAL_PRECISION);
+    logger.info(`${this._tag}::_classifyDeposits extendedPositionDelta=${_extendedPositionDelta}`);
+    logger.info(`${this._tag}::_classifyDeposits vesuDeltas=${JSON.stringify(vesuDeltas)}`);
+    assert(vesuDeltas.length == 1, 'vesuDeltas should have only one delta');
+    const minPositionDelta = Math.min(vesuDeltas[0].collateralDelta.toNumber(), Number(_extendedPositionDelta));
+    logger.info(`${this._tag}::_classifyDeposits minPositionDelta=${minPositionDelta}`);
+    vesuDeltas[0].collateralDelta = new Web3Number(minPositionDelta.toFixed(COLLATERAL_PRECISION), vesuDeltas[0].collateralDelta.decimals);
+    const extendedPositionDeltas: ExtendedPositionDelta[] = [{
+      instrument: this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD',
+      delta: new Web3Number((minPositionDelta).toFixed(COLLATERAL_PRECISION), collateralDecimals),
+    }];
+    const vesuDepositAmount = this._computeVesuDepositAmount(vesuDeltas);
+    logger.info(`${this._tag}::_classifyDeposits vesuDepositAmount=${vesuDepositAmount}`);
+
+    const routes: ExecutionRoute[] = [];
+
+    if (isExtendedToVesu) {
+      // negative means to spend
+      if (dExtUpnl < 0) {
+        this._getUpnlRoute(Math.abs(dExtUpnl), routes);
+      }
+
+      if (dExtUpnl < 0 || dExtAvlWithdraw < 0) {
+        const netAmount = (dExtAvlWithdraw < 0 ? Math.abs(dExtAvlWithdraw) : 0) + (dExtUpnl < 0 ? Math.abs(dExtUpnl) : 0);
+        const walletUsd = this._budget.walletUsd; // its important to put it here, to ensure below route's impact on walletUsd doesnt double count later
+        this._getExtendedToWalletRoute(netAmount, routes);
+        this._getWALLETToVARoute(netAmount + walletUsd, routes); // add wallet usd to send entire amount to va
+      }
+    } else {
+      let netDVaUsd = dVaUsd;
+      if (dWalletUsd < 0) {
+        // always send entire amount to va (no use it being in wallet)
+        this._getWalletToVARoute(this._budget.walletUsd, routes);
+        netDVaUsd += dWalletUsd;
+      }
+
+      if (dVesuBorrowCapacity < 0) {
+        this._buildVesuBorrowRoutes(Math.abs(dVesuBorrowCapacity), routes);
+        netDVaUsd += dVesuBorrowCapacity;
+      }
+
+      if (netDVaUsd < 0) {
+        this._getVAToEXTENDEDRoute(Math.abs(netDVaUsd), routes, true); // true means, add wait route always
+      }
+    }
+
+    // ── Vesu lever increase ─────────────────────────────────────────────
+    for (const vesuDelta of vesuDeltas) {
+      if (
+        !skipAvnuDepositSwap &&
+        vesuDepositAmount.toNumber() > CASE_THRESHOLD_USD
+      ) {
+        // routes.push({
+        //   type: RouteType.AVNU_DEPOSIT_SWAP,
+        //   priority: routes.length,
+        //   fromToken: vesuDelta.collateralToken.symbol,
+        //   fromAmount: vesuDepositAmount,
+        //   toToken: vesuDelta.debtToken.symbol,
+        // });
+      }
+      if (vesuDelta.collateralDelta.toNumber() > 0) {
+        // removes borrowing capacity after excluding delta capacity that is being briddged out
+        // this is bcz, since bnorrow capacity exists, no need for external margin amount
+        const availableBorrowCapacity = this._budget.vesuBorrowCapacity;
+        const externalDepositAmount = vesuDepositAmount.minus(availableBorrowCapacity);
+        const swappedAmount = new Web3Number((externalDepositAmount.toNumber() * vesuDelta.debtPrice / (vesuDelta.collateralPrice ?? 0)).toFixed(6), vesuDelta.collateralToken.decimals);
+        routes.push({
+          type: RouteType.VESU_MULTIPLY_INCREASE_LEVER,
+          priority: routes.length,
+          collateralToken: vesuDelta.collateralToken,
+          debtToken: vesuDelta.debtToken,
+          marginAmount: swappedAmount, // should be the swapped amount as per vesu multiply adapter
+          swappedCollateralAmount: vesuDelta.collateralDelta.minus(swappedAmount),
+          debtAmount: vesuDelta.debtDelta.plus(availableBorrowCapacity),
+          poolId: vesuDelta.poolId,
+        } as VesuMultiplyRoute);
+      }
+    }
+
+    // ── Extended lever increase ────────────────────────────────────────
+    for (const epDelta of extendedPositionDeltas) {
+      if (epDelta.delta.toNumber() > 0) {
+        routes.push({
+          type: RouteType.EXTENDED_INCREASE_LEVER,
+          priority: routes.length,
+          instrument: epDelta.instrument,
+          amount: epDelta.delta,
+        } as ExtendedLeverRoute);
+      }
+    }
+
+    if (routes.length === 0) return [];
+    routes.forEach((r, i) => { r.priority = i; });
+    return [{
+      case: CASE_DEFINITIONS[CaseId.DEPOSIT_FRESH_VAULT],
+      additionalArgs: {
+        amount: safeUsdcWeb3Number(distributableAmount.toNumber()),
+      },
+      routes,
+    }];
+  }
+
+  /** 4. Exposure Imbalance */
+  // private _classifyImbalance(
+  //   vesuDeltas: VesuPoolDelta[],
+  // ): SolveCaseEntry[] {
+  //   const extBtc = this._totalExtendedExposure().toNumber();
+  //   const vesuBtc = this._totalVesuCollateral().toNumber();
+  //   const maxBtc = Math.max(extBtc, vesuBtc);
+  //   if (maxBtc <= 0) return [];
+  //   const imb = extBtc - vesuBtc;
+  //   if (Math.abs(imb) / maxBtc <= IMBALANCE_THRESHOLD_FRACTION) return [];
+  //   const exposureDiffBtc = Math.abs(imb);
+  //   const rem = this._budget.totalUnused;
+
+  //   if (imb > 0) {
+  //     // Extended excess short → need more Vesu collateral
+  //     if (rem > CASE_THRESHOLD_USD) {
+  //       return [{
+  //         case: CASE_DEFINITIONS[CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_HAS_FUNDS],
+  //         additionalArgs: {},
+  //         routes: this._buildImbalanceExtExcessShortHasFundsRoutes(rem, exposureDiffBtc, vesuDeltas),
+  //       }];
+  //     }
+  //     return [{
+  //       case: CASE_DEFINITIONS[CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_NO_FUNDS],
+  //       additionalArgs: {},
+  //       routes: this._buildImbalanceExtExcessShortNoFundsRoutes(exposureDiffBtc),
+  //     }];
+  //   }
+
+  //   // Vesu excess long → need more Extended exposure
+  //   if (rem > CASE_THRESHOLD_USD) {
+  //     return [{
+  //       case: CASE_DEFINITIONS[CaseId.IMBALANCE_VESU_EXCESS_LONG_HAS_FUNDS],
+  //       additionalArgs: {},
+  //       routes: this._buildImbalanceVesuExcessLongHasFundsRoutes(rem, exposureDiffBtc, vesuDeltas),
+  //     }];
+  //   }
+  //   return [{
+  //     case: CASE_DEFINITIONS[CaseId.IMBALANCE_VESU_EXCESS_LONG_NO_FUNDS],
+  //     additionalArgs: {},
+  //     routes: this._buildImbalanceVesuExcessLongNoFundsRoutes(vesuDeltas),
+  //   }];
+  // }
+
+  // ── Imbalance route builders ──────────────────────────────────────────
+
+  /**
+   * IMBALANCE_EXTENDED_EXCESS_SHORT_HAS_FUNDS:
+   * Extended has too much short exposure vs Vesu. Use VA/Wallet funds to
+   * add Vesu collateral and reduce Extended exposure.
+   *
+   * The new Vesu collateral covers part of the imbalance; the remaining
+   * gap is closed by reducing Extended short exposure.
+   *
+   * Routes: [AVNU_DEPOSIT_SWAP, VESU_MULTIPLY_INCREASE_LEVER, EXTENDED_DECREASE_LEVER]
+   */
+  // private _buildImbalanceExtExcessShortHasFundsRoutes(
+  //   fundsUsd: number, exposureDiffBtc: number, vesuDeltas: VesuPoolDelta[],
+  // ): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = [];
+  //   const collSym = this._config.collateralToken.symbol;
+  //   const debtSym = this._config.assetToken.symbol;
+  //   const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+
+  //   // Swap USDC → BTC for Vesu collateral
+  //   routes.push({
+  //     type: RouteType.AVNU_DEPOSIT_SWAP,
+  //     fromToken: debtSym,
+  //     fromAmount: safeUsdcWeb3Number(fundsUsd),
+  //     toToken: collSym,
+  //     priority: routes.length,
+  //   } as SwapRoute);
+
+  //   // Increase Vesu lever (deposit collateral + borrow)
+  //   routes.push(...this._buildVesuIncreaseLeverRoutes(vesuDeltas));
+
+  //   // New Vesu collateral covers part of the imbalance
+  //   const newVesuCollBtc = vesuDeltas
+  //     .filter((d) => d.collateralDelta.greaterThan(0))
+  //     .reduce((sum, d) => sum + d.collateralDelta.toNumber(), 0);
+
+  //   // Remaining imbalance that needs to be closed on Extended
+  //   const extDecreaseExposureBtc = Math.max(0, exposureDiffBtc - newVesuCollBtc);
+
+  //   if (extDecreaseExposureBtc > 0) {
+  //     const decDelta = new Web3Number(extDecreaseExposureBtc.toFixed(COLLATERAL_PRECISION), USDC_TOKEN_DECIMALS);
+  //     routes.push({
+  //       type: RouteType.EXTENDED_DECREASE_LEVER,
+  //       amount: decDelta,
+  //       instrument,
+  //       priority: routes.length,
+  //     });
+  //     this._budget.applyExtendedExposureDelta(instrument, new Web3Number(decDelta.negated().toFixed(COLLATERAL_PRECISION), USDC_TOKEN_DECIMALS));
+
+  //   }
+
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  /**
+   * IMBALANCE_EXTENDED_EXCESS_SHORT_NO_FUNDS:
+   * No available funds to add Vesu collateral → reduce Extended exposure
+   * by the full imbalance amount.
+   * Routes: [EXTENDED_DECREASE_LEVER]
+   */
+  private _buildImbalanceExtExcessShortNoFundsRoutes(exposureDiffBtc: number): ExecutionRoute[] {
+    const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+    // hardcoding 8 decimals is ok here
+    const decDelta = new Web3Number(Web3Number.fromNumber(exposureDiffBtc, 8).toFixedRoundDown(COLLATERAL_PRECISION), USDC_TOKEN_DECIMALS);
+    const collPx = this._budget.vesuPools[0]?.collateralPrice ?? 1;
+    this._budget.applyExtendedExposureDelta(
+      instrument,
+      new Web3Number(Web3Number.fromNumber(decDelta.negated().toNumber(), 8).toFixedRoundDown(COLLATERAL_PRECISION), USDC_TOKEN_DECIMALS),
+      collPx,
+    );
+    return [{
+      type: RouteType.EXTENDED_DECREASE_LEVER,
+      amount: decDelta,
+      instrument,
+      priority: 0,
+    }];
+  }
+
+  /**
+   * IMBALANCE_VESU_EXCESS_LONG_HAS_FUNDS:
+   * Vesu has too much long exposure vs Extended. Deposit funds on Extended
+   * to increase short exposure, and decrease Vesu lever for the remainder.
+   *
+   * Routes: [WALLET_TO_EXTENDED / VA_TO_EXTENDED, EXTENDED_INCREASE_LEVER,
+   *          VESU_MULTIPLY_DECREASE_LEVER]
+   */
+  // private _buildImbalanceVesuExcessLongHasFundsRoutes(
+  //   fundsUsd: number, exposureDiffBtc: number, vesuDeltas: VesuPoolDelta[],
+  // ): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = [];
+  //   const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+
+  //   // ExecutionRoute funds to Extended (wallet-first, then VA)
+  //   routes.push(...this._buildExtendedDepositRoutes(fundsUsd));
+
+  //   // Compute how much new Extended exposure the deposited funds create
+  //   const extLeverage = calculateExtendedLevergae();
+  //   const newExtExposureUsd = fundsUsd * extLeverage;
+  //   const avgCollPrice = this._budget.vesuPoolStates[0]?.collateralPrice ?? 1;
+  //   const newExtExposureBtc = avgCollPrice > 0 ? newExtExposureUsd / avgCollPrice : 0;
+
+  //   // Increase Extended lever by the new exposure (capped to imbalance)
+  //   const extIncreaseBtc = Math.min(newExtExposureBtc, exposureDiffBtc);
+  //   if (extIncreaseBtc > 0) {
+  //     const incDelta = new Web3Number(extIncreaseBtc.toFixed(COLLATERAL_PRECISION), USDC_TOKEN_DECIMALS);
+  //     routes.push({
+  //       type: RouteType.EXTENDED_INCREASE_LEVER,
+  //       amount: incDelta,
+  //       instrument,
+  //       priority: routes.length,
+  //     });
+  //     this._budget.applyExtendedExposureDelta(instrument, incDelta);
+  //   }
+
+  //   // Remaining imbalance closed by decreasing Vesu lever
+  //   const vesuDecreaseBtc = Math.max(0, exposureDiffBtc - extIncreaseBtc);
+  //   if (vesuDecreaseBtc > 0) {
+  //     routes.push(...this._buildVesuDecreaseLeverRoutes(vesuDeltas));
+  //   }
+
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  /**
+   * IMBALANCE_VESU_EXCESS_LONG_NO_FUNDS:
+   * No funds to increase Extended → decrease Vesu lever by the full imbalance.
+   * Routes: [VESU_MULTIPLY_DECREASE_LEVER]
+   */
+  // private _buildImbalanceVesuExcessLongNoFundsRoutes(vesuDeltas: VesuPoolDelta[]): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = this._buildVesuDecreaseLeverRoutes(vesuDeltas);
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  // ── Main classifier (orchestrator) ─────────────────────────────────────
+
+  /**
+   * Classifies the current state into actionable cases. Each case carries
+   * its own execution routes with amounts and state info.
+   */
+  private _classifyCases(withdrawAmount: Web3Number): SolveCaseEntry[] {
+    this._budget.initBudget();
+
+    // withdrawal uses full raw balances (no safety buffer)
+    const withdrawalCases = this._classifyWithdrawal(withdrawAmount);
+
+    // apply safety buffer to remaining balances for subsequent classifiers
+    this._budget.applyBuffer(this._config.limitBalanceBufferFactor);
+
+    // 2. LTV Rebalance — unified Vesu high LTV + Extended low margin
+    const ltvCases = this._classifyLTV();
+
+    // 3. New Deposits — allocate remaining budget to lever operations
+    const depositCases = this._classifyDeposits(
+      withdrawAmount,
+      ltvCases.length > 0,
+    );
+
+    return [
+      ...withdrawalCases,
+      ...ltvCases,
+      ...depositCases,
+    ];
+  }
+
+
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — aggregation helpers
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  private _totalVesuCollateral(): Web3Number {
+    return this._budget.vesuPools.reduce(
+      (acc, pool) =>
+        acc.plus(
+          pool.collateralAmount,
+        ),
+      new Web3Number(0, USDC_TOKEN_DECIMALS),
+    );
+  }
+
+  private _totalVesuCollateralUsd(): Web3Number {
+    return this._budget.vesuPools.reduce(
+      (acc, pool) =>
+        acc.plus(
+          pool.collateralAmount.multipliedBy(pool.collateralPrice),
+        ),
+      new Web3Number(0, USDC_TOKEN_DECIMALS),
+    );
+  }
+
+  private _totalExtendedExposure(): Web3Number {
+    return this._budget.extendedPositionsView.reduce(
+      (acc, position) => acc.plus(position.size),
+      new Web3Number(0, USDC_TOKEN_DECIMALS),
+    );
+  }
+
+  private _totalExtendedExposureUsd(): Web3Number {
+    return this._budget.extendedPositionsView.reduce(
+      (acc, position) => acc.plus(position.valueUsd),
+      new Web3Number(0, USDC_TOKEN_DECIMALS),
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — logging
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  private _logSolveResult(result: SolveResult): void {
+    // Log detected cases
+    logger.info(
+      `${this._tag}::solve detected ${result.cases.length} case(s): ` +
+      result.cases
+        .map((c) => `[${c.case.category}] ${c.case.id}`)
+        .join(', '),
+    );
+    for (const entry of result.cases) {
+      logger.info(
+        `${this._tag}::solve case "${entry.case.title}" — ` +
+        `steps: ${entry.case.steps.length}`,
+      );
+    }
+
+    logger.info(
+      `${this._tag}::solve result — ` +
+      `extendedDeposit: ${result.extendedDeposit.toNumber()}, ` +
+      `vesuAllocUsd: ${result.vesuAllocationUsd.toNumber()}, ` +
+      `extAllocUsd: ${result.extendedAllocationUsd.toNumber()}, ` +
+      `bringLiquidity: ${result.bringLiquidityAmount.toNumber()}`,
+    );
+
+    for (let i = 0; i < result.vesuDeltas.length; i++) {
+      const delta = result.vesuDeltas[i];
+      logger.info(
+        `${this._tag}::solve vesu[${i}] ` +
+        `pool=${delta.poolId.shortString()} ` +
+        `debtDelta=${delta.debtDelta.toNumber()} ` +
+        `collateralDelta=${delta.collateralDelta.toNumber()}`,
+      );
+    }
+
+    for (let i = 0; i < result.extendedPositionDeltas.length; i++) {
+      const delta = result.extendedPositionDeltas[i];
+      logger.info(
+        `${this._tag}::solve extended[${i}] ` +
+        `instrument=${delta.instrument} ` +
+        `delta=${delta.delta.toNumber()}`,
+      );
+    }
+
+    for (const entry of result.cases) {
+      const caseRoutes = entry.routes;
+      logger.info(
+        `${this._tag}::solve case "${entry.case.id}" routes (${caseRoutes.length}): ` +
+        caseRoutes
+          .map((r) => `[${r.priority}] ${r.type} ${routeSummary(r)}`)
+          .join(' → '),
+      );
+    }
+  }
+}