@reefclaw/openclaw-plugin 0.1.0

package/live/bracket-manager.js

@@ -0,0 +1,478 @@
+// BracketManager — orchestrates the lifecycle of exchange-side bracket orders.
+//
+// Separation of concerns:
+//   - LiveAdapter owns the ENTRY order (submit, wait for fill).
+//   - BracketManager owns the SL/TP orders (attach, modify, cancel).
+//   - BracketLedger owns persistent state (survives restart).
+//
+// Retry policy (locked decision #2):
+//   - 3 attempts over ~5s total
+//   - On any leg failure, cancel the successful sibling from that attempt
+//     before retrying, so the exchange state never runs ahead of the ledger.
+//   - After exhausting retries, transitions ledger to 'failed' and emits a
+//     critical event. LiveAdapter listens for that event and triggers the
+//     auto-flatten (the manager itself does not close positions).
+//
+// Modes:
+//   - Both SL and TP provided → target state 'active'
+//   - Only one provided       → target state 'partial' (matches requireStopLoss /
+//     requireTakeProfit toggles being independently flippable)
+//   - Neither provided        → Manager.registerEntry rejects; LiveAdapter
+//     should skip bracket registration entirely in that case.
+import { EventEmitter } from 'node:events';
+import { logger, formatError } from '../logger.js';
+import { buildStopLossParams, buildTakeProfitParams } from './bracket-params.js';
+import { assertNotShuttingDown, trackOp } from '../lifecycle/shutdown-coordinator.js';
+const TAG = 'bracket-manager';
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_BACKOFF = (attempt) => attempt === 1 ? 1_000 : 2_000;
+const DEFAULT_SLA_MS = 3_000;
+const TERMINAL_STATES = new Set([
+    'triggered_sl',
+    'triggered_tp',
+    'cancelled',
+    'failed',
+]);
+function isTerminalState(state) {
+    return TERMINAL_STATES.has(state);
+}
+export class BracketManager extends EventEmitter {
+    api;
+    ledger;
+    maxAttempts;
+    backoff;
+    slaMs;
+    now;
+    sleep;
+    constructor(api, ledger, opts = {}) {
+        super();
+        this.api = api;
+        this.ledger = ledger;
+        this.maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+        this.backoff = opts.retryBackoffMs ?? DEFAULT_BACKOFF;
+        this.slaMs = opts.slaMs ?? DEFAULT_SLA_MS;
+        this.now = opts.now ?? Date.now;
+        this.sleep = opts.sleep ?? ((ms) => new Promise(r => setTimeout(r, ms)));
+    }
+    /** Called by LiveAdapter after submitting the entry but before fill.
+     *  Creates the ledger row in 'pending_entry' state.
+     *
+     *  Ledger hygiene: if a terminal-state row exists for this symbol (from a
+     *  prior trade cycle that closed, got cancelled, or had its brackets
+     *  stripped), remove it before inserting the new pending_entry. Otherwise
+     *  the stale row's bracketId/slCid/tpCid would survive the upsert and
+     *  mislead later callers — most visibly, `modify_stop` / `modify_target`
+     *  would see `state: 'cancelled'` and refuse to operate even though a fresh
+     *  bracket is now active. */
+    registerEntry(req, bracketId, entryCid) {
+        if (req.stopPrice === undefined && req.targetPrice === undefined) {
+            throw new Error('registerEntry: at least one of stopPrice or targetPrice is required');
+        }
+        const existing = this.ledger.getBySymbol(req.symbol);
+        // ANTI-CLOBBER ROOT FIX (2026-05-16 SOL/INJ spiral disease). A
+        // NON-terminal row (pending_entry / attaching / active / partial) is a
+        // live or in-flight bracket for the CURRENT position cycle, holding the
+        // bracketId + slCid/tpCid that match the orders live on the exchange.
+        // A single entry produces MULTIPLE fill signals — the real WS
+        // ORDER_TRADE_UPDATE, the create_order confirmation, the (stale-skill)
+        // position-poll SYNTHETIC fill, and any agent attach_brackets — each of
+        // which can re-enter registerEntry. The original code then upsert'd
+        // state:'pending_entry' with a FRESH bracketId unconditionally, wiping
+        // the active bracket's identity from the ledger. The ledger row no
+        // longer matched the live exchange orders, so the orphan sweep saw them
+        // as unmatched (→ cancel), classify saw stale cids (→ reattach loop),
+        // and audit went unverifiable — the shared root of every bracket spiral
+        // this session. Making a duplicate registerEntry a no-op keeps the
+        // ledger row matching the live orders. attach_brackets terminalises the
+        // row (markState 'cancelled') BEFORE its registerEntry, so its legitimate
+        // re-attach is unaffected (existing is terminal → removed below). A new
+        // entry on a symbol that still has a non-terminal row is a scale-in/
+        // error whose bracket must be adjusted via modify_*, never by silently
+        // resetting + re-attaching (that IS the double-bracket spiral).
+        if (existing && !isTerminalState(existing.state)) {
+            logger.warn(TAG, `registerEntry(${req.symbol}): a non-terminal bracket row already ` +
+                `exists (state=${existing.state}, bracketId=${existing.bracketId}, ` +
+                `slCid=${existing.slCid ?? '-'}, tpCid=${existing.tpCid ?? '-'}). ` +
+                `Treating as a duplicate fill signal — NOT clobbering the live ` +
+                `bracket's ledger identity (anti-clobber root fix). Use modify_* ` +
+                `to change levels.`);
+            return;
+        }
+        if (existing && isTerminalState(existing.state)) {
+            this.ledger.remove(req.symbol);
+        }
+        this.ledger.upsert({
+            bracketId,
+            symbol: req.symbol,
+            entrySide: req.side,
+            entryCid,
+            stopPrice: req.stopPrice,
+            targetPrice: req.targetPrice,
+            state: 'pending_entry',
+        });
+        this.emitEvent({
+            type: 'bracket.entry_submitted',
+            bracketId,
+            symbol: req.symbol,
+            ts: new Date(this.now()).toISOString(),
+        });
+    }
+    /** Called by LiveAdapter when the entry fills. Attaches SL + TP to the
+     *  exchange with retries. Idempotent — safe to call exactly once per fill.
+     *
+     *  Intentionally NOT gated by `assertNotShuttingDown`: by the time this
+     *  runs, the entry has already filled and the position is open on Binance.
+     *  Refusing here would leave a naked position — the drain budget is sized
+     *  to cover the 3-attempt retry loop instead. New ENTRIES are gated at
+     *  `LiveAdapter.createOrder`, so once we get here the entry was authorised
+     *  before the shutdown flag was set. */
+    async attachBrackets(symbol, entryAmount) {
+        const entry = this.ledger.getBySymbol(symbol);
+        if (!entry)
+            throw new Error(`attachBrackets: no ledger entry for ${symbol}`);
+        if (entry.state !== 'pending_entry') {
+            // Idempotency: if already attaching/active, return current status.
+            return {
+                ok: entry.state === 'active' || entry.state === 'partial',
+                latencyMs: entry.attachLatencyMs ?? 0,
+                slCid: entry.slCid,
+                tpCid: entry.tpCid,
+                attempts: 0,
+            };
+        }
+        return trackOp(`attachBrackets(${symbol})`, async () => {
+            const startTs = this.now();
+            const startedAtIso = new Date(startTs).toISOString();
+            this.ledger.markState(symbol, 'attaching', { attachStartedAt: startedAtIso });
+            this.emitEvent({
+                type: 'bracket.entry_filled',
+                bracketId: entry.bracketId,
+                symbol,
+                ts: startedAtIso,
+            });
+            const req = {
+                symbol,
+                side: entry.entrySide,
+                stopPrice: entry.stopPrice,
+                targetPrice: entry.targetPrice,
+            };
+            let lastError;
+            for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+                const result = await this.attemptAttach(req, entry.bracketId, entryAmount);
+                if (result.ok) {
+                    const latencyMs = this.now() - startTs;
+                    const targetState = (result.slCid && result.tpCid)
+                        ? 'active'
+                        : 'partial';
+                    this.ledger.markState(symbol, targetState, {
+                        attachCompletedAt: new Date(this.now()).toISOString(),
+                        attachLatencyMs: latencyMs,
+                        slCid: result.slCid,
+                        tpCid: result.tpCid,
+                        // Freeze the size the legs were submitted with so a later
+                        // modifyStop/modifyTarget rebuilds the leg at the SAME size
+                        // instead of a placeholder (the 1-contract under-protect bug).
+                        qty: entryAmount,
+                    });
+                    this.emitEvent({
+                        type: 'bracket.attached',
+                        bracketId: entry.bracketId,
+                        symbol,
+                        latencyMs,
+                        ts: new Date(this.now()).toISOString(),
+                    });
+                    if (latencyMs > this.slaMs) {
+                        this.emitEvent({
+                            type: 'bracket.sla_breach',
+                            bracketId: entry.bracketId,
+                            symbol,
+                            latencyMs,
+                            ts: new Date(this.now()).toISOString(),
+                        });
+                    }
+                    return { ok: true, latencyMs, slCid: result.slCid, tpCid: result.tpCid, attempts: attempt };
+                }
+                lastError = result.error;
+                this.emitEvent({
+                    type: 'bracket.attach_failed',
+                    bracketId: entry.bracketId,
+                    symbol,
+                    error: lastError ?? 'unknown',
+                    retryCount: attempt,
+                    ts: new Date(this.now()).toISOString(),
+                });
+                // Clean up any partial attach (one leg succeeded, the other didn't)
+                await this.cancelPartial(symbol, result.slCid, result.tpCid);
+                if (attempt < this.maxAttempts) {
+                    await this.sleep(this.backoff(attempt));
+                }
+            }
+            const latencyMs = this.now() - startTs;
+            this.ledger.markState(symbol, 'failed', {
+                closeReason: 'attach_failed',
+                lastError,
+            });
+            return { ok: false, latencyMs, attempts: this.maxAttempts, error: lastError };
+        });
+    }
+    /** Move the stop. Cancel-then-resubmit; rolls back to the old stop if the
+     *  new submission fails, so the position is never left unprotected. */
+    async modifyStop(symbol, newStopPrice) {
+        // Refuse during shutdown — cancel-then-resubmit is the worst race window
+        // (brief naked position between cancel ack and new SL submission).
+        assertNotShuttingDown(`modifyStop(${symbol})`);
+        if (!Number.isFinite(newStopPrice) || newStopPrice <= 0) {
+            throw new Error(`modifyStop: newStopPrice must be positive finite, got ${newStopPrice}`);
+        }
+        const entry = this.ledger.getBySymbol(symbol);
+        if (!entry)
+            throw new Error(`modifyStop: no ledger entry for ${symbol}`);
+        if (entry.state !== 'active' && entry.state !== 'partial') {
+            throw new Error(`modifyStop: cannot modify stop in state ${entry.state}`);
+        }
+        // Resolve the size the bracket was attached with. This MUST happen before
+        // the old SL is cancelled below: if we cancelled first and then couldn't
+        // size the replacement, the position would be left naked. Throwing here
+        // (old bracket still live) is strictly safer than rebuilding the leg at a
+        // placeholder size, which would silently under-protect the position.
+        const qty = entry.qty;
+        if (qty === undefined || !Number.isFinite(qty) || qty <= 0) {
+            throw new Error(`modifyStop: ledger has no valid bracket qty for ${symbol} (qty=${qty}); ` +
+                `refusing to resize the stop to a placeholder size — re-attach the bracket first`);
+        }
+        return trackOp(`modifyStop(${symbol})`, async () => {
+            const oldStopPrice = entry.stopPrice;
+            const oldSlCid = entry.slCid;
+            // Cancel old stop (if present)
+            if (oldSlCid) {
+                try {
+                    await this.api.cancelOrderByClientId(oldSlCid, symbol);
+                }
+                catch (err) {
+                    throw new Error(`modifyStop: could not cancel old SL: ${formatError(err)}`);
+                }
+            }
+            // Submit new stop
+            const leg = buildStopLossParams({ symbol, side: entry.entrySide, stopPrice: newStopPrice }, entry.bracketId, qty);
+            try {
+                await this.api.submitBracketLeg(leg);
+            }
+            catch (err) {
+                // Rollback: put the old stop back
+                if (oldStopPrice !== undefined && oldSlCid) {
+                    const rollbackLeg = buildStopLossParams({ symbol, side: entry.entrySide, stopPrice: oldStopPrice }, entry.bracketId, qty);
+                    try {
+                        await this.api.submitBracketLeg(rollbackLeg);
+                    }
+                    catch (rbErr) {
+                        logger.error(TAG, `modifyStop rollback ALSO failed for ${symbol}: ${formatError(rbErr)}`);
+                        // Position is now unprotected on the stop side — emit critical event
+                        this.emitEvent({
+                            type: 'bracket.attach_failed',
+                            bracketId: entry.bracketId,
+                            symbol,
+                            error: `rollback failed: ${formatError(rbErr)}`,
+                            retryCount: 0,
+                            ts: new Date(this.now()).toISOString(),
+                        });
+                    }
+                }
+                throw new Error(`modifyStop: new SL submission failed: ${formatError(err)}`);
+            }
+            // Success — persist new stop. Same reasoning as attemptAttach: store the
+            // client id we chose, not the exchange-assigned id.
+            this.ledger.upsert({
+                ...entry,
+                stopPrice: newStopPrice,
+                slCid: leg.params.newClientOrderId,
+            });
+            this.emitEvent({
+                type: 'bracket.modified',
+                bracketId: entry.bracketId,
+                symbol,
+                field: 'stop',
+                oldValue: oldStopPrice ?? NaN,
+                newValue: newStopPrice,
+                ts: new Date(this.now()).toISOString(),
+            });
+        });
+    }
+    /** Move the take-profit. Same semantics as modifyStop. */
+    async modifyTarget(symbol, newTargetPrice) {
+        assertNotShuttingDown(`modifyTarget(${symbol})`);
+        if (!Number.isFinite(newTargetPrice) || newTargetPrice <= 0) {
+            throw new Error(`modifyTarget: newTargetPrice must be positive finite, got ${newTargetPrice}`);
+        }
+        const entry = this.ledger.getBySymbol(symbol);
+        if (!entry)
+            throw new Error(`modifyTarget: no ledger entry for ${symbol}`);
+        if (entry.state !== 'active' && entry.state !== 'partial') {
+            throw new Error(`modifyTarget: cannot modify target in state ${entry.state}`);
+        }
+        // See modifyStop: resolve size before cancelling the old TP so we never
+        // rebuild the leg at a placeholder size (the 1-contract under-protect bug).
+        const qty = entry.qty;
+        if (qty === undefined || !Number.isFinite(qty) || qty <= 0) {
+            throw new Error(`modifyTarget: ledger has no valid bracket qty for ${symbol} (qty=${qty}); ` +
+                `refusing to resize the target to a placeholder size — re-attach the bracket first`);
+        }
+        return trackOp(`modifyTarget(${symbol})`, async () => {
+            const oldTargetPrice = entry.targetPrice;
+            const oldTpCid = entry.tpCid;
+            if (oldTpCid) {
+                try {
+                    await this.api.cancelOrderByClientId(oldTpCid, symbol);
+                }
+                catch (err) {
+                    throw new Error(`modifyTarget: could not cancel old TP: ${formatError(err)}`);
+                }
+            }
+            const leg = buildTakeProfitParams({ symbol, side: entry.entrySide, targetPrice: newTargetPrice }, entry.bracketId, qty);
+            try {
+                await this.api.submitBracketLeg(leg);
+            }
+            catch (err) {
+                if (oldTargetPrice !== undefined && oldTpCid) {
+                    const rollbackLeg = buildTakeProfitParams({ symbol, side: entry.entrySide, targetPrice: oldTargetPrice }, entry.bracketId, qty);
+                    try {
+                        await this.api.submitBracketLeg(rollbackLeg);
+                    }
+                    catch (rbErr) {
+                        logger.error(TAG, `modifyTarget rollback ALSO failed for ${symbol}: ${formatError(rbErr)}`);
+                    }
+                }
+                throw new Error(`modifyTarget: new TP submission failed: ${formatError(err)}`);
+            }
+            this.ledger.upsert({
+                ...entry,
+                targetPrice: newTargetPrice,
+                tpCid: leg.params.newClientOrderId,
+            });
+            this.emitEvent({
+                type: 'bracket.modified',
+                bracketId: entry.bracketId,
+                symbol,
+                field: 'target',
+                oldValue: oldTargetPrice ?? NaN,
+                newValue: newTargetPrice,
+                ts: new Date(this.now()).toISOString(),
+            });
+        });
+    }
+    /** Cancel both bracket legs and mark the ledger cancelled. Called when
+     *  LiveAdapter closes the position via `close_position` or flatten. Risk-
+     *  reducing — allowed during shutdown, but tracked so the drain awaits it. */
+    async cancelBrackets(symbol, reason) {
+        const entry = this.ledger.getBySymbol(symbol);
+        if (!entry)
+            return; // nothing to cancel
+        if (entry.slCid) {
+            try {
+                await this.api.cancelOrderByClientId(entry.slCid, symbol);
+            }
+            catch (err) {
+                logger.warn(TAG, `cancelBrackets SL ${symbol}: ${formatError(err)}`);
+            }
+        }
+        if (entry.tpCid) {
+            try {
+                await this.api.cancelOrderByClientId(entry.tpCid, symbol);
+            }
+            catch (err) {
+                logger.warn(TAG, `cancelBrackets TP ${symbol}: ${formatError(err)}`);
+            }
+        }
+        this.ledger.markState(symbol, 'cancelled', { closeReason: 'cancelled_manual' });
+        this.emitEvent({
+            type: 'bracket.cancelled',
+            bracketId: entry.bracketId,
+            symbol,
+            reason,
+            ts: new Date(this.now()).toISOString(),
+        });
+    }
+    /** Called by the reconciler / fill poller when one of the bracket legs
+     *  fires on the exchange. Transitions the ledger to the matching triggered
+     *  state and emits. Binance's closePosition:true auto-cancels the sibling. */
+    handleBracketTriggered(symbol, triggeredRole) {
+        const entry = this.ledger.getBySymbol(symbol);
+        if (!entry)
+            return;
+        const nextState = triggeredRole === 'sl' ? 'triggered_sl' : 'triggered_tp';
+        this.ledger.markState(symbol, nextState, {
+            closeReason: triggeredRole === 'sl' ? 'triggered_sl' : 'triggered_tp',
+        });
+        this.emitEvent({
+            type: 'bracket.triggered',
+            bracketId: entry.bracketId,
+            symbol,
+            side: triggeredRole,
+            ts: new Date(this.now()).toISOString(),
+        });
+    }
+    // ---- Internals ----
+    async attemptAttach(req, bracketId, entryAmount) {
+        let slCid;
+        let tpCid;
+        // ROOT-CAUSE FIX 2026-05-16: neutralise any externally-armed
+        // countdownCancelAll dead-man's-switch for this symbol BEFORE placing
+        // protection, so Binance can't purge the legs ~tens of seconds later
+        // (the proven cause of the months-long naked-position spiral). Purely
+        // protective + best-effort: the method swallows its own errors and never
+        // throws here — a failed disable must never block bracket placement.
+        if (this.api.disableCountdownCancelAll) {
+            try {
+                await this.api.disableCountdownCancelAll(req.symbol);
+            }
+            catch (err) {
+                logger.warn(TAG, `disableCountdownCancelAll(${req.symbol}) threw (ignored): ${formatError(err)}`);
+            }
+        }
+        if (req.stopPrice !== undefined) {
+            const leg = buildStopLossParams(req, bracketId, entryAmount);
+            try {
+                await this.api.submitBracketLeg(leg);
+                // Store the CLIENT order id (what we sent), not the exchange-assigned
+                // id. The exchange id lives in a different namespace for algo orders
+                // (algoId) vs regular orders; cancelOrderByClientId expects the cid
+                // we chose, which is deterministic and survives an adapter restart.
+                slCid = leg.params.newClientOrderId;
+            }
+            catch (err) {
+                return { ok: false, error: `SL: ${formatError(err)}` };
+            }
+        }
+        if (req.targetPrice !== undefined) {
+            const leg = buildTakeProfitParams(req, bracketId, entryAmount);
+            try {
+                await this.api.submitBracketLeg(leg);
+                tpCid = leg.params.newClientOrderId;
+            }
+            catch (err) {
+                return { ok: false, slCid, error: `TP: ${formatError(err)}` };
+            }
+        }
+        return { ok: true, slCid, tpCid };
+    }
+    async cancelPartial(symbol, slCid, tpCid) {
+        if (slCid) {
+            try {
+                await this.api.cancelOrderByClientId(slCid, symbol);
+            }
+            catch (err) {
+                logger.warn(TAG, `cancelPartial SL ${symbol}: ${formatError(err)}`);
+            }
+        }
+        if (tpCid) {
+            try {
+                await this.api.cancelOrderByClientId(tpCid, symbol);
+            }
+            catch (err) {
+                logger.warn(TAG, `cancelPartial TP ${symbol}: ${formatError(err)}`);
+            }
+        }
+    }
+    emitEvent(event) {
+        this.emit('event', event);
+    }
+}

package/live/bracket-params.d.ts

@@ -0,0 +1,22 @@
+import type { BracketId, BracketRequest } from './bracket-types.js';
+/** One CCXT-shaped leg ready to hand to `exchange.createOrder(...)`. */
+export interface BracketLegParams {
+    symbol: string;
+    type: 'STOP_MARKET' | 'TAKE_PROFIT_MARKET';
+    side: 'buy' | 'sell';
+    amount: number;
+    price: undefined;
+    params: Record<string, any>;
+}
+/** Return the side that CLOSES a position opened with `entrySide`. */
+export declare function closingSide(entrySide: 'buy' | 'sell'): 'buy' | 'sell';
+/** Build the stop-loss leg. Throws if stopPrice is missing. */
+export declare function buildStopLossParams(req: BracketRequest, bracketId: BracketId, entryAmount: number): BracketLegParams;
+/** Build the take-profit leg. Throws if targetPrice is missing. */
+export declare function buildTakeProfitParams(req: BracketRequest, bracketId: BracketId, entryAmount: number): BracketLegParams;
+/** Sanity check that a stopPrice is on the correct side of entry — catches
+ *  off-by-flipped-sign errors before Binance rejects with -2021 "would
+ *  immediately trigger." Returns null if OK, error message otherwise. */
+export declare function validateStopDirection(entrySide: 'buy' | 'sell', entryPrice: number, stopPrice: number): string | null;
+/** Same sanity check for take-profit: must be on the winning side of entry. */
+export declare function validateTargetDirection(entrySide: 'buy' | 'sell', entryPrice: number, targetPrice: number): string | null;

package/live/bracket-params.js

@@ -0,0 +1,124 @@
+// CCXT parameter builder for bracket legs (STOP_MARKET + TAKE_PROFIT_MARKET).
+//
+// One-way mode only (per locked design decision #1). Hedge-mode support can
+// be added later via positionSide — but see §2 of BRACKET_ORDERS_DESIGN.md.
+//
+// Order-flag semantics — `closePosition: true` (position-bound), 2026-05-16.
+//
+//   ROOT-CAUSE FIX. We previously used `reduceOnly: true` + explicit `amount`.
+//   On 2025-12-09 Binance migrated ALL USD-M conditional orders to the new
+//   "Algo Service" (changelog 2025-11-06 / 2025-12-09; classic /fapi/v1/order
+//   now rejects them with -4120 → forced onto POST /fapi/v1/algoOrder). The
+//   new Algo Service AUTO-CANCELS standalone `reduceOnly`+`quantity`
+//   conditional algo orders ~17-53s after placement WHILE THE POSITION IS
+//   STILL OPEN (prod-proven 2026-05-15/16 SOL+APT: every prior fix targeted
+//   ReefClaw bracket logic — the wrong layer; an airtight-verified
+//   `logAlgoCancelChokepoint` tracer recorded ZERO of our cancel calls while
+//   Binance reported the leg CANCELED). Binance does NOT document this; it is
+//   a silent post-migration behaviour change.
+//
+//   `closePosition: true` is the POSITION-BOUND form: Binance ties the order's
+//   lifecycle to the position and does NOT auto-cancel it while the position
+//   is open. Independently proven: the operator's manually-set Binance-app
+//   position TP/SL is exactly this form and it sticks when our reduceOnly one
+//   vanishes. Doc (New-Algo-Order): closePosition "close all current
+//   long/short position if triggered"; MUST NOT be sent with `quantity`
+//   (-4137) or `reduceOnly` (-4138) → `amount` is 0 and neither flag is set.
+//
+//   -4130 reassessed: the old comment said a second closePosition order is
+//   rejected -4130 ("stop/TP with GTE and closePosition in the direction
+//   exists"). That finding "after testnet validation" PREDATES the 2025-12-09
+//   algo migration; -4130 is no longer in the current USD-M error-code doc;
+//   and the Binance app itself runs a coexisting closePosition SL+TP on a
+//   position (opposite trigger types, the standard exchange-native bracket).
+//   The deployed cancel/attribution tracers + the bracket reconciler surface
+//   any -4130 immediately and loudly, so a recurrence is an observable fast
+//   follow-up (asymmetric SL-closePosition / TP-reduceOnly fallback) rather
+//   than a silent naked position.
+//
+//   closePosition also SIMPLIFIES the model: first trigger closes the whole
+//   position; the sibling is auto-cancelled by Binance on position close
+//   (EXPIRED, benign); no quantity/partial-fill bracket-resize logic needed.
+//
+// workingType:
+//   - CONTRACT_PRICE (Binance default): triggers on last traded price of the
+//     pair. Matches what users typically mean by "stop price."
+//   - MARK_PRICE: triggers on the mark price (index-derived). More robust to
+//     single-pair manipulation but can lag fast moves. Not used by default.
+import { buildBracketCid } from './bracket-id.js';
+/** Return the side that CLOSES a position opened with `entrySide`. */
+export function closingSide(entrySide) {
+    return entrySide === 'buy' ? 'sell' : 'buy';
+}
+/** Build the stop-loss leg. Throws if stopPrice is missing. */
+export function buildStopLossParams(req, bracketId, entryAmount) {
+    if (req.stopPrice === undefined || !Number.isFinite(req.stopPrice) || req.stopPrice <= 0) {
+        throw new Error('buildStopLossParams: stopPrice must be a positive finite number');
+    }
+    if (!Number.isFinite(entryAmount) || entryAmount <= 0) {
+        throw new Error('buildStopLossParams: entryAmount must be a positive finite number');
+    }
+    return {
+        symbol: req.symbol,
+        type: 'STOP_MARKET',
+        side: closingSide(req.side),
+        // closePosition is "close-all" — Binance ignores/forbids a quantity
+        // (-4137). amount 0; entryAmount is still validated above so a caller
+        // with a bogus size is rejected, and the ledger keeps qty for telemetry.
+        amount: 0,
+        price: undefined,
+        params: {
+            stopPrice: req.stopPrice,
+            // Position-bound form: Binance keeps it with the position and does NOT
+            // auto-cancel it while open (unlike reduceOnly+qty — see file header).
+            closePosition: true,
+            workingType: 'CONTRACT_PRICE',
+            newClientOrderId: buildBracketCid(bracketId, 'stop'),
+        },
+    };
+}
+/** Build the take-profit leg. Throws if targetPrice is missing. */
+export function buildTakeProfitParams(req, bracketId, entryAmount) {
+    if (req.targetPrice === undefined || !Number.isFinite(req.targetPrice) || req.targetPrice <= 0) {
+        throw new Error('buildTakeProfitParams: targetPrice must be a positive finite number');
+    }
+    if (!Number.isFinite(entryAmount) || entryAmount <= 0) {
+        throw new Error('buildTakeProfitParams: entryAmount must be a positive finite number');
+    }
+    return {
+        symbol: req.symbol,
+        type: 'TAKE_PROFIT_MARKET',
+        side: closingSide(req.side),
+        amount: 0, // closePosition = close-all; no quantity (-4137)
+        price: undefined,
+        params: {
+            stopPrice: req.targetPrice, // Binance calls the trigger "stopPrice" on TP_MARKET too
+            // Position-bound form — see file header (root-cause fix 2026-05-16).
+            closePosition: true,
+            workingType: 'CONTRACT_PRICE',
+            newClientOrderId: buildBracketCid(bracketId, 'target'),
+        },
+    };
+}
+/** Sanity check that a stopPrice is on the correct side of entry — catches
+ *  off-by-flipped-sign errors before Binance rejects with -2021 "would
+ *  immediately trigger." Returns null if OK, error message otherwise. */
+export function validateStopDirection(entrySide, entryPrice, stopPrice) {
+    if (entrySide === 'buy' && stopPrice >= entryPrice) {
+        return `Stop price ${stopPrice} must be BELOW entry ${entryPrice} for a long position`;
+    }
+    if (entrySide === 'sell' && stopPrice <= entryPrice) {
+        return `Stop price ${stopPrice} must be ABOVE entry ${entryPrice} for a short position`;
+    }
+    return null;
+}
+/** Same sanity check for take-profit: must be on the winning side of entry. */
+export function validateTargetDirection(entrySide, entryPrice, targetPrice) {
+    if (entrySide === 'buy' && targetPrice <= entryPrice) {
+        return `Target price ${targetPrice} must be ABOVE entry ${entryPrice} for a long position`;
+    }
+    if (entrySide === 'sell' && targetPrice >= entryPrice) {
+        return `Target price ${targetPrice} must be BELOW entry ${entryPrice} for a short position`;
+    }
+    return null;
+}