perp-cli 0.3.3

package/dist/__tests__/integration/response-shapes.integration.test.js

@@ -0,0 +1,278 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { HyperliquidAdapter } from "../../exchanges/hyperliquid.js";
+import { fetchAllDexAssets, findDexArbPairs, scanDexArb, } from "../../dex-asset-map.js";
+import { startEventStream } from "../../event-stream.js";
+/**
+ * Integration tests: validate that ALL API response shapes match what
+ * user-facing code expects.
+ *
+ * Hits real Hyperliquid mainnet API (read-only, no private key needed).
+ * Catches shape mismatches between live API data and our TypeScript interfaces.
+ *
+ * Run:
+ *   pnpm --filter perp-cli test -- --testPathPattern response-shapes.integration
+ */
+// Dummy private key for read-only operations (never signs anything)
+const DUMMY_KEY = "0x" + "1".repeat(64);
+/**
+ * Find a market by base symbol, handling possible suffixes (e.g., "BTC-PERP").
+ * The SDK may return symbols with or without a -PERP suffix depending on version.
+ */
+function findMarket(markets, base) {
+    return (markets.find((m) => m.symbol === base) ??
+        markets.find((m) => m.symbol === `${base}-PERP`) ??
+        markets.find((m) => m.symbol.toUpperCase().startsWith(base.toUpperCase())));
+}
+describe("Response Shape Validation (Hyperliquid Mainnet)", () => {
+    let adapter;
+    beforeAll(async () => {
+        adapter = new HyperliquidAdapter(DUMMY_KEY, false);
+        await adapter.init();
+    }, 30000);
+    // ── 1. ExchangeMarketInfo shape ──────────────────────────────────────
+    describe("1. ExchangeMarketInfo shape", () => {
+        it("every market has all required fields with correct types", async () => {
+            const markets = await adapter.getMarkets();
+            expect(markets.length).toBeGreaterThanOrEqual(10);
+            // BTC and ETH must be present (may have -PERP suffix)
+            const btc = findMarket(markets, "BTC");
+            const eth = findMarket(markets, "ETH");
+            expect(btc).toBeTruthy();
+            expect(eth).toBeTruthy();
+            for (const m of markets) {
+                // symbol: non-empty string
+                expect(typeof m.symbol).toBe("string");
+                expect(m.symbol.length).toBeGreaterThan(0);
+                // markPrice: string, parseable as number > 0
+                expect(typeof m.markPrice).toBe("string");
+                const mark = Number(m.markPrice);
+                expect(Number.isNaN(mark)).toBe(false);
+                expect(mark).toBeGreaterThan(0);
+                // indexPrice: string
+                expect(typeof m.indexPrice).toBe("string");
+                // fundingRate: string, parseable as number
+                expect(typeof m.fundingRate).toBe("string");
+                const funding = Number(m.fundingRate);
+                expect(Number.isNaN(funding)).toBe(false);
+                // volume24h: string
+                expect(typeof m.volume24h).toBe("string");
+                // openInterest: string
+                expect(typeof m.openInterest).toBe("string");
+                // maxLeverage: number > 0
+                expect(typeof m.maxLeverage).toBe("number");
+                expect(m.maxLeverage).toBeGreaterThan(0);
+            }
+        }, 30000);
+    });
+    // ── 2. Orderbook shape ───────────────────────────────────────────────
+    describe("2. ExchangeOrder shape (getOrderbook)", () => {
+        it("BTC orderbook has correct bid/ask tuple structure", async () => {
+            const book = await adapter.getOrderbook("BTC");
+            // bids and asks are arrays
+            expect(Array.isArray(book.bids)).toBe(true);
+            expect(Array.isArray(book.asks)).toBe(true);
+            // Both have entries
+            expect(book.bids.length).toBeGreaterThan(0);
+            expect(book.asks.length).toBeGreaterThan(0);
+            // Each entry is a [price, size] tuple of strings
+            for (const [price, size] of book.bids) {
+                expect(typeof price).toBe("string");
+                expect(typeof size).toBe("string");
+                expect(Number.isNaN(Number(price))).toBe(false);
+                expect(Number.isNaN(Number(size))).toBe(false);
+            }
+            for (const [price, size] of book.asks) {
+                expect(typeof price).toBe("string");
+                expect(typeof size).toBe("string");
+                expect(Number.isNaN(Number(price))).toBe(false);
+                expect(Number.isNaN(Number(size))).toBe(false);
+            }
+            // Spread is positive: best bid < best ask
+            const bestBid = Number(book.bids[0][0]);
+            const bestAsk = Number(book.asks[0][0]);
+            expect(bestBid).toBeLessThan(bestAsk);
+        }, 30000);
+    });
+    // ── 3. HIP-3 Deployed Dexes shape ───────────────────────────────────
+    describe("3. HIP-3 Deployed Dexes shape", () => {
+        it("listDeployedDexes returns correctly shaped dex entries", async () => {
+            const dexes = await adapter.listDeployedDexes();
+            expect(Array.isArray(dexes)).toBe(true);
+            expect(dexes.length).toBeGreaterThanOrEqual(3);
+            for (const dex of dexes) {
+                // name: non-empty string
+                expect(typeof dex.name).toBe("string");
+                expect(dex.name.length).toBeGreaterThan(0);
+                // assets: string array with length > 0
+                expect(Array.isArray(dex.assets)).toBe(true);
+                expect(dex.assets.length).toBeGreaterThan(0);
+                for (const asset of dex.assets) {
+                    expect(typeof asset).toBe("string");
+                }
+            }
+            // Known dex "xyz" is present
+            const xyz = dexes.find((d) => d.name === "xyz");
+            expect(xyz).toBeTruthy();
+            // Asset names from deployed dexes contain ":" prefix (e.g., "xyz:TSLA")
+            for (const dex of dexes) {
+                for (const asset of dex.assets) {
+                    expect(asset).toContain(":");
+                }
+            }
+        }, 30000);
+    });
+    // ── 4. DexAsset shape from fetchAllDexAssets ─────────────────────────
+    describe("4. DexAsset shape from fetchAllDexAssets", () => {
+        let allAssets;
+        beforeAll(async () => {
+            allAssets = await fetchAllDexAssets();
+        }, 30000);
+        it("every asset has all required fields with correct types", () => {
+            expect(allAssets.length).toBeGreaterThan(200);
+            for (const asset of allAssets) {
+                // raw: non-empty string
+                expect(typeof asset.raw).toBe("string");
+                expect(asset.raw.length).toBeGreaterThan(0);
+                // base: non-empty string
+                expect(typeof asset.base).toBe("string");
+                expect(asset.base.length).toBeGreaterThan(0);
+                // dex: non-empty string
+                expect(typeof asset.dex).toBe("string");
+                expect(asset.dex.length).toBeGreaterThan(0);
+                // markPrice: number > 0
+                expect(typeof asset.markPrice).toBe("number");
+                expect(asset.markPrice).toBeGreaterThan(0);
+                // fundingRate: number (not NaN)
+                expect(typeof asset.fundingRate).toBe("number");
+                expect(Number.isNaN(asset.fundingRate)).toBe(false);
+                // maxLeverage: number
+                expect(typeof asset.maxLeverage).toBe("number");
+                // openInterest: number
+                expect(typeof asset.openInterest).toBe("number");
+                // volume24h: number
+                expect(typeof asset.volume24h).toBe("number");
+                // szDecimals: number >= 0
+                expect(typeof asset.szDecimals).toBe("number");
+                expect(asset.szDecimals).toBeGreaterThanOrEqual(0);
+            }
+        });
+        it("assets come from at least 4 different dexes", () => {
+            const dexes = new Set(allAssets.map((a) => a.dex));
+            expect(dexes.size).toBeGreaterThanOrEqual(4);
+        });
+    });
+    // ── 5. DexArbPair shape from findDexArbPairs ────────────────────────
+    describe("5. DexArbPair shape from findDexArbPairs", () => {
+        it("TSLA pairs across dexes have correct shape and constraints", async () => {
+            const allAssets = await fetchAllDexAssets();
+            const tslaAssets = allAssets.filter((a) => a.base === "TSLA");
+            // TSLA should exist on multiple dexes
+            expect(tslaAssets.length).toBeGreaterThanOrEqual(2);
+            const pairs = findDexArbPairs(tslaAssets);
+            expect(pairs.length).toBeGreaterThanOrEqual(1);
+            for (const pair of pairs) {
+                // underlying: string
+                expect(typeof pair.underlying).toBe("string");
+                expect(pair.underlying).toBe("TSLA");
+                // long and short: DexAsset objects
+                expect(pair.long).toBeTruthy();
+                expect(pair.short).toBeTruthy();
+                expect(typeof pair.long.dex).toBe("string");
+                expect(typeof pair.short.dex).toBe("string");
+                // long.dex !== short.dex
+                expect(pair.long.dex).not.toBe(pair.short.dex);
+                // priceGapPct < 5 (same underlying, prices should be close)
+                expect(pair.priceGapPct).toBeLessThan(5);
+                // annualSpread: reasonable number (not NaN, not Infinity)
+                expect(typeof pair.annualSpread).toBe("number");
+                expect(Number.isNaN(pair.annualSpread)).toBe(false);
+                expect(Number.isFinite(pair.annualSpread)).toBe(true);
+            }
+        }, 30000);
+    });
+    // ── 6. scanDexArb full pipeline ──────────────────────────────────────
+    describe("6. scanDexArb full pipeline", () => {
+        it("returns sorted array with valid pairs", async () => {
+            const pairs = await scanDexArb({ minAnnualSpread: 5 });
+            expect(Array.isArray(pairs)).toBe(true);
+            // Sorted by annualSpread descending
+            for (let i = 1; i < pairs.length; i++) {
+                expect(pairs[i].annualSpread).toBeLessThanOrEqual(pairs[i - 1].annualSpread);
+            }
+            // Every pair has all required fields and no same-dex pairs
+            for (const pair of pairs) {
+                expect(typeof pair.underlying).toBe("string");
+                expect(pair.underlying.length).toBeGreaterThan(0);
+                expect(pair.long).toBeTruthy();
+                expect(pair.short).toBeTruthy();
+                expect(pair.long.dex).not.toBe(pair.short.dex);
+                expect(typeof pair.annualSpread).toBe("number");
+                expect(pair.annualSpread).toBeGreaterThanOrEqual(5);
+                expect(Number.isFinite(pair.annualSpread)).toBe(true);
+                expect(typeof pair.priceGapPct).toBe("number");
+                expect(Number.isFinite(pair.priceGapPct)).toBe(true);
+            }
+        }, 30000);
+    });
+    // ── 7. Event stream shape (single poll cycle) ───────────────────────
+    describe("7. Event stream shape (single poll cycle)", () => {
+        it("emits correctly shaped events without crashing", async () => {
+            const events = [];
+            const controller = new AbortController();
+            // Run a single poll cycle then abort
+            const streamPromise = startEventStream(adapter, {
+                intervalMs: 100_000, // large interval so we only get one poll
+                onEvent: (event) => {
+                    events.push(event);
+                },
+                signal: controller.signal,
+            });
+            // Wait briefly for the initial poll to complete, then abort
+            await new Promise((resolve) => setTimeout(resolve, 5000));
+            controller.abort();
+            // Wait for the stream to finish
+            await streamPromise;
+            // With a dummy key, positions/orders may be empty but the poll should
+            // complete without crashing. Any emitted events must conform to shape.
+            for (const event of events) {
+                // type: valid EventType string
+                expect(typeof event.type).toBe("string");
+                expect(event.type.length).toBeGreaterThan(0);
+                // exchange: string
+                expect(typeof event.exchange).toBe("string");
+                expect(event.exchange).toBe("hyperliquid");
+                // timestamp: ISO format string
+                expect(typeof event.timestamp).toBe("string");
+                expect(new Date(event.timestamp).toISOString()).toBe(event.timestamp);
+                // data: object
+                expect(typeof event.data).toBe("object");
+                expect(event.data).not.toBeNull();
+            }
+        }, 30000);
+    });
+    // ── 8. Funding rate / price sanity checks ────────────────────────────
+    describe("8. Funding rate and price sanity checks", () => {
+        it("BTC and ETH have reasonable funding rates and prices", async () => {
+            const markets = await adapter.getMarkets();
+            // Handle possible -PERP suffix from SDK
+            const btc = findMarket(markets, "BTC");
+            const eth = findMarket(markets, "ETH");
+            expect(btc).toBeTruthy();
+            expect(eth).toBeTruthy();
+            // BTC funding rate between -0.01 and 0.01 (1% per period is extreme)
+            const btcFunding = Number(btc.fundingRate);
+            expect(btcFunding).toBeGreaterThan(-0.01);
+            expect(btcFunding).toBeLessThan(0.01);
+            // ETH funding rate between -0.01 and 0.01
+            const ethFunding = Number(eth.fundingRate);
+            expect(ethFunding).toBeGreaterThan(-0.01);
+            expect(ethFunding).toBeLessThan(0.01);
+            // BTC mark price > $100 (catches off-by-order-of-magnitude parsing bugs)
+            const btcPrice = Number(btc.markPrice);
+            expect(btcPrice).toBeGreaterThan(100);
+            // ETH mark price > $10
+            const ethPrice = Number(eth.markPrice);
+            expect(ethPrice).toBeGreaterThan(10);
+        }, 30000);
+    });
+});

package/dist/__tests__/liquidity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/liquidity.test.js

@@ -0,0 +1,225 @@
+import { describe, it, expect, vi } from "vitest";
+import { computeExecutableSize, checkArbLiquidity } from "../liquidity.js";
+// ──────────────────────────────────────────────
+// computeExecutableSize — orderbook walking
+// ──────────────────────────────────────────────
+describe("computeExecutableSize — empty book", () => {
+    it("returns zeroed result for empty levels", () => {
+        const result = computeExecutableSize([], 1000);
+        expect(result.maxSize).toBe(0);
+        expect(result.avgFillPrice).toBe(0);
+        expect(result.slippagePct).toBe(0);
+        expect(result.depthUsd).toBe(0);
+        expect(result.canFillFull).toBe(false);
+        expect(result.recommendedSize).toBe(0);
+    });
+});
+describe("computeExecutableSize — single level", () => {
+    it("fills entirely from one level when sufficient", () => {
+        // One level at $100, size 100 = $10,000 USD. Request $500.
+        const result = computeExecutableSize([["100", "100"]], 500);
+        expect(result.maxSize).toBeCloseTo(5); // $500 / $100
+        expect(result.avgFillPrice).toBeCloseTo(100);
+        expect(result.slippagePct).toBeCloseTo(0);
+        expect(result.canFillFull).toBe(true);
+        expect(result.depthUsd).toBeCloseTo(10000);
+    });
+    it("partially fills when level is insufficient", () => {
+        // One level at $100, size 2 = $200 USD. Request $500.
+        const result = computeExecutableSize([["100", "2"]], 500);
+        expect(result.maxSize).toBeCloseTo(2);
+        expect(result.avgFillPrice).toBeCloseTo(100);
+        // Can't fill 95% → canFillFull = false
+        expect(result.canFillFull).toBe(false);
+        expect(result.depthUsd).toBeCloseTo(200);
+    });
+});
+describe("computeExecutableSize — multiple levels", () => {
+    it("walks through levels to fill requested size", () => {
+        // Use prices well within slippage tolerance (default 0.5%)
+        // bestPrice = 100, slippageLimit = 100.5
+        // All prices must be <= 100.5 to not be stopped by slippage check
+        const levels = [
+            ["100", "5"], // $500
+            ["100.2", "5"], // $501 — well within 0.5% of $100
+            ["100.4", "10"], // $1004 — also within 0.5%
+        ];
+        // Request $1000. Level 1: $500 fully consumed (5 units).
+        // Level 2: remaining $500, levelUsd $501 > $500, partial fill: 500/100.2 ≈ 4.99 units.
+        const result = computeExecutableSize(levels, 1000);
+        expect(result.maxSize).toBeCloseTo(5 + 500 / 100.2, 2);
+        expect(result.canFillFull).toBe(true);
+        expect(result.avgFillPrice).toBeCloseTo(1000 / result.maxSize, 2);
+        expect(result.slippagePct).toBeGreaterThan(0);
+        expect(result.slippagePct).toBeLessThan(0.5);
+    });
+    it("computes slippage as avg fill vs best price", () => {
+        // Use wider slippage tolerance (5%) so all levels are included
+        const levels = [
+            ["1000", "0.1"], // $100
+            ["1010", "0.1"], // $101
+            ["1020", "10"], // $10,200
+        ];
+        // With 5% tolerance, slippageLimit = 1000 * 1.05 = 1050
+        // All levels are within tolerance.
+        // Request $10,000. Level 1: $100 (fully consumed). Level 2: $101 (fully consumed).
+        // Level 3: remaining = $9799, levelUsd = $10200 > remaining → partial fill.
+        const result = computeExecutableSize(levels, 10000, 5);
+        // Most of the fill happens at $1020
+        expect(result.avgFillPrice).toBeGreaterThan(1000);
+        // slippagePct = abs((avgFillPrice - 1000) / 1000) * 100
+        expect(result.slippagePct).toBeGreaterThan(1);
+        expect(result.slippagePct).toBeLessThan(3);
+    });
+    it("stops walking when slippage limit is exceeded", () => {
+        const levels = [
+            ["100", "1"], // $100
+            ["100.4", "1"], // $100.40 — within 0.5%
+            ["101", "100"], // $10,100 — 1% above best, exceeds 0.5% default
+        ];
+        // Request $5000 with default 0.5% slippage.
+        // slippageLimit = 100 * (1 + 0.5/100) = 100.5
+        // Level 1: $100 (consumed), level 2: $100.4 (consumed), level 3: $101 > $100.5 → stop
+        const result = computeExecutableSize(levels, 5000, 0.5);
+        // Should only consume levels 1 and 2
+        expect(result.maxSize).toBeCloseTo(2);
+        expect(result.canFillFull).toBe(false);
+    });
+    it("respects custom slippage tolerance", () => {
+        const levels = [
+            ["100", "1"],
+            ["102", "100"], // 2% above best
+        ];
+        // With 3% tolerance, level 2 is within range
+        const result = computeExecutableSize(levels, 5000, 3);
+        expect(result.canFillFull).toBe(true);
+        expect(result.maxSize).toBeGreaterThan(1);
+    });
+    it("considers canFillFull at 95% threshold", () => {
+        // Need $1000. If we fill $950, canFillFull = true (95%)
+        const levels = [
+            ["100", "9.5"], // $950
+        ];
+        const result = computeExecutableSize(levels, 1000);
+        expect(result.canFillFull).toBe(true);
+        // Need $1000. If we fill $940, canFillFull = false (94%)
+        const levels2 = [
+            ["100", "9.4"], // $940
+        ];
+        const result2 = computeExecutableSize(levels2, 1000);
+        expect(result2.canFillFull).toBe(false);
+    });
+});
+describe("computeExecutableSize — depth calculation", () => {
+    it("accumulates total depth across all iterated levels", () => {
+        const levels = [
+            ["100", "10"], // $1000
+            ["101", "10"], // $1010
+            ["102", "10"], // $1020
+        ];
+        // Request $500. Level 1 has $1000 > $500, so partial fill on level 1.
+        // But the loop: totalDepthUsd is accumulated BEFORE checking remainingUsd.
+        // So level 1: totalDepthUsd += $1000, then fills $500 partial, then remainingUsd = 0.
+        // Level 2: totalDepthUsd += $1010 (accumulated before the break on remainingUsd <= 0).
+        // Actually: after level 1 fill, filledNotional = $500, so remainingUsd = 0 → breaks at start of level 2.
+        // Wait — let's trace: for level 1, totalDepthUsd += 1000, price 100 not > slippageLimit,
+        // remaining = 500, levelUsd = 1000 > 500 → partial fill. filledNotional = 500.
+        // Next iteration level 2: totalDepthUsd += 1010, then remaining = 500 - 500 = 0 → break.
+        // So totalDepthUsd = 1000 + 1010 = 2010.
+        const result = computeExecutableSize(levels, 500);
+        expect(result.depthUsd).toBeCloseTo(2010);
+        // But only $500 was actually filled from level 1
+        expect(result.maxSize).toBeCloseTo(5); // 500 / 100
+        expect(result.canFillFull).toBe(true);
+    });
+});
+// ──────────────────────────────────────────────
+// checkArbLiquidity — cross-exchange check
+// ──────────────────────────────────────────────
+function mockAdapter(name, asks, bids) {
+    return {
+        name,
+        getOrderbook: vi.fn().mockResolvedValue({ asks, bids }),
+        getMarkets: vi.fn().mockResolvedValue([]),
+        getBalance: vi.fn().mockResolvedValue({ equity: "1000", available: "800", marginUsed: "200", unrealizedPnl: "0" }),
+        getPositions: vi.fn().mockResolvedValue([]),
+        getOpenOrders: vi.fn().mockResolvedValue([]),
+        getOrderHistory: vi.fn().mockResolvedValue([]),
+        getTradeHistory: vi.fn().mockResolvedValue([]),
+        getRecentTrades: vi.fn().mockResolvedValue([]),
+        getFundingHistory: vi.fn().mockResolvedValue([]),
+        getFundingPayments: vi.fn().mockResolvedValue([]),
+        getKlines: vi.fn().mockResolvedValue([]),
+        marketOrder: vi.fn().mockResolvedValue({}),
+        limitOrder: vi.fn().mockResolvedValue({}),
+        editOrder: vi.fn().mockResolvedValue({}),
+        cancelOrder: vi.fn().mockResolvedValue({}),
+        cancelAllOrders: vi.fn().mockResolvedValue({}),
+        setLeverage: vi.fn().mockResolvedValue({}),
+        stopOrder: vi.fn().mockResolvedValue({}),
+    };
+}
+describe("checkArbLiquidity", () => {
+    it("returns viable when both sides have sufficient liquidity", async () => {
+        const longAdapter = mockAdapter("exchange-a", [["60000", "10"], ["60010", "10"]], // asks
+        [["59990", "10"]]);
+        const shortAdapter = mockAdapter("exchange-b", [["60005", "10"]], // asks
+        [["59995", "10"], ["59985", "10"]]);
+        const result = await checkArbLiquidity(longAdapter, shortAdapter, "BTC", 1000);
+        expect(result.viable).toBe(true);
+        expect(result.adjustedSizeUsd).toBeGreaterThan(0);
+        expect(result.adjustedSizeUsd).toBeLessThanOrEqual(1000);
+    });
+    it("returns not viable when liquidity is too thin (less than 20% of requested)", async () => {
+        const longAdapter = mockAdapter("exchange-a", [["60000", "0.001"]], // asks: ~$60
+        [["59990", "1"]]);
+        const shortAdapter = mockAdapter("exchange-b", [["60005", "1"]], [["59995", "0.001"]]);
+        // Request $10000. Both sides have ~$60 → way below 20% = $2000 threshold
+        const result = await checkArbLiquidity(longAdapter, shortAdapter, "BTC", 10000);
+        expect(result.viable).toBe(false);
+        expect(result.adjustedSizeUsd).toBe(0);
+    });
+    it("returns not viable when cross-exchange price gap exceeds 2%", async () => {
+        const longAdapter = mockAdapter("exchange-a", [["60000", "100"]], // asks
+        [["59900", "100"]]);
+        const shortAdapter = mockAdapter("exchange-b", [["62000", "100"]], // asks
+        [["61500", "100"]]);
+        const result = await checkArbLiquidity(longAdapter, shortAdapter, "BTC", 1000);
+        expect(result.viable).toBe(false);
+    });
+    it("adjusts size down when one side has limited liquidity", async () => {
+        const longAdapter = mockAdapter("exchange-a", [["60000", "0.05"]], // asks: $3000
+        [["59990", "10"]]);
+        const shortAdapter = mockAdapter("exchange-b", [["60010", "10"]], [["59995", "10"]]);
+        // Request $5000. Long side only has $3000 on asks.
+        const result = await checkArbLiquidity(longAdapter, shortAdapter, "BTC", 5000);
+        expect(result.viable).toBe(true);
+        expect(result.adjustedSizeUsd).toBeLessThan(5000);
+        expect(result.adjustedSizeUsd).toBeGreaterThan(0);
+    });
+    it("returns not viable when orderbook fetch fails", async () => {
+        const longAdapter = mockAdapter("exchange-a", [], []);
+        longAdapter.getOrderbook = vi.fn().mockRejectedValue(new Error("timeout"));
+        const shortAdapter = mockAdapter("exchange-b", [], []);
+        const result = await checkArbLiquidity(longAdapter, shortAdapter, "BTC", 1000);
+        expect(result.viable).toBe(false);
+        expect(result.adjustedSizeUsd).toBe(0);
+    });
+    it("invokes log callback for diagnostics", async () => {
+        const longAdapter = mockAdapter("exchange-a", [["60000", "0.001"]], // tiny asks
+        [["59990", "1"]]);
+        const shortAdapter = mockAdapter("exchange-b", [["60005", "1"]], [["59995", "0.001"]]);
+        const logFn = vi.fn();
+        await checkArbLiquidity(longAdapter, shortAdapter, "BTC", 10000, 0.5, logFn);
+        expect(logFn).toHaveBeenCalled();
+        expect(logFn.mock.calls[0][0]).toContain("[LIQ]");
+    });
+    it("caps adjusted size to requested size when liquidity is ample", async () => {
+        const longAdapter = mockAdapter("exchange-a", [["60000", "100"]], // $6M asks
+        [["59990", "100"]]);
+        const shortAdapter = mockAdapter("exchange-b", [["60005", "100"]], [["59995", "100"]]);
+        const result = await checkArbLiquidity(longAdapter, shortAdapter, "BTC", 1000);
+        expect(result.viable).toBe(true);
+        expect(result.adjustedSizeUsd).toBeLessThanOrEqual(1000);
+    });
+});

package/dist/__tests__/plan-executor.test.d.ts

@@ -0,0 +1 @@
+export {};