feat: add maxBorrowAmountPerOperation and oversized-deal splitter

Adds a per-operation borrow cap to prevent single-credit-accept operations
from consuming too much of the total maxBorrowAmount at once, making
repay/reborrow cycles easier with less liquidity per operation.

## maxBorrowAmountPerOperation (new config field)
File: modules/types.ts
- New optional field on LendingEntryBase (shared by MPA and creditOffer).
- Enforced in buildCreditOfferAcceptOperation: any single borrow exceeding
  the limit is rejected with a descriptive error.
- isMaxBorrowAmountError widened to match both ceiling and per-op patterns.

File: modules/bot_settings.ts
- Validation: must be a positive number.

## MPA planner capping
File: modules/cr_planner.ts
- buildDebtFirstCrPlan clamps debtDelta by maxBorrowAmountPerOperation
  on top of the total maxBorrowAmount cap.

## _splitOversizedCreditDeals (new feature)
File: modules/credit_runtime.ts
- Phase 0 of _runCreditMaintenance: scans creditOffer deals where
  individual debt exceeds maxBorrowAmountPerOperation.
- Splits oversized deals into N equal pieces via atomic repay+reborrow
  transactions, keeping total debt unchanged.
- min_deal_amount guard: skips deals where a piece would be below the
  offer's minimum deal size.
- MAX_PIECES_PER_CYCLE (48, from TIMING constant) prevents unbounded
  cycles that would exceed the watchdog interval.
- 6s settle delay between pieces with shutdown abort (T1).
- _splitInFlight concurrency guard (T2) prevents runMaintenance /
  runCreditWatchdog collisions.
- Canonical settle-delay resolution matching dexbot_maintenance_runtime.ts
  (T3). Note: per-bot TIMING.BLOCKCHAIN_SETTLE_DELAY_MS in bots.json is
  no longer honoured for split pacing.

File: tests/test_credit_runtime.ts
- 6 new tests: per-op rejection, offer-selection capping, correct
  split arithmetic, within-limit skip, no-limit skip, error-pattern match.

## Risk/edge-case notes
- T3 settleDelay resolution changed from bot.config.TIMING to the imported
  TIMING constant — see CHANGELOG.
- Offer min_deal_amount is cached; stale values are possible if the offer
  is edited on-chain mid-split (rare).
- T1 shutdown check fires once at the start of each 6s wait; worst case
  is one extra piece of post-shutdown activity (matches existing pattern).

## Validation
- npm run typecheck: clean
- npm test: all 38 credit runtime tests pass, full suite clean

Author: froooze

CHANGELOG.md

@@ -9,6 +9,8 @@ All notable changes to this project will be documented in this file.
 - **Fix**: correct AMA4 slowPeriod from 107.4 to 102.4 — aligns AMA4 with the same λ=0.0025 refit applied to AMA1-3 in v1.1.3. Fixes stale slowPeriod references in market_adapter/README.md, test fixtures, and TradingView chart generator (`modules/constants.ts`, `market_adapter/README.md`, `tests/test_market_adapter_log_format.ts`, `tests/test_market_adapter_logic.ts`, `analysis/tradingview/tradingview_uplot_chart_generator.ts`).
 - **Feat**: narrow optimizer slow search range from 50-200 to 40-160 — focuses the geometric grid on the range where fitted winners consistently land, reducing wasted evaluations at uncompetitive extremes (`analysis/ama_fitting/optimizer_high_resolution.ts`).
 - **Docs**: sync v1.1.3 release notes with amaS% retune (0.085→0.08), update DYNAMIC_WEIGHT_RESEARCH.md knob table, correct EVOLUTION.md commit count for v1.1.3 (2→4) and summary to include the amaS% retune (`CHANGELOG.md`, `analysis/trend_detection/DYNAMIC_WEIGHT_RESEARCH.md`, `docs/EVOLUTION.md`).
+- **Feat**: add `maxBorrowAmountPerOperation` config field and `_splitOversizedCreditDeals` — when a credit deal exceeds `maxBorrowAmountPerOperation`, maintenance splits it into equal pieces via repay+reborrow cycles with 6s spacing (`modules/types.ts`, `modules/bot_settings.ts`, `modules/credit_runtime.ts`, `modules/cr_planner.ts`).
+- **Fix**: settle-delay resolution for credit splits now reads from the `TIMING` constant instead of `bot.config.TIMING.BLOCKCHAIN_SETTLE_DELAY_MS` — consistent with `dexbot_maintenance_runtime.ts`. Any per-bot `TIMING.BLOCKCHAIN_SETTLE_DELAY_MS` override in `bots.json` is no longer honoured for split pacing (`modules/credit_runtime.ts`).
 
 ## [1.1.3] - 2026-07-13 - AMA Refit λ=0.0025, amaS% Retune, tsx Compatibility, Doc Fixes
 

modules/bot_settings.ts

@@ -139,6 +139,13 @@ function validateBotEntry(b: any, i: number, src: string): string | null {
                         }
                     }
 
+                    // maxBorrowAmountPerOperation: optional, must be a fixed positive number
+                    if ('maxBorrowAmountPerOperation' in item) {
+                        if (!isPositiveNumber(item.maxBorrowAmountPerOperation)) {
+                            problems.push(`debtPolicy.lending[${idx}].maxBorrowAmountPerOperation must be a positive number`);
+                        }
+                    }
+
                     // maxCollateralAmount: optional, positive number or percentage
                     if ('maxCollateralAmount' in item && !isPositiveNumberOrPercent(item.maxCollateralAmount)) {
                         problems.push(`debtPolicy.lending[${idx}].maxCollateralAmount must be a positive number or percentage`);

modules/cr_planner.ts

@@ -19,6 +19,7 @@ interface DebtFirstCrPlanOptions {
     maxCollateralRatio?: number;
     targetCollateralRatio?: number;
     maxBorrowAmount?: number;
+    maxBorrowAmountPerOperation?: number;
     maxCollateralAmount?: number | string;
     collateralLimitReferenceAmount?: number;
     minCollateralIncreaseThreshold?: number | string;
@@ -162,6 +163,7 @@ function buildDebtFirstCrPlan({
     maxCollateralRatio,
     targetCollateralRatio,
     maxBorrowAmount,
+    maxBorrowAmountPerOperation,
     maxCollateralAmount,
     collateralLimitReferenceAmount,
     minCollateralIncreaseThreshold,
@@ -224,7 +226,14 @@ function buildDebtFirstCrPlan({
 
     const targetDebt = (currentCollateralAmount as number) / ((feedPrice as number) * (desiredCr as number));
     const rawDebtDelta = targetDebt - (currentDebtAmount as number);
-    const debtDelta = clampIncreaseToTotalMax(rawDebtDelta, currentDebtAmount, maxBorrowAmount);
+    let debtDelta = clampIncreaseToTotalMax(rawDebtDelta, currentDebtAmount, maxBorrowAmount);
+    // Also clamp by per-operation limit
+    if (debtDelta > 0) {
+        const limit = positiveOrNull(maxBorrowAmountPerOperation);
+        if (limit !== null) {
+            debtDelta = Math.min(debtDelta, limit);
+        }
+    }
     const projectedDebt = Math.max(0, (currentDebtAmount as number) + debtDelta);
     const targetCollateral = (desiredCr as number) * (feedPrice as number) * projectedDebt;
     let collateralDelta = targetCollateral - (currentCollateralAmount as number);

modules/credit_runtime.ts

@@ -17,7 +17,7 @@ const {
     resolveMinCollateralIncreaseThreshold,
     resolveTargetCollateralRatio,
 } = require('./cr_planner');
-const { FEE_PARAMETERS, DEFAULT_TARGET_CR } = require('./constants');
+const { FEE_PARAMETERS, DEFAULT_TARGET_CR, TIMING } = require('./constants');
 const { roundToDecimals } = require('./utils/math_utils');
 const { PATHS } = require('./paths');
 const { readJSON } = require('./utils/fs_utils');
@@ -138,7 +138,7 @@ function isDeterministicMpaDebtBalanceError(err, plan) {
 
 function isMaxBorrowAmountError(err) {
     const message = String(err?.message || err || '');
-    return /would exceed maxBorrowAmount/.test(message);
+    return /would exceed maxBorrowAmount/.test(message) || /exceeds maxBorrowAmountPerOperation/.test(message);
 }
 
 function normalizeCollateralMap(acceptableCollateral) {
@@ -282,6 +282,7 @@ class CreditRuntime {
     _maintenanceInFlight: boolean;
     _watchdogInFlight: boolean;
     _reborrowsInFlight: boolean;
+    _splitInFlight: boolean;
 
     constructor(bot, options = {}) {
         this.bot = bot || {};
@@ -303,6 +304,7 @@ class CreditRuntime {
         this._maintenanceInFlight = false;
         this._watchdogInFlight = false;
         this._reborrowsInFlight = false;
+        this._splitInFlight = false;
     }
 
     _createDefaultState() {
@@ -1435,6 +1437,7 @@ class CreditRuntime {
             maxCollateralRatio: lendingItem.maxCollateralRatio,
             targetCollateralRatio: lendingItem.targetCollateralRatio,
             maxBorrowAmount: lendingItem.maxBorrowAmount,
+            maxBorrowAmountPerOperation: lendingItem.maxBorrowAmountPerOperation,
             maxCollateralAmount: posState.assignedCollateralBudget ?? lendingItem.maxCollateralAmount,
             collateralLimitReferenceAmount: posState.currentCollateralFundsTotal,
             minCollateralIncreaseThreshold: lendingItem.minCollateralIncreaseThreshold,
@@ -1624,6 +1627,15 @@ class CreditRuntime {
             }
         }
 
+        // Enforce per-operation borrow limit
+        const maxPerOp = positiveOrNull(policy?.maxBorrowAmountPerOperation);
+        if (maxPerOp !== null && Number.isFinite(borrowInt) && borrowInt > 0) {
+            const borrowFloat = blockchainToFloat(borrowInt, debtAsset.precision);
+            if (Number.isFinite(borrowFloat) && borrowFloat > maxPerOp) {
+                throw new Error(`borrowAmount ${borrowFloat} exceeds maxBorrowAmountPerOperation ${maxPerOp}`);
+            }
+        }
+
         if (!Number.isFinite(requiredCollateralInt) || requiredCollateralInt <= 0) {
             throw new Error('Unable to determine collateral amount for credit offer');
         }
@@ -2207,6 +2219,12 @@ class CreditRuntime {
             ? Number(remainingBorrowCapacity)
             : null;
 
+        // Apply per-operation borrow limit on top of remaining capacity
+        const maxPerOp = positiveOrNull(policy?.maxBorrowAmountPerOperation);
+        const effectiveBorrowCapacity = finiteRemainingBorrowCapacity !== null && maxPerOp !== null
+            ? Math.min(finiteRemainingBorrowCapacity, maxPerOp)
+            : finiteRemainingBorrowCapacity ?? maxPerOp;
+
         for (const offerId of allowedOfferIds) {
             const offer = await this._getOfferById(offerId);
             if (offer?.id && !seen.has(String(offer.id))) {
@@ -2241,7 +2259,7 @@ class CreditRuntime {
                     autoRepay,
                     specificPolicy: policy,
                 };
-                if (accountId && debtAsset && collateralAsset && finiteRemainingBorrowCapacity !== null) {
+                if (accountId && debtAsset && collateralAsset && effectiveBorrowCapacity !== null) {
                     const collateralSpec = normalizeAmountSpec(collateralAmount);
                     const collateralReferenceAmount = isPercentageAmountSpec(collateralSpec)
                         ? await this._getCollateralPercentageBase(accountId, collateralAsset.id)
@@ -2258,10 +2276,10 @@ class CreditRuntime {
                         collateralAsset
                     );
                     const desiredBorrowAmount = blockchainToFloat(desiredBorrowInt, debtAsset.precision);
-                    if (Number.isFinite(desiredBorrowAmount) && desiredBorrowAmount > finiteRemainingBorrowCapacity) {
+                    if (Number.isFinite(desiredBorrowAmount) && desiredBorrowAmount > effectiveBorrowCapacity) {
                         acceptArgs = {
                             offer,
-                            borrowAmount: finiteRemainingBorrowCapacity,
+                            borrowAmount: effectiveBorrowCapacity,
                             collateralAmount: { assetId: collateralAsset.id },
                             autoRepay,
                             specificPolicy: policy,
@@ -2276,12 +2294,12 @@ class CreditRuntime {
                     if (!isMaxBorrowAmountError(err)) {
                         throw err;
                     }
-                    if (finiteRemainingBorrowCapacity === null) {
+                    if (effectiveBorrowCapacity === null) {
                         throw err;
                     }
                     op = await this.buildCreditOfferAcceptOperation({
                         offer,
-                        borrowAmount: finiteRemainingBorrowCapacity,
+                        borrowAmount: effectiveBorrowCapacity,
                         collateralAmount: { assetId: collateralAssetId },
                         autoRepay,
                         specificPolicy: policy,
@@ -2372,6 +2390,137 @@ class CreditRuntime {
         };
     }
 
+    async _splitOversizedCreditDeals(lendingItem, assetId, posState, runtimeContext: Record<string, any> = {}) {
+        const maxPerOp = positiveOrNull(lendingItem.maxBorrowAmountPerOperation);
+        if (maxPerOp === null) return null;
+
+        // T2: Concurrency guard — prevent concurrent splits from runMaintenance / watchdog
+        if (this._splitInFlight) return { skipped: true, reason: 'split in flight' };
+        this._splitInFlight = true;
+        try {
+            return await this._doSplitOversizedCreditDeals(lendingItem, assetId, posState, runtimeContext);
+        } finally {
+            this._splitInFlight = false;
+        }
+    }
+
+    async _doSplitOversizedCreditDeals(lendingItem, assetId, posState, runtimeContext: Record<string, any> = {}) {
+        const maxPerOp = positiveOrNull(lendingItem.maxBorrowAmountPerOperation);
+        if (maxPerOp === null) return null;
+
+        const debtAsset = await this._resolveAsset(assetId);
+        const collateralAsset = await this._resolveAsset(lendingItem.collateralAsset);
+        if (!debtAsset || !collateralAsset) return null;
+
+        const deals = Array.isArray(posState?.creditDeals) ? posState.creditDeals : [];
+        const oversized = deals.filter((d) => {
+            const debt = blockchainAmountToFloat(d?.debtAmount, debtAsset);
+            return Number.isFinite(debt) && debt > maxPerOp;
+        });
+        if (oversized.length === 0) return null;
+
+        // T3: Use canonical settle-delay resolution matching dexbot_maintenance_runtime.ts
+        const settleDelay = Number.isFinite(TIMING.BLOCKCHAIN_SETTLE_DELAY_MS)
+            ? Math.max(0, TIMING.BLOCKCHAIN_SETTLE_DELAY_MS)
+            : 6_000;
+
+        // T4: Hard cap on pieces per cycle so the watchdog interval is never exceeded
+        const MAX_PIECES_PER_CYCLE = Number.isFinite(TIMING.CREDIT_DEAL_SPLIT_MAX_PIECES)
+            ? Math.max(0, TIMING.CREDIT_DEAL_SPLIT_MAX_PIECES)
+            : 48;
+
+        const configuredCollateralAssetId = collateralAsset.id;
+        const posKey = configuredCollateralAssetId
+            ? this._positionKey(assetId, configuredCollateralAssetId)
+            : assetId;
+        let prevPieceAt = 0;
+        let totalPiecesThisCycle = 0;
+
+        for (const deal of oversized) {
+            const dealId = String(deal.id);
+            let currentDeal = deal;
+
+            const dealDebt = blockchainAmountToFloat(currentDeal.debtAmount, debtAsset);
+            if (!Number.isFinite(dealDebt) || dealDebt <= maxPerOp) continue;
+
+            // Check min_deal_amount on the offer to avoid reborrows that would fail.
+            // Note: _getOfferById caches the offer for the runtime lifetime — if the
+            // offer's min_deal_amount changes on-chain mid-split, the guard uses the
+            // stale cached value. Risk is low in practice (offers rarely change this).
+            const dealOffer = await this._getOfferById(parseDealSummary(currentDeal)?.offerId);
+            const minDealAmount = toFiniteNumber(dealOffer?.min_deal_amount, null);
+            const numPieces = Math.ceil(dealDebt / maxPerOp);
+            const pieceAmount = roundToDecimals(dealDebt / numPieces, debtAsset.precision);
+            if (minDealAmount !== null && pieceAmount < blockchainToFloat(minDealAmount, debtAsset.precision)) {
+                this.warn(`credit runtime: cannot split deal ${dealId} — piece amount ${pieceAmount} below min_deal_amount ${blockchainToFloat(minDealAmount, debtAsset.precision)} for offer ${dealOffer?.id}`);
+                continue;
+            }
+
+            const dealPieces = Math.min(numPieces - 1, MAX_PIECES_PER_CYCLE - totalPiecesThisCycle);
+            if (dealPieces <= 0) {
+                const remainingDeals = oversized.length - oversized.indexOf(deal) - 1;
+                this.warn(`credit runtime: hit cap (${MAX_PIECES_PER_CYCLE}); deferring deal ${dealId} and ${remainingDeals} other deal(s)`);
+                break;
+            }
+            if (dealPieces < numPieces - 1) {
+                this.warn(`credit runtime: splitting only ${dealPieces} of ${numPieces - 1} pieces for deal ${dealId} this cycle (cap: ${MAX_PIECES_PER_CYCLE})`);
+            }
+
+            for (let i = 0; i < dealPieces; i++) {
+                // T1: Abort on shutdown during settle delay
+                if (prevPieceAt > 0) {
+                    await new Promise((resolve, reject) => {
+                        const t = setTimeout(resolve, settleDelay);
+                        if (this.bot?._shuttingDown) {
+                            clearTimeout(t);
+                            reject(new Error('shutting down'));
+                        }
+                    });
+                }
+
+                // Re-fetch deal from current state (may have been refreshed by repayCreditDeal)
+                const pos = this.state.positions?.[posKey];
+                const refreshed = Array.isArray(pos?.creditDeals)
+                    ? pos.creditDeals.find((d) => String(d.id) === dealId)
+                    : null;
+                if (!refreshed) {
+                    this.warn(`credit runtime: deal ${dealId} (asset ${assetId}) vanished during restructure`);
+                    break;
+                }
+                currentDeal = refreshed;
+
+                const remaining = blockchainAmountToFloat(currentDeal.debtAmount, debtAsset);
+                if (!Number.isFinite(remaining) || remaining <= maxPerOp) break;
+
+                const currentPiece = Math.min(pieceAmount, remaining - maxPerOp);
+                if (currentPiece <= 0) break;
+
+                this.log(`credit runtime: splitting deal ${dealId}: repaying ${currentPiece} of ${remaining} debt (piece ${i + 1}/${dealPieces})`);
+
+                await this.repayCreditDeal(currentDeal, currentPiece, {
+                    autoReborrow: true,
+                    specificPolicy: lendingItem,
+                    fillLockAlreadyHeld: runtimeContext?.options?.fillLockAlreadyHeld === true,
+                });
+
+                prevPieceAt = Date.now();
+                totalPiecesThisCycle++;
+            }
+        }
+
+        if (prevPieceAt > 0) {
+            // N3: skip heavy refresh on cap-exit — repayCreditDeal already called refreshState
+            if (totalPiecesThisCycle < MAX_PIECES_PER_CYCLE) {
+                await this.refreshCreditState({}, lendingItem);
+            }
+            const gridResult = await this._checkGridMaintenanceAfterCreditUpdate('credit restructure', {
+                fillLockAlreadyHeld: runtimeContext?.options?.fillLockAlreadyHeld === true,
+            });
+            return { action: 'restructured', gridMaintenanceResult: gridResult };
+        }
+        return null;
+    }
+
     async _getDealById(dealId) {
         if (!dealId) return null;
         const deals = Array.isArray(this.state.creditDeals) ? this.state.creditDeals : [];
@@ -2644,6 +2793,16 @@ class CreditRuntime {
         const posState = this.state.positions[posKey];
         if (!posState) return null;
 
+        // Phase 0: Split oversized credit deals that exceed maxBorrowAmountPerOperation
+        try {
+            const splitResult = await this._splitOversizedCreditDeals(lendingItem, assetId, posState, runtimeContext);
+            if (splitResult) {
+                this.log(`credit runtime: restructured oversized deals for ${assetId}`);
+            }
+        } catch (err: any) {
+            this.warn(`credit runtime: deal restructuring failed: ${err.message}`);
+        }
+
         let activeDealIds = new Set((posState.creditDeals || []).map((d) => String(d?.id)).filter(Boolean));
 
         for (const deal of (posState.creditDeals || [])) {

modules/types.ts

@@ -1005,6 +1005,12 @@ export interface LendingEntryBase {
   ratio?: number;
   outputWeight?: number;
   maxBorrowAmount?: number;
+  /** Max debt per single borrow operation (per-op cap, independent of
+   * maxBorrowAmount's total ceiling). When a deal exceeds this, maintenance
+   * splits it into equal pieces ≤ this value via repay+reborrow cycles with
+   * 6s spacing. Only applies to `creditOffer` type; `mpa` uses the same
+   * field to cap one-shot debt increases in CR-adjustment plans. */
+  maxBorrowAmountPerOperation?: number;
   maxCollateralAmount?: number | string;
   minCollateralIncreaseThreshold?: number | string;
   maxCollateralRatio?: number;