@reefclaw/openclaw-plugin 0.1.12 → 0.1.13

package/tools/get-risk-summary.js

@@ -2,6 +2,26 @@
 // Returns exposure, drawdown, heat score, position count — everything
 // the agent needs for risk-aware decision making.
 import { getQuoteBalance, getQuoteWalletBalance } from '../balance-utils.js';
+/** Finite number or undefined — never NaN, never a silent 0. */
+function fin(v) {
+    if (v === undefined || v === null || v === '')
+        return undefined;
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+/** Round for display without ever throwing.
+ *
+ *  ★ This tool is read-only observability — it must DEGRADE, never crash. It used
+ *  to call `.toFixed()` straight on adapter fields, and on Hyperliquid live
+ *  (where ccxt leaves `markPrice` undefined) that took the whole tool down with
+ *  `Cannot read properties of undefined (reading 'toFixed')` — the agent lost its
+ *  entire risk read because one display field was absent. The venue-side root
+ *  cause is fixed in `venues/hyperliquid/hl-position.ts`; this is the backstop
+ *  for every other adapter/field. */
+function round(v, dp) {
+    const n = fin(v);
+    return n === undefined ? 0 : +n.toFixed(dp);
+}
 export async function getRiskSummaryTool(_args, deps) {
     // In live modes, use real exchange data instead of simulator
     let balance;
@@ -27,23 +47,41 @@ export async function getRiskSummaryTool(_args, deps) {
     let longExposure = 0;
     let shortExposure = 0;
     let totalUnrealizedPnl = 0;
+    const dataWarnings = [];
     const positionDetails = positions.map((pos) => {
-        const notional = Math.abs(pos.notional);
+        const entryPrice = fin(pos.entryPrice);
+        const rawMark = fin(pos.markPrice);
+        // Same convention as pre-trade-check / create-order: an absent mark falls
+        // back to entry (a $0 mark would read as a total loss), and we say so.
+        const markPrice = rawMark ?? entryPrice;
+        if (rawMark === undefined) {
+            dataWarnings.push(`${pos.symbol}: mark price unavailable from the exchange — entry price substituted (uPnL/exposure may be stale)`);
+        }
+        if (entryPrice === undefined) {
+            dataWarnings.push(`${pos.symbol}: entry price unavailable from the exchange`);
+        }
+        const quantity = fin(pos.contracts) ?? 0;
+        const rawNotional = fin(pos.notional);
+        const notional = rawNotional !== undefined ? Math.abs(rawNotional) : Math.abs(quantity * (markPrice ?? 0));
+        const unrealizedPnl = fin(pos.unrealizedPnl);
+        if (unrealizedPnl === undefined) {
+            dataWarnings.push(`${pos.symbol}: unrealized PnL unavailable from the exchange — counted as 0`);
+        }
         grossExposure += notional;
         if (pos.side === 'long')
             longExposure += notional;
         else
             shortExposure += notional;
-        totalUnrealizedPnl += pos.unrealizedPnl;
+        totalUnrealizedPnl += unrealizedPnl ?? 0;
         return {
             symbol: pos.symbol,
             side: pos.side,
-            quantity: pos.contracts,
-            entryPrice: +pos.entryPrice.toFixed(2),
-            markPrice: +pos.markPrice.toFixed(2),
-            notional: +notional.toFixed(2),
-            unrealizedPnl: +pos.unrealizedPnl.toFixed(2),
-            portfolioPercent: totalEquity > 0 ? +((notional / totalEquity) * 100).toFixed(1) : 0,
+            quantity,
+            entryPrice: round(entryPrice, 2),
+            markPrice: round(markPrice, 2),
+            notional: round(notional, 2),
+            unrealizedPnl: round(unrealizedPnl, 2),
+            portfolioPercent: totalEquity > 0 ? round((notional / totalEquity) * 100, 1) : 0,
         };
     });
     const netExposure = longExposure - shortExposure;
@@ -76,10 +114,10 @@ export async function getRiskSummaryTool(_args, deps) {
     const executionStats = execStats && execStats.totalTrades > 0
         ? {
             totalTrades: execStats.totalTrades,
-            avgSlippageBps: +execStats.avgSlippageBps.toFixed(2),
-            worstSlippageBps: +execStats.worstSlippageBps.toFixed(2),
-            totalFeesPaid: +execStats.totalFeesPaid.toFixed(2),
-            avgLatencyMs: +execStats.avgLatencyMs.toFixed(0),
+            avgSlippageBps: round(execStats.avgSlippageBps, 2),
+            worstSlippageBps: round(execStats.worstSlippageBps, 2),
+            totalFeesPaid: round(execStats.totalFeesPaid, 2),
+            avgLatencyMs: round(execStats.avgLatencyMs, 0),
         }
         : undefined;
     // Shadow metrics (Phase 9b)
@@ -89,8 +127,8 @@ export async function getRiskSummaryTool(_args, deps) {
         const upgrade = deps.shadowTracker.isReadyForUpgrade();
         shadowMetrics = {
             totalShadowTrades: sm.totalShadowTrades,
-            avgDeltaBps: +sm.avgDeltaBps.toFixed(2),
-            worstDeltaBps: +sm.worstDeltaBps.toFixed(2),
+            avgDeltaBps: round(sm.avgDeltaBps, 2),
+            worstDeltaBps: round(sm.worstDeltaBps, 2),
             tradingDays: sm.tradingDays,
             readyForUpgrade: upgrade.ready,
             upgradeBlockers: upgrade.reasons,
@@ -98,21 +136,22 @@ export async function getRiskSummaryTool(_args, deps) {
     }
     return {
         tradingMode: deps.tradingMode ?? 'PAPER',
-        totalEquity: +totalEquity.toFixed(2),
-        availableBalance: +availableBalance.toFixed(2),
-        lockedBalance: +lockedBalance.toFixed(2),
-        grossExposure: +grossExposure.toFixed(2),
-        grossExposurePercent: +grossExposurePercent.toFixed(1),
-        netExposure: +netExposure.toFixed(2),
-        netExposurePercent: +netExposurePercent.toFixed(1),
+        totalEquity: round(totalEquity, 2),
+        availableBalance: round(availableBalance, 2),
+        lockedBalance: round(lockedBalance, 2),
+        grossExposure: round(grossExposure, 2),
+        grossExposurePercent: round(grossExposurePercent, 1),
+        netExposure: round(netExposure, 2),
+        netExposurePercent: round(netExposurePercent, 1),
         positionCount: positions.length,
-        unrealizedPnl: +totalUnrealizedPnl.toFixed(2),
-        unrealizedPnlPercent: +unrealizedPnlPercent.toFixed(2),
+        unrealizedPnl: round(totalUnrealizedPnl, 2),
+        unrealizedPnlPercent: round(unrealizedPnlPercent, 2),
         positions: positionDetails,
         heatScore,
         heatLevel,
         executionStats,
         shadowMetrics,
+        ...(dataWarnings.length > 0 ? { dataWarnings } : {}),
         timestamp: new Date().toISOString(),
     };
 }

package/venues/hyperliquid/hl-bracket-coordinator.d.ts

@@ -58,6 +58,10 @@ export interface HlCoordinatorOpts {
     sleep?: (ms: number) => Promise<void>;
 }
 export declare function isTerminalBracketState(state: BracketState): boolean;
+/** A batch item HL rejected. ccxt types status as open|closed|canceled, but a
+ *  per-item rejection surfaces as an `error` entry in the raw batch response
+ *  (`info.error`) — check both shapes rather than trust the narrow type. */
+export declare function isRejectedOrder(o: CcxtOrder | undefined | null): boolean;
 export declare class HlBracketCoordinator extends EventEmitter {
     private readonly executor;
     private readonly ledger;

package/venues/hyperliquid/hl-bracket-coordinator.js

@@ -46,10 +46,10 @@ const TRIGGERED_STATUSES = new Set(['filled', 'triggered']);
 /** A batch item HL rejected. ccxt types status as open|closed|canceled, but a
  *  per-item rejection surfaces as an `error` entry in the raw batch response
  *  (`info.error`) — check both shapes rather than trust the narrow type. */
-function isRejectedOrder(o) {
+export function isRejectedOrder(o) {
     if (!o)
         return true;
-    if (String(o.status ?? '') === 'rejected')
+    if (String(o.status ?? '').toLowerCase() === 'rejected')
         return true;
     const info = o.info;
     return Boolean(info && info.error);

package/venues/hyperliquid/hl-live-adapter.d.ts

@@ -76,6 +76,10 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
      * ★ null ≠ empty: a FAILED position fetch throws (state unknown — closing
      * against an unknown book could open a NEW position in the opposite direction);
      * a CONFIRMED-flat account is a benign no-op.
+     *
+     * ★ Success requires CONFIRMED flat: brackets/ledger are only cleaned up after
+     * a post-close position read shows zero — a rejected/partial IOC throws with
+     * protection left in place.
      */
     closePosition(symbol: string, _closeReason?: CloseReason): Promise<CcxtOrder>;
     getBalance(): Promise<CcxtBalance>;

package/venues/hyperliquid/hl-live-adapter.js

@@ -36,7 +36,7 @@ import { buildHlOrderCloid, parseHlBracketCloid } from './hl-cloid.js';
 import { BracketLedger } from '../../live/bracket-ledger.js';
 import { generateBracketId } from '../../live/bracket-id.js';
 import { validateStopDirection, validateTargetDirection } from '../../live/bracket-params.js';
-import { HlBracketCoordinator, isTerminalBracketState } from './hl-bracket-coordinator.js';
+import { HlBracketCoordinator, isRejectedOrder, isTerminalBracketState, } from './hl-bracket-coordinator.js';
 import { HyperliquidUserStream } from './hl-user-stream.js';
 import { formatError } from '../../logger.js';
 const TAG = 'hl-live-adapter';
@@ -420,6 +420,10 @@ export class HyperliquidLiveAdapter extends EventEmitter {
      * ★ null ≠ empty: a FAILED position fetch throws (state unknown — closing
      * against an unknown book could open a NEW position in the opposite direction);
      * a CONFIRMED-flat account is a benign no-op.
+     *
+     * ★ Success requires CONFIRMED flat: brackets/ledger are only cleaned up after
+     * a post-close position read shows zero — a rejected/partial IOC throws with
+     * protection left in place.
      */
     async closePosition(symbol, _closeReason) {
         const positions = await this.api.fetchPositions(symbol);
@@ -456,10 +460,34 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         });
         if (!order)
             throw new Error(`closePosition(${symbol}) returned no order`);
-        // Ledger hygiene: mark the bracket row terminal. T-1 auto-cancels the
-        // exchange legs when the position goes flat, so this is bookkeeping (plus
-        // a harmless defensive cancel), never load-bearing. Fire-and-forget — a
-        // close must never fail on ledger cleanup.
+        if (isRejectedOrder(order)) {
+            throw new Error(`closePosition(${symbol}): close order REJECTED by the exchange — position still open, ` +
+                'protection left in place. Retry the close.');
+        }
+        // ★ An IOC acknowledgement is NOT a fill: the slippage-bounded close can
+        // partially fill (or fill nothing) in a fast market. Confirm flat from
+        // exchange truth BEFORE touching protection — cancelling the brackets on a
+        // live residual would strip its only stop (no watcher fallback on HL live)
+        // AND terminalize the ledger row, hiding the residual from the truth-check
+        // sweep forever (audit 2026-07-26 F3).
+        const after = await this.api.fetchPositions(symbol);
+        if (after === null) {
+            logger.warn(TAG, `closePosition(${symbol}): post-close position read FAILED — flat UNCONFIRMED; leaving ` +
+                'protection + ledger row in place (T-1 auto-cancels legs on flat; the truth-check ' +
+                'sweep reconciles the row either way)');
+            return order;
+        }
+        const residualPos = after.find((p) => p.symbol?.startsWith(symbol.split(':')[0]));
+        const residual = Math.abs(Number(residualPos?.contracts ?? 0));
+        if (residual > 0) {
+            throw new Error(`closePosition(${symbol}): IOC close did NOT fully fill — residual ${residual} still open, ` +
+                'protection left in place (the truth-check sweep resizes the legs to the residual). ' +
+                'Retry the close.');
+        }
+        // Confirmed flat. Ledger hygiene: mark the bracket row terminal. T-1
+        // auto-cancels the exchange legs when the position goes flat, so this is
+        // bookkeeping (plus a harmless defensive cancel), never load-bearing.
+        // Fire-and-forget — a close must never fail on ledger cleanup.
         const row = this.getHlBracketCoordinator().getLedger().getBySymbol(symbol);
         if (row && !isTerminalBracketState(row.state)) {
             void this.getHlBracketCoordinator()
@@ -608,6 +636,16 @@ export class HyperliquidLiveAdapter extends EventEmitter {
             // added size stays naked until the caller retries (truth-check sweep).
             throw new Error(`resizeBrackets(${args.symbol}): submission returned nothing — old legs left in place`);
         }
+        const rejected = submitted.filter((order) => isRejectedOrder(order));
+        if (submitted.length !== plan.submit.length || rejected.length > 0) {
+            // A batch-level acknowledgement does not mean every leg was accepted:
+            // Hyperliquid reports individual failures in each order's raw
+            // `info.error`. Keep every known-good old leg live and leave the ledger
+            // untouched so the truth-check sweep can retry with fresh cloids.
+            throw new Error(`resizeBrackets(${args.symbol}): batch returned ${submitted.length}/${plan.submit.length} legs` +
+                (rejected.length > 0 ? ` (${rejected.length} rejected)` : '') +
+                ' — old legs left in place');
+        }
         for (const cloid of plan.cancelCloids) {
             // Register BEFORE the request: the WS 'canceled' event can beat the
             // ledger update and must not read as stripped protection (canary).

package/venues/hyperliquid/hl-order.d.ts

@@ -0,0 +1,35 @@
+import type { CcxtOrder } from '../../types.js';
+/**
+ * Collapse HL/ccxt order-type strings into the declared `'market' | 'limit'`
+ * union. HL order types are all execution-styles of one of the two: anything
+ * containing "market" ('Market', 'Stop Market', 'Take Profit Market') executes
+ * as a market when it goes; everything else — including a missing type, which
+ * only occurs on RESTING rows (a market order never rests) — is a limit.
+ * The raw subtype stays readable at `info.orderType`.
+ */
+export declare function normalizeHlOrderType(raw: unknown): 'market' | 'limit';
+/**
+ * Collapse order statuses into `'open' | 'closed' | 'canceled'`.
+ *
+ * ccxt's parseOrderStatus already maps filled→closed, triggered→open,
+ * marginCanceled/liquidatedCanceled→canceled — but lets 'rejected' (and any
+ * future HL status) through verbatim. Directional rule for the residue:
+ *   - 'rejected' and any '*canceled' variant → 'canceled' (positively terminal,
+ *     nothing was or will be executed);
+ *   - 'filled' → 'closed' (in case a raw status bypasses ccxt's map);
+ *   - anything UNKNOWN → 'open' + WARN. 'open' is the conservative direction on
+ *     both consumer classes: destructive bracket decisions treat the leg as
+ *     still live (never "gone" on a guess — the null≠empty doctrine), and the
+ *     entry-order poller just keeps polling into its own timeout.
+ */
+export declare function normalizeHlOrderStatus(raw: unknown): 'open' | 'closed' | 'canceled';
+/**
+ * Normalize one ccxt HL order into a contract-compliant `CcxtOrder`.
+ *
+ * Unlike positions (where a fabricated number is a risk-limit hazard and an
+ * unpriceable row nulls the snapshot), an order row is never dropped: the
+ * fields we default (fee 0, cost from average×filled) are display/accounting
+ * conveniences, while the fields decisions hang on (id, cloid, status, info)
+ * are passed through or conservatively mapped.
+ */
+export declare function normalizeHlOrder(raw: CcxtOrder, nowMs?: number): CcxtOrder;

package/venues/hyperliquid/hl-order.js

@@ -0,0 +1,123 @@
+// Hyperliquid order normalization — brings ccxt's HL order rows up to the
+// `CcxtOrder` contract, the sibling of hl-position.ts (see its header for the
+// class of bug: ccxt emits fields our types declare required as undefined, and
+// TypeScript never checks runtime shapes).
+//
+// What ccxt@4.5.x's hyperliquid `parseOrder` actually emits (verified offline
+// against the real parser, 2026-07-26, surfaced by hl-venue-conformance.test.ts):
+//   - `cost: undefined`, `fee: undefined` (HL carries fees on FILLS only, never
+//     on order objects) — our contract requires both.
+//   - `type: 'take profit market'` / `'take profit limit'` pass straight through
+//     `parseOrderType` (only 'stop limit'/'stop market' are mapped) — outside
+//     our `'market' | 'limit'` union. A resting limit with no `orderType` field
+//     yields `type: undefined`.
+//   - `status: 'rejected'` survives `parseOrderStatus` — outside our
+//     `'open' | 'closed' | 'canceled'` union.
+//   - `average: undefined`, `timeInForce: undefined` on trigger legs.
+//
+// ★ SCOPE: READ paths only (`fetchOpenOrders`, `fetchOrder`). Submit-path
+//   responses (`submitOrder`/`submitOrders`) are deliberately NOT normalized —
+//   `HlBracketCoordinator.isRejectedOrder` keys on the raw `status: 'rejected'`
+//   sentinel there, and blurring it into 'canceled' would break per-item batch
+//   rejection detection.
+//
+// ★ WHAT MUST SURVIVE VERBATIM: `info` (skill-side protective classification
+//   reads `info.orderType` — 'Take Profit Market' etc — via isProtectiveOrder/
+//   classifyProtectiveRole) and `clientOrderId` (bracket reconciliation parses
+//   the cloid). The conformance suite pins both.
+import { logger } from '../../logger.js';
+const TAG = 'hl-order';
+/** HL's settlement asset — the only fee currency on this venue. */
+const HL_FEE_CURRENCY = 'USDC';
+/** Finite number or undefined — never NaN, never a silent 0. */
+function fin(v) {
+    if (v === undefined || v === null || v === '')
+        return undefined;
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+/**
+ * Collapse HL/ccxt order-type strings into the declared `'market' | 'limit'`
+ * union. HL order types are all execution-styles of one of the two: anything
+ * containing "market" ('Market', 'Stop Market', 'Take Profit Market') executes
+ * as a market when it goes; everything else — including a missing type, which
+ * only occurs on RESTING rows (a market order never rests) — is a limit.
+ * The raw subtype stays readable at `info.orderType`.
+ */
+export function normalizeHlOrderType(raw) {
+    const t = String(raw ?? '').toLowerCase();
+    return t.includes('market') ? 'market' : 'limit';
+}
+/**
+ * Collapse order statuses into `'open' | 'closed' | 'canceled'`.
+ *
+ * ccxt's parseOrderStatus already maps filled→closed, triggered→open,
+ * marginCanceled/liquidatedCanceled→canceled — but lets 'rejected' (and any
+ * future HL status) through verbatim. Directional rule for the residue:
+ *   - 'rejected' and any '*canceled' variant → 'canceled' (positively terminal,
+ *     nothing was or will be executed);
+ *   - 'filled' → 'closed' (in case a raw status bypasses ccxt's map);
+ *   - anything UNKNOWN → 'open' + WARN. 'open' is the conservative direction on
+ *     both consumer classes: destructive bracket decisions treat the leg as
+ *     still live (never "gone" on a guess — the null≠empty doctrine), and the
+ *     entry-order poller just keeps polling into its own timeout.
+ */
+export function normalizeHlOrderStatus(raw) {
+    const s = String(raw ?? '').trim();
+    if (s === 'open' || s === 'closed' || s === 'canceled')
+        return s;
+    const lower = s.toLowerCase();
+    if (lower === 'rejected' || lower.endsWith('canceled') || lower.endsWith('cancelled')) {
+        return 'canceled';
+    }
+    if (lower === 'filled')
+        return 'closed';
+    logger.warn(TAG, `unknown HL order status '${s}' — treating as 'open' (not confirmed terminal)`);
+    return 'open';
+}
+/**
+ * Normalize one ccxt HL order into a contract-compliant `CcxtOrder`.
+ *
+ * Unlike positions (where a fabricated number is a risk-limit hazard and an
+ * unpriceable row nulls the snapshot), an order row is never dropped: the
+ * fields we default (fee 0, cost from average×filled) are display/accounting
+ * conveniences, while the fields decisions hang on (id, cloid, status, info)
+ * are passed through or conservatively mapped.
+ */
+export function normalizeHlOrder(raw, nowMs = Date.now()) {
+    const r = raw;
+    const amount = fin(r.amount) ?? 0;
+    const filledRaw = fin(r.filled);
+    const remainingRaw = fin(r.remaining);
+    const filled = filledRaw ?? (remainingRaw !== undefined ? Math.max(0, amount - remainingRaw) : 0);
+    const remaining = remainingRaw ?? Math.max(0, amount - filled);
+    const average = fin(r.average) ?? null;
+    const price = fin(r.price) ?? null;
+    const cost = fin(r.cost) ?? (average !== null ? average * filled : 0);
+    const fee = r.fee && typeof r.fee === 'object' && Number.isFinite(r.fee.cost)
+        ? r.fee
+        : { cost: 0, currency: HL_FEE_CURRENCY };
+    const timestamp = fin(r.timestamp) ?? nowMs;
+    return {
+        ...raw,
+        id: String(r.id ?? ''),
+        type: normalizeHlOrderType(
+        // Prefer the raw venue subtype — ccxt's unified type may already be
+        // collapsed ('stop market'→'market') or missing; info.orderType is the
+        // authoritative HL string when present.
+        r.info?.orderType ?? r.type),
+        status: normalizeHlOrderStatus(r.status),
+        amount,
+        filled,
+        remaining,
+        average,
+        price,
+        cost,
+        fee,
+        timeInForce: typeof r.timeInForce === 'string' && r.timeInForce.length > 0 ? r.timeInForce : 'GTC',
+        timestamp,
+        datetime: typeof r.datetime === 'string' && r.datetime.length > 0
+            ? r.datetime
+            : new Date(timestamp).toISOString(),
+    };
+}

package/venues/hyperliquid/hl-position.d.ts

@@ -0,0 +1,36 @@
+import type { CcxtPosition } from '../../types.js';
+/** The raw `assetPositions[].position` payload ccxt passes through at
+ *  `position.info.position` (fields per the info-endpoint docs, §3.6 of the
+ *  integration plan). */
+export interface HlRawPositionInfo {
+    coin?: string;
+    /** Signed size — negative for a short. */
+    szi?: string | number;
+    entryPx?: string | number;
+    unrealizedPnl?: string | number;
+    /** |szi| × mark. */
+    positionValue?: string | number;
+}
+/**
+ * Mark price for an HL position, derived from the position payload alone.
+ *
+ * Primary route inverts the documented uPnl formula; secondary route divides
+ * `positionValue` by |szi|. Returns undefined rather than a guess when neither
+ * route yields a positive price.
+ */
+export declare function deriveHlMarkPrice(args: {
+    entryPrice?: number;
+    unrealizedPnl?: number;
+    /** Signed size (negative = short). */
+    signedSize?: number;
+    positionValue?: number;
+}): number | undefined;
+/**
+ * Normalize one ccxt HL position into a contract-compliant `CcxtPosition`.
+ *
+ * Returns **null** when the row cannot be priced or sized — the caller must then
+ * treat the whole snapshot as UNKNOWN (`null`), not drop the row: a silently
+ * missing position is exactly the "empty ≠ unknown" collapse that drove the
+ * naked-bracket incidents on the Binance side.
+ */
+export declare function normalizeHlPosition(raw: CcxtPosition | null | undefined, nowMs?: number): CcxtPosition | null;

package/venues/hyperliquid/hl-position.js

@@ -0,0 +1,127 @@
+// Hyperliquid position normalization — brings ccxt's HL position rows up to the
+// `CcxtPosition` contract the rest of the plugin treats as REQUIRED numbers.
+//
+// ★ WHY THIS FILE EXISTS (the bug it fixes, 2026-07-26): ccxt@4.5.x's hyperliquid
+//   `parsePosition` sets `markPrice: undefined` (hyperliquid.js:3603), plus
+//   `contractSize`/`timestamp`/`datetime: undefined` — and `safePosition()` fills
+//   none of them. `CcxtPosition` declares all four as non-optional numbers, so
+//   every consumer that trusts the type broke on an HL LIVE position:
+//     - `get_risk_summary` threw `Cannot read properties of undefined (reading
+//       'toFixed')` on `+pos.markPrice.toFixed(2)` (the reported symptom),
+//     - `get_wave9_status` / `live-account-capture` reject the position as
+//       non-finite, `stop-watcher` / `modify_stop` / `modify_target` read a
+//       `undefined` reference price, and `pre-trade-check` / `create-order`
+//       silently fall back to entryPrice (stale exposure + stop-distance math).
+//   Fixing it at this boundary fixes all of them at once — which is why the
+//   normalization lives here (the single choke point every HL position read
+//   passes through) and not in the individual tools.
+//
+// ★ THE MARK DERIVATION IS DOC-EXACT AND COSTS NO NETWORK CALL.
+//   `clearinghouseState` carries NO per-position mark price — markPx lives only in
+//   `metaAndAssetCtxs` (weight 20), so ccxt has nothing to parse and a naive fix
+//   would put a heavy call on a per-tick read path (the rule from
+//   memory/project_hl_venue_scoped_scan_jul13: never put a heavy HL info call on a
+//   poll path). Instead we invert Hyperliquid's own documented formula:
+//
+//     "Unrealized pnl is defined as `side * (mark_price - entry_price) *
+//      position_size`"  — hyperliquid.gitbook.io → Trading → Entry price and pnl
+//                          (verified 2026-07-26)
+//
+//   With `szi` the SIGNED size (side × size) that inverts exactly to
+//       mark = entryPx + unrealizedPnl / szi
+//   and the docs' own example confirms both this and the secondary route:
+//       szi 0.0335, entryPx 2986.3, uPnl −0.0134 → mark 2985.9
+//       positionValue 100.02765 / 0.0335        → mark 2985.9  ✓ (|szi| × mark)
+//
+// ★ NEVER FABRICATE. A row we cannot price returns null and the CALLER turns the
+//   whole snapshot into null ("unknown"), never a partial list and never a $0
+//   mark — a phantom zero mark reads as a total loss and would trip risk limits.
+/** Finite number or undefined — never NaN, never a silent 0. */
+function fin(v) {
+    if (v === undefined || v === null || v === '')
+        return undefined;
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+/**
+ * Mark price for an HL position, derived from the position payload alone.
+ *
+ * Primary route inverts the documented uPnl formula; secondary route divides
+ * `positionValue` by |szi|. Returns undefined rather than a guess when neither
+ * route yields a positive price.
+ */
+export function deriveHlMarkPrice(args) {
+    const { entryPrice, unrealizedPnl, signedSize, positionValue } = args;
+    // Primary: mark = entry + uPnl / szi  (exact inverse of the documented
+    // uPnl = side * (mark - entry) * size). Also correct when uPnl is 0 — a
+    // freshly-filled position marks at its entry.
+    if (entryPrice !== undefined &&
+        entryPrice > 0 &&
+        unrealizedPnl !== undefined &&
+        signedSize !== undefined &&
+        signedSize !== 0) {
+        const mark = entryPrice + unrealizedPnl / signedSize;
+        if (Number.isFinite(mark) && mark > 0)
+            return mark;
+    }
+    // Secondary: positionValue = |szi| × mark.
+    if (positionValue !== undefined &&
+        positionValue > 0 &&
+        signedSize !== undefined &&
+        signedSize !== 0) {
+        const mark = positionValue / Math.abs(signedSize);
+        if (Number.isFinite(mark) && mark > 0)
+            return mark;
+    }
+    return undefined;
+}
+/**
+ * Normalize one ccxt HL position into a contract-compliant `CcxtPosition`.
+ *
+ * Returns **null** when the row cannot be priced or sized — the caller must then
+ * treat the whole snapshot as UNKNOWN (`null`), not drop the row: a silently
+ * missing position is exactly the "empty ≠ unknown" collapse that drove the
+ * naked-bracket incidents on the Binance side.
+ */
+export function normalizeHlPosition(raw, nowMs = Date.now()) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const info = raw.info?.position;
+    const signedFromInfo = fin(info?.szi);
+    const contracts = fin(raw.contracts) ?? (signedFromInfo === undefined ? undefined : Math.abs(signedFromInfo));
+    if (contracts === undefined || contracts <= 0)
+        return null;
+    const side = raw.side === 'short' || (raw.side === undefined && signedFromInfo !== undefined && signedFromInfo < 0)
+        ? 'short'
+        : 'long';
+    const signedSize = signedFromInfo ?? (side === 'short' ? -contracts : contracts);
+    const entryPrice = fin(raw.entryPrice) ?? fin(info?.entryPx);
+    if (entryPrice === undefined || entryPrice <= 0)
+        return null;
+    // HL always sends unrealizedPnl for an open position; 0 is the neutral value
+    // for the impossible branch (it makes the primary mark route degrade to
+    // "marks at entry" rather than inventing a price).
+    const unrealizedPnl = fin(raw.unrealizedPnl) ?? fin(info?.unrealizedPnl) ?? 0;
+    const positionValue = fin(raw.notional) ?? fin(info?.positionValue);
+    const markPrice = fin(raw.markPrice) ??
+        deriveHlMarkPrice({ entryPrice, unrealizedPnl, signedSize, positionValue });
+    if (markPrice === undefined || markPrice <= 0)
+        return null;
+    const notional = positionValue ?? Math.abs(contracts * markPrice);
+    const timestamp = fin(raw.timestamp) ?? nowMs;
+    return {
+        ...raw,
+        side,
+        contracts,
+        contractSize: fin(raw.contractSize) ?? 1, // HL perps: 1 coin per contract
+        entryPrice,
+        markPrice,
+        notional,
+        unrealizedPnl,
+        percentage: fin(raw.percentage) ?? 0,
+        timestamp,
+        datetime: typeof raw.datetime === 'string' && raw.datetime.length > 0
+            ? raw.datetime
+            : new Date(timestamp).toISOString(),
+    };
+}

package/venues/hyperliquid/hl-private.d.ts

@@ -49,16 +49,33 @@ export declare class HyperliquidPrivateApi {
     getExchange(): any;
     loadMarkets(): Promise<boolean>;
     /** Positions for the MASTER account. `null` = fetch failed (state unknown);
-     *  `[]` = the exchange confirmed flat. */
+     *  `[]` = the exchange confirmed flat.
+     *
+     *  ★ Rows are normalized through `normalizeHlPosition` — ccxt leaves
+     *  `markPrice`/`contractSize`/`timestamp`/`datetime` UNDEFINED on this venue
+     *  (clearinghouseState carries no markPx) while `CcxtPosition` declares them
+     *  required, which crashed `get_risk_summary` and degraded every other
+     *  mark-reading consumer. See hl-position.ts for the doc-exact derivation.
+     *  A row that cannot be priced makes the WHOLE snapshot null (unknown) — never
+     *  a partial list, never a fabricated zero. */
     fetchPositions(symbol?: string): Promise<CcxtPosition[] | null>;
     /** Open orders INCLUDING trigger/TPSL legs. CCXT's HL `fetchOpenOrders`
      *  defaults to `frontendOpenOrders`, which is the only endpoint that returns
-     *  trigger orders (plan §3.6) — the analog of Binance's merged algo endpoints. */
+     *  trigger orders (plan §3.6) — the analog of Binance's merged algo endpoints.
+     *
+     *  ★ Rows are normalized through `normalizeHlOrder` (ccxt leaves cost/fee/
+     *  average/timeInForce undefined and leaks 'take profit market' past the
+     *  type union — see hl-order.ts); `info` + `clientOrderId` survive verbatim
+     *  (protective classification + bracket reconciliation read them). */
     fetchOpenOrders(symbol?: string): Promise<CcxtOrder[] | null>;
     fetchBalance(): Promise<CcxtBalance | null>;
     /** Per-order status — the liveness resolver's REST tier (Tier 2 of the
      *  3-tier rule). Weight 2. `null` = lookup FAILED (unknown), which callers
-     *  must treat as "do not act", NOT as "gone". */
+     *  must treat as "do not act", NOT as "gone".
+     *
+     *  Normalized like fetchOpenOrders. Unknown statuses collapse to 'open'
+     *  (= not confirmed terminal — the conservative direction for both the
+     *  liveness resolver and the entry poller); raw status stays in `info`. */
     fetchOrder(orderId: string, symbol?: string): Promise<CcxtOrder | null>;
     /** Own fills. WS is the authoritative ingress (plan + the audit-trail rule);
      *  this is the gap-fill/truth-check path. NOTE: only the 10,000 most recent