@reefclaw/connect 0.1.11 → 0.1.12

package/assets/plugin/live/bracket-manager.js

@@ -1,478 +0,0 @@
-// 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/assets/plugin/live/bracket-params.d.ts

@@ -1,22 +0,0 @@
-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/assets/plugin/live/bracket-params.js

@@ -1,124 +0,0 @@
-// 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;
-}