@reefclaw/openclaw-plugin 0.1.5 → 0.1.7

package/venues/hyperliquid/hl-brackets.js

@@ -0,0 +1,172 @@
+// Hyperliquid bracket mechanics (plan §5.7) — written against MEASURED behavior,
+// not assumptions. The testnet run of 2026-07-12 (docs/CLAUDE/hyperliquid.md
+// §"Testnet verification results") settled the two questions this file turns on:
+//
+//   ★ T-1 — GOOD NEWS. Standalone (grouping `na`) reduce-only trigger legs
+//     AUTO-CANCEL when the position goes flat (~2.7s, zero residuals), and when
+//     ONE leg triggers the SIBLING SELF-CANCELS (OCO-like, ≤5.6s). HL cleans up
+//     after itself like Binance's algo orders, so BracketManager needs NO bespoke
+//     sibling-canceller. A defensive cancel stays harmless (idempotent) but is not
+//     load-bearing.
+//
+//   ★ T-2 — THE HAZARD. `grouping:'positionTpsl'` is NOT reachable through ccxt's
+//     params passthrough (it silently produced an ordinary `isPositionTpsl:false`
+//     leg), and leg sizes DO NOT follow a scale-in: after doubling a position the
+//     stop stayed at the ORIGINAL size. Binance legs use `closePosition:true`
+//     (inherently whole-position); HL legs are FIXED SIZE. Therefore:
+//
+//       ⇒ EVERY scale-in MUST resize the protective legs, or the added size is
+//         NAKED. `planResize()` is that requirement in code and
+//         `bracketCoversPosition()` is the invariant the auditor enforces.
+//
+// Everything here is PURE — it computes plans (what to submit, what to cancel);
+// the adapter executes them. Safety logic stays unit-testable without a network.
+import { buildHlBracketCloid } from './hl-cloid.js';
+/** HL sizes are rounded to szDecimals, so an exact float compare would false-flag
+ *  a correctly-sized leg. Below this, a gap is rounding dust, not exposure. */
+const COVERAGE_EPSILON = 1e-8;
+/** Plan a fresh bracket for a filled entry. */
+export function planBracket(args) {
+    const closeSide = args.positionSide === 'long' ? 'sell' : 'buy';
+    const legs = [];
+    if (args.stopPrice !== undefined) {
+        legs.push({
+            role: 'stop',
+            triggerPrice: args.stopPrice,
+            size: args.positionSize,
+            cloid: buildHlBracketCloid(args.bracketId, 'stop'),
+        });
+    }
+    if (args.targetPrice !== undefined) {
+        legs.push({
+            role: 'target',
+            triggerPrice: args.targetPrice,
+            size: args.positionSize,
+            cloid: buildHlBracketCloid(args.bracketId, 'target'),
+        });
+    }
+    return { bracketId: args.bracketId, symbol: args.symbol, closeSide, legs };
+}
+/** Build the submit-requests for a plan.
+ *
+ *  Both legs go out as ONE `createOrders` batch: one signed action, one nonce (a
+ *  same-ms nonce collision is a real HL failure mode), costing 1 IP weight unit
+ *  but 2 ADDRESS actions (the rate gate counts both).
+ *
+ *  Legs are reduce-only trigger-market orders. HL triggers fire on MARK price only
+ *  — stop-distance validation upstream must therefore use mark, never last. */
+export function buildBracketOrders(plan) {
+    return plan.legs.map((leg) => ({
+        symbol: plan.symbol,
+        side: plan.closeSide,
+        type: 'market',
+        amount: leg.size,
+        // A trigger-market leg still needs a price for ccxt's slippage bound; the
+        // trigger price is the natural reference (the leg only executes there).
+        price: leg.triggerPrice,
+        reduceOnly: true,
+        cloid: leg.cloid,
+        trigger: {
+            triggerPrice: leg.triggerPrice,
+            tpsl: leg.role === 'stop' ? 'sl' : 'tp',
+        },
+    }));
+}
+/** ★ THE T-2 INVARIANT — do the live legs cover the whole position?
+ *
+ *  On HL a protective leg is a FIXED SIZE, so a scale-in silently leaves the added
+ *  contracts unprotected unless the legs are resized. A `covered:false` result is
+ *  a safety-floor breach (naked size), not cosmetic drift. */
+export function bracketCoversPosition(args) {
+    const shortfall = { stop: 0, target: 0 };
+    const missing = [];
+    for (const role of ['stop', 'target']) {
+        const legs = args.liveLegs.filter((l) => l.role === role);
+        if (legs.length === 0) {
+            missing.push(role);
+            continue;
+        }
+        const coveredSize = legs.reduce((sum, l) => sum + l.size, 0);
+        const gap = args.positionSize - coveredSize;
+        if (gap > COVERAGE_EPSILON)
+            shortfall[role] = gap;
+    }
+    const covered = shortfall.stop <= COVERAGE_EPSILON &&
+        shortfall.target <= COVERAGE_EPSILON &&
+        // A missing STOP is never "covered" — that is the naked-position case. A
+        // missing TARGET is a policy choice (requireTakeProfit can be off), so it is
+        // reported in `missing` but does not by itself fail coverage.
+        !missing.includes('stop');
+    return { covered, shortfall, missing };
+}
+/** ★ Resize protective legs after a scale-in (or any position-size change).
+ *
+ *  HL gives us no in-place resize primitive we can trust (`modify` carries an
+ *  `always_place` footgun the plan forbids, and positionTpsl auto-sizing is
+ *  unreachable via ccxt — T-2). So the honest sequence is CANCEL + REPLACE, and
+ *  the order matters:
+ *
+ *    Cancel-then-place opens a brief unprotected window; place-then-cancel would
+ *    double-protect (two reduce-only legs summing to 2× the position — the excess
+ *    is harmless because reduce-only can never flip a position, and HL cancels the
+ *    stragglers when flat). We therefore SUBMIT FIRST, then cancel the stale legs:
+ *    over-protection for a few hundred ms beats a naked window. The caller is
+ *    expected to execute `submit` before `cancelCloids`.
+ *
+ *  Fresh cloids are generated for the new legs (a cloid is single-use), which is
+ *  also why the ledger keys on `bracketId`, not on a specific cloid. */
+export function planResize(args) {
+    const coverage = bracketCoversPosition({
+        positionSize: args.positionSize,
+        liveLegs: args.liveLegs,
+    });
+    // Nothing to do when every present leg already covers the position exactly.
+    const oversized = args.liveLegs.some((l) => l.size - args.positionSize > COVERAGE_EPSILON);
+    if (coverage.shortfall.stop <= COVERAGE_EPSILON &&
+        coverage.shortfall.target <= COVERAGE_EPSILON &&
+        !oversized) {
+        return { cancelCloids: [], submit: [], noop: true };
+    }
+    // Rebuild every PRESENT role at the correct size, preserving its trigger price.
+    const legs = [];
+    const cancelCloids = [];
+    for (const role of ['stop', 'target']) {
+        const existing = args.liveLegs.filter((l) => l.role === role);
+        if (existing.length === 0)
+            continue; // absent leg = attach path's job, not resize's
+        // Trigger price is preserved from the live leg (the agent's pinned plan) —
+        // resizing must NEVER silently move a stop.
+        const triggerPrice = existing[0].triggerPrice;
+        legs.push({
+            role,
+            triggerPrice,
+            size: args.positionSize,
+            cloid: buildHlBracketCloid(args.bracketId, role),
+        });
+        cancelCloids.push(...existing.map((l) => l.cloid));
+    }
+    const closeSide = args.positionSide === 'long' ? 'sell' : 'buy';
+    const submit = buildBracketOrders({
+        bracketId: args.bracketId,
+        symbol: args.symbol,
+        closeSide,
+        legs,
+    });
+    return { cancelCloids, submit, noop: submit.length === 0 };
+}
+/** Is this exchange order one of OUR protective legs?
+ *
+ *  The kill-switch's second layer (`OrderData.protective`) maps from this. It is
+ *  deliberately BROADER than "has one of our cloids": an externally-placed stop
+ *  must also survive a Kill. Mirrors the Binance rule (`reduceOnly || closePosition
+ *  || STOP/TAKE_PROFIT type`), translated to HL's fields. */
+export function isProtectiveHlOrder(order) {
+    if (order.reduceOnly === true)
+        return true;
+    if (order.isTrigger === true)
+        return true;
+    if (order.isPositionTpsl === true)
+        return true;
+    const t = (order.orderType ?? '').toLowerCase();
+    return t.includes('stop') || t.includes('take profit') || t.includes('tp');
+}

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

@@ -0,0 +1,22 @@
+import type { BracketId, BracketRole } from '../../live/bracket-types.js';
+/** Build the HL cloid for a bracket leg. Reuses the venue-neutral 16-hex
+ *  bracketId (same value the Binance cid carries) so the BracketLedger,
+ *  reconciler and journal stay venue-agnostic. */
+export declare function buildHlBracketCloid(bracketId: BracketId, role: BracketRole): string;
+/** Parse an HL cloid. Returns null for any non-bracket cloid — this is called on
+ *  EVERY order HL returns during reconciliation, so a null result is normal and
+ *  must never throw. */
+export declare function parseHlBracketCloid(cloid: string): {
+    bracketId: BracketId;
+    role: BracketRole;
+} | null;
+/** Cheap type-guard: is this one of OUR bracket cloids? */
+export declare function isHlBracketCloid(cloid: string): boolean;
+/** Is this a syntactically valid HL cloid at all (128-bit hex)? Used to reject
+ *  a Binance-shaped cid before it reaches the wire (HL returns a cryptic error
+ *  for malformed cloids). */
+export declare function isValidHlCloid(cloid: string): boolean;
+/** Non-bracket cloid for a plain (entry/close) order — lets every HL order carry
+ *  an idempotency key, exactly like the Binance path's clientOrderId. Distinct
+ *  magic ("ord") so it never parses as a bracket leg. */
+export declare function buildHlOrderCloid(): string;

package/venues/hyperliquid/hl-cloid.js

@@ -0,0 +1,82 @@
+// Hyperliquid bracket cloid scheme (plan §5.7).
+//
+// HL client order ids are **128-bit hex** (`0x` + exactly 32 hex chars) — NOT
+// free-form ASCII like Binance's `newClientOrderId`. So the Binance `bkt<16hex><role>`
+// scheme cannot be reused verbatim; it is RE-ENCODED into the 128-bit space:
+//
+//   0x  bc7  <role>  <16hex bracketId>  <12hex random>
+//   └┬┘ └┬┘  └──┬─┘  └──────┬────────┘  └─────┬──────┘
+//    │   │      │           │                 └── entropy (collision + opacity)
+//    │   │      │           └── the SAME bracketId the Binance scheme uses, so the
+//    │   │      │              ledger/reconciler stay venue-agnostic
+//    │   │      └── role nibble: e=entry, 5=stop, 7=target (hex-legal; 's'/'t' are not)
+//    │   └── magic "bc7" (bracket) — short on purpose, see below
+//    └── 0x prefix
+//
+//   3 + 1 + 16 + 12 = 32 hex chars. Exactly a valid cloid.
+//
+// ★ WHY THE MAGIC IS SHORT AND THE ENTROPY IS LONG. On Binance an EXTERNAL actor
+// with API access pattern-matched our `rc-` cids and auto-cancelled every order
+// carrying them (docs/BRACKET_CANCEL_ROOT_CAUSE_2026-05-16.md). The lesson carries
+// to any venue: a long, guessable, human-obvious prefix is an attack surface. Keep
+// the recognizable part minimal (we still need to reassemble brackets from the
+// exchange after a restart, with zero reliance on local state) and let the rest be
+// random.
+//
+// ★ RECOGNITION STAYS CENTRALIZED. docs/CLAUDE/brackets.md forbids a second
+// bracket-cid regex anywhere else in the codebase. This module is the HL half of
+// that rule; `live/bracket-id.ts:parseBracketClientId(venue, cid)` dispatches here.
+// Never inline `/^0xbc7/` in a caller.
+import { randomBytes } from 'node:crypto';
+/** 0x + bc7 + role-nibble + 16-hex bracketId + 12-hex entropy = 34 chars total. */
+const HL_CLOID_REGEX = /^0xbc7([e57])([0-9a-f]{16})([0-9a-f]{12})$/;
+/** Any well-formed HL cloid (128-bit hex), bracket or not. */
+const HL_CLOID_SHAPE = /^0x[0-9a-f]{32}$/;
+const ROLE_TO_NIBBLE = {
+    entry: 'e',
+    stop: '5',
+    target: '7',
+};
+const NIBBLE_TO_ROLE = {
+    e: 'entry',
+    '5': 'stop',
+    '7': 'target',
+};
+/** Build the HL cloid for a bracket leg. Reuses the venue-neutral 16-hex
+ *  bracketId (same value the Binance cid carries) so the BracketLedger,
+ *  reconciler and journal stay venue-agnostic. */
+export function buildHlBracketCloid(bracketId, role) {
+    if (!/^[0-9a-f]{16}$/.test(bracketId)) {
+        throw new Error(`Invalid bracketId: ${bracketId} — expected 16 hex chars`);
+    }
+    const entropy = randomBytes(6).toString('hex'); // 12 hex chars
+    return `0xbc7${ROLE_TO_NIBBLE[role]}${bracketId}${entropy}`;
+}
+/** Parse an HL cloid. Returns null for any non-bracket cloid — this is called on
+ *  EVERY order HL returns during reconciliation, so a null result is normal and
+ *  must never throw. */
+export function parseHlBracketCloid(cloid) {
+    if (typeof cloid !== 'string')
+        return null;
+    const m = HL_CLOID_REGEX.exec(cloid.toLowerCase());
+    if (!m)
+        return null;
+    return { bracketId: m[2], role: NIBBLE_TO_ROLE[m[1]] };
+}
+/** Cheap type-guard: is this one of OUR bracket cloids? */
+export function isHlBracketCloid(cloid) {
+    return typeof cloid === 'string' && HL_CLOID_REGEX.test(cloid.toLowerCase());
+}
+/** Is this a syntactically valid HL cloid at all (128-bit hex)? Used to reject
+ *  a Binance-shaped cid before it reaches the wire (HL returns a cryptic error
+ *  for malformed cloids). */
+export function isValidHlCloid(cloid) {
+    return typeof cloid === 'string' && HL_CLOID_SHAPE.test(cloid.toLowerCase());
+}
+/** Non-bracket cloid for a plain (entry/close) order — lets every HL order carry
+ *  an idempotency key, exactly like the Binance path's clientOrderId. Distinct
+ *  magic ("ord") so it never parses as a bracket leg. */
+export function buildHlOrderCloid() {
+    // 0x + "0d" (order) + 30 hex random = 32 hex chars.
+    return `0x0d${randomBytes(15).toString('hex')}`;
+}

package/venues/hyperliquid/hl-info-cache.d.ts

@@ -0,0 +1,46 @@
+import { type HlAssetRules, type HlValidationResult, type RoundDirection } from './hl-precision.js';
+interface MetaUniverseEntry {
+    name: string;
+    szDecimals: number;
+    maxLeverage?: number;
+    isDelisted?: boolean;
+}
+export declare class HyperliquidInfoCache {
+    private readonly fetchMeta;
+    private rules;
+    private loadedAt;
+    constructor(fetchMeta: () => Promise<{
+        universe?: MetaUniverseEntry[];
+    } | null>);
+    /** Load `meta.universe` → per-coin rules. Returns false on failure and KEEPS the
+     *  previous rules (a transient failure must not zero out the cache and start
+     *  rejecting every order). */
+    load(): Promise<boolean>;
+    get isStale(): boolean;
+    get size(): number;
+    /** Rules for a canonical symbol (BTC/USDC) or a bare coin (BTC). Coin names are
+     *  CASE-SENSITIVE on HL (kPEPE) — never uppercase the lookup key. */
+    getRules(symbolOrCoin: string): HlAssetRules | null;
+    /** Same contract as ExchangeInfoCache.validate — round, then check, and return
+     *  the rounded values the caller must actually submit. */
+    validate(args: {
+        symbol: string;
+        amount: number;
+        side: 'buy' | 'sell';
+        price?: number;
+        referencePrice?: number;
+    }): HlValidationResult;
+    /** Round a price for a symbol (direction explicit — a protective leg never
+     *  rounds "nearest"). Throws when the asset is unknown: a stop we cannot round
+     *  correctly must NOT be silently submitted at an unrounded price. */
+    roundPrice(symbol: string, price: number, dir: RoundDirection): number;
+    roundSize(symbol: string, size: number): number;
+    /** The IOC bound that emulates a market order. */
+    marketPrice(args: {
+        symbol: string;
+        side: 'buy' | 'sell';
+        referencePrice: number;
+        slippagePct: number;
+    }): number;
+}
+export {};

package/venues/hyperliquid/hl-info-cache.js

@@ -0,0 +1,125 @@
+// Hyperliquid asset-rules cache — the HL analog of `live/exchange-info-cache.ts`.
+//
+// Holds `szDecimals` + `assetIndex` + `maxLeverage` per coin, refreshed from
+// `meta` (weight 20) at boot and daily thereafter, and exposes the SAME
+// `validate()` contract the Binance cache exposes so the two adapters' call sites
+// stay symmetric (the shared contract suite depends on that symmetry).
+//
+// ★ NEVER hardcode an assetIndex. Indices are positional in `meta.universe` and
+//   DIFFER between mainnet and testnet ([asset-ids]). A hardcoded index is an
+//   order on the wrong coin.
+// ★ The rounding rule itself lives in `hl-precision.ts` — this module only
+//   supplies the per-asset inputs and caches them.
+import { logger } from '../../logger.js';
+import { toHyperliquidCoin } from '../symbols.js';
+import { validateHlOrder, roundHlPrice, roundHlSize, marketIocPrice, } from './hl-precision.js';
+const TAG = 'hl-info-cache';
+/** Refresh cadence — HL adds/removes perps and can change szDecimals on a
+ *  listing; daily matches the Binance exchangeInfo refresh. */
+const REFRESH_MS = 24 * 60 * 60 * 1000;
+export class HyperliquidInfoCache {
+    fetchMeta;
+    rules = new Map(); // keyed by COIN (case-sensitive)
+    loadedAt = 0;
+    constructor(fetchMeta) {
+        this.fetchMeta = fetchMeta;
+    }
+    /** Load `meta.universe` → per-coin rules. Returns false on failure and KEEPS the
+     *  previous rules (a transient failure must not zero out the cache and start
+     *  rejecting every order). */
+    async load() {
+        try {
+            const meta = await this.fetchMeta();
+            const universe = meta?.universe;
+            if (!Array.isArray(universe) || universe.length === 0) {
+                logger.error(TAG, 'meta.universe empty or unreadable — keeping previous rules');
+                return false;
+            }
+            const next = new Map();
+            universe.forEach((entry, index) => {
+                if (!entry?.name || typeof entry.szDecimals !== 'number')
+                    return;
+                if (entry.isDelisted)
+                    return; // never trade a delisted asset
+                next.set(entry.name, {
+                    szDecimals: entry.szDecimals,
+                    assetIndex: index, // ★ positional — this is the ONLY correct source
+                    maxLeverage: entry.maxLeverage,
+                });
+            });
+            if (next.size === 0) {
+                logger.error(TAG, 'meta.universe parsed to zero assets — keeping previous rules');
+                return false;
+            }
+            this.rules = next;
+            this.loadedAt = Date.now();
+            logger.info(TAG, `Loaded HL asset rules: ${next.size} coins`);
+            return true;
+        }
+        catch (err) {
+            logger.error(TAG, `load failed: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    }
+    get isStale() {
+        return this.loadedAt === 0 || Date.now() - this.loadedAt > REFRESH_MS;
+    }
+    get size() {
+        return this.rules.size;
+    }
+    /** Rules for a canonical symbol (BTC/USDC) or a bare coin (BTC). Coin names are
+     *  CASE-SENSITIVE on HL (kPEPE) — never uppercase the lookup key. */
+    getRules(symbolOrCoin) {
+        const coin = symbolOrCoin.includes('/')
+            ? toHyperliquidCoin(symbolOrCoin)
+            : symbolOrCoin;
+        return this.rules.get(coin) ?? null;
+    }
+    /** Same contract as ExchangeInfoCache.validate — round, then check, and return
+     *  the rounded values the caller must actually submit. */
+    validate(args) {
+        const rules = this.getRules(args.symbol);
+        if (!rules) {
+            return {
+                valid: false,
+                error: `Unknown Hyperliquid asset for ${args.symbol} — not in meta.universe ` +
+                    '(delisted, wrong network, or coin-name case mismatch).',
+                roundedAmount: 0,
+            };
+        }
+        return validateHlOrder({
+            amount: args.amount,
+            price: args.price,
+            referencePrice: args.referencePrice,
+            rules,
+            side: args.side,
+        });
+    }
+    /** Round a price for a symbol (direction explicit — a protective leg never
+     *  rounds "nearest"). Throws when the asset is unknown: a stop we cannot round
+     *  correctly must NOT be silently submitted at an unrounded price. */
+    roundPrice(symbol, price, dir) {
+        const rules = this.getRules(symbol);
+        if (!rules)
+            throw new Error(`Cannot round price for unknown HL asset ${symbol}`);
+        return roundHlPrice(price, rules.szDecimals, dir);
+    }
+    roundSize(symbol, size) {
+        const rules = this.getRules(symbol);
+        if (!rules)
+            throw new Error(`Cannot round size for unknown HL asset ${symbol}`);
+        return roundHlSize(size, rules.szDecimals);
+    }
+    /** The IOC bound that emulates a market order. */
+    marketPrice(args) {
+        const rules = this.getRules(args.symbol);
+        if (!rules)
+            throw new Error(`Cannot price market order for unknown HL asset ${args.symbol}`);
+        return marketIocPrice({
+            referencePrice: args.referencePrice,
+            side: args.side,
+            slippagePct: args.slippagePct,
+            szDecimals: rules.szDecimals,
+        });
+    }
+}

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

@@ -0,0 +1,146 @@
+import { EventEmitter } from 'node:events';
+import type { IExchangeAdapter, AdapterReadiness, OrderOptions } from '../../exchange-adapter.js';
+import type { CcxtOrder, CcxtBalance, CcxtPosition, TradingMode } from '../../types.js';
+import type { PositionMetadata, CloseReason } from '../../simulator/types.js';
+import { type HlCredentials } from './hl-private.js';
+import type { BracketId } from '../../live/bracket-types.js';
+import { BracketLedger } from '../../live/bracket-ledger.js';
+import { HlBracketCoordinator } from './hl-bracket-coordinator.js';
+export interface HlLiveAdapterOptions {
+    credentials: HlCredentials;
+    mode: TradingMode;
+    marketSlippagePct?: number;
+    /** Test seams. Production omits both. */
+    bracketLedger?: BracketLedger;
+    disableUserStream?: boolean;
+}
+export declare class HyperliquidLiveAdapter extends EventEmitter implements IExchangeAdapter {
+    private readonly opts;
+    private readonly api;
+    private readonly publicApi;
+    private readonly infoCache;
+    private readonly slippagePct;
+    /** ★ On HL live, brackets are ALWAYS enforced — there is no watcher fallback
+     *  (the stop-watcher has no live metadata) and no `brackets.mode=off` arm:
+     *  the exchange-side legs ARE the safety floor. Lazily constructed so that
+     *  merely constructing the adapter (registry tests) writes no ledger file. */
+    private _coordinator;
+    private userStream;
+    private truthCheckTimer;
+    private truthCheckRunning;
+    private _readiness;
+    private openOrdersUnavailableUntil;
+    constructor(opts: HlLiveAdapterOptions);
+    /** The HL bracket orchestrator — the venue-aware tools (attach_brackets /
+     *  modify_stop / modify_target / audit) drive brackets through this. */
+    getHlBracketCoordinator(): HlBracketCoordinator;
+    /** Boot: load markets + asset rules. Readiness gates `create_order` ONLY —
+     *  emergency paths never consult it. */
+    initialize(): Promise<void>;
+    /** Stop background machinery (tests / graceful shutdown). The exchange-side
+     *  legs keep protecting the position regardless — that is the point. */
+    stop(): void;
+    get readiness(): AdapterReadiness;
+    get mode(): TradingMode;
+    get isLive(): boolean;
+    createOrder(symbol: string, side: 'buy' | 'sell', type: 'market' | 'limit', amount: number, price?: number, metadata?: PositionMetadata, options?: OrderOptions): Promise<CcxtOrder>;
+    /**
+     * Post-submit bracket wiring, mirroring the Binance LiveAdapter sequence:
+     * validate direction against the ACTUAL fill (issue #196 — never the limit
+     * price on a filled order), flatten a filled entry whose bracket is invalid
+     * (a naked entry must not survive), detect scale-ins (T-2: HL legs are fixed
+     * size — the ADDED contracts are naked until resized), then register +
+     * attach. Attach itself is async (non-blocking, mirrors Binance) — retries +
+     * auto-flatten handle failures.
+     */
+    private wireBracketsAfterSubmit;
+    private attachOnFillAsync;
+    private resizeAfterScaleInAsync;
+    /** Emergency-safe: never pre-gated, never readiness-gated. */
+    cancelOrder(orderId: string, symbol?: string): Promise<CcxtOrder>;
+    /**
+     * Cancel WORKING orders — protective legs are PRESERVED.
+     *
+     * This is the plugin-side half of the kill-preserve rule (the skill has its own,
+     * broader layer). A Kill must never strip the stop off a live position.
+     */
+    cancelAllOrders(symbol?: string): Promise<CcxtOrder[]>;
+    /**
+     * Close a position at market (reduce-only IOC).
+     *
+     * ★ 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.
+     */
+    closePosition(symbol: string, _closeReason?: CloseReason): Promise<CcxtOrder>;
+    getBalance(): Promise<CcxtBalance>;
+    /** Display contract (`?? []`) — the 20+ KPI/display callers. */
+    getPositions(symbol?: string): Promise<CcxtPosition[]>;
+    /** ★ Decision contract — null means UNKNOWN, and destructive paths must not act. */
+    getPositionsOrNull(symbol?: string): Promise<CcxtPosition[] | null>;
+    /**
+     * ★ THROWS on a failed fetch — never returns [].
+     *
+     * An empty list is positive information ("the exchange has no orders"); a failed
+     * fetch is not. Collapsing the two is what drove the ATOM naked-bracket loop on
+     * Binance. A sticky cooldown then prevents a retry loop from pinning the budget.
+     */
+    getOpenOrders(symbol?: string): Promise<CcxtOrder[]>;
+    fetchOrder(orderId: string, symbol?: string): Promise<CcxtOrder | null>;
+    getLastPrice(symbol: string): Promise<number | null>;
+    /** Attach protective legs to a filled position — ONE signed action for both.
+     *  Returns the cloids it generated so the coordinator can persist them (a
+     *  cloid is single-use; the ledger must always match the live legs). */
+    attachBrackets(args: {
+        bracketId: BracketId;
+        symbol: string;
+        positionSide: 'long' | 'short';
+        positionSize: number;
+        stopPrice?: number;
+        targetPrice?: number;
+    }): Promise<{
+        orders: CcxtOrder[];
+        slCid?: string;
+        tpCid?: string;
+    }>;
+    /**
+     * ★ T-2 REQUIREMENT: resize protective legs after a scale-in.
+     *
+     * HL legs are FIXED SIZE and do not follow the position (measured). Without this
+     * the added contracts are NAKED. Submit-then-cancel: a moment of over-protection
+     * (harmless — reduce-only cannot flip a position) beats a naked window.
+     */
+    resizeBrackets(args: {
+        bracketId: BracketId;
+        symbol: string;
+        positionSide: 'long' | 'short';
+        positionSize: number;
+    }): Promise<{
+        resized: boolean;
+        slCid?: string;
+        tpCid?: string;
+    }>;
+    /** Cancel one bracket leg by cloid. Idempotent: a leg that is already gone
+     *  (triggered / T-1 auto-cancelled / sibling-cancelled) is SUCCESS, not an
+     *  error — the goal state ("leg not on the book") is reached. */
+    cancelBracketLeg(cloid: string, symbol: string): Promise<void>;
+    /** Coverage audit — `covered:false` means part of the position is NAKED. */
+    auditBracketCoverage(symbol: string, positionSize: number): Promise<import("./hl-brackets.js").CoverageResult>;
+    /** Cancel every OUR-cloid bracket leg on a symbol (recovery-path orphan
+     *  cleanup before a fresh attach). THROWS when order state is unknown —
+     *  the caller logs and still attaches (protection beats hygiene). */
+    cancelSymbolBracketLegs(symbol: string): Promise<number>;
+    /** Entry fills drive attach (resting limits) / resize (partial-fill growth).
+     *  `startPosition` is the position BEFORE this fill — the WS-authoritative
+     *  way to know the after-fill total without an extra REST read. */
+    private onUserFill;
+    /** `orderUpdates` is authoritative for leg lifecycle (the ALGO_UPDATE
+     *  analog). A trigger = the exchange closed the position — surface the same
+     *  `drift_detected` close shape the Binance reconciler emits so the journal
+     *  close-bypass cleanup fires at once, not ≤5 min late. */
+    private onUserOrderUpdate;
+    /** T-5 REST truth-check — serialized so a slow pass can't stack. */
+    private runTruthCheck;
+    /** Our protective legs currently on the exchange. Throws on unknown (never []). */
+    private readLiveLegs;
+}