@reefclaw/openclaw-plugin 0.1.6 → 0.1.7

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

@@ -0,0 +1,123 @@
+import { EventEmitter } from 'node:events';
+import type { CcxtOrder, CcxtPosition } from '../../types.js';
+import type { CloseReason } from '../../simulator/types.js';
+import type { BracketId, BracketRequest, BracketState } from '../../live/bracket-types.js';
+import type { BracketLedger } from '../../live/bracket-ledger.js';
+import type { HlOrderUpdateEvent } from './hl-user-stream.js';
+/** Narrow execution surface the coordinator needs — the HyperliquidLiveAdapter
+ *  implements it; tests mock it without a network. */
+export interface HlBracketExecutor {
+    attachBrackets(args: {
+        bracketId: BracketId;
+        symbol: string;
+        positionSide: 'long' | 'short';
+        positionSize: number;
+        stopPrice?: number;
+        targetPrice?: number;
+    }): Promise<{
+        orders: CcxtOrder[];
+        slCid?: string;
+        tpCid?: string;
+    }>;
+    resizeBrackets(args: {
+        bracketId: BracketId;
+        symbol: string;
+        positionSide: 'long' | 'short';
+        positionSize: number;
+    }): Promise<{
+        resized: boolean;
+        slCid?: string;
+        tpCid?: string;
+    }>;
+    /** Cancel one leg by cloid. Idempotent — "already gone" must not throw. */
+    cancelBracketLeg(cloid: string, symbol: string): Promise<void>;
+    /** Coverage audit — THROWS when order state is unknown (null ≠ empty). */
+    auditBracketCoverage(symbol: string, positionSize: number): Promise<{
+        covered: boolean;
+        shortfall: {
+            stop: number;
+            target: number;
+        };
+        missing: ('stop' | 'target')[];
+    }>;
+    getPositionsOrNull(symbol?: string): Promise<CcxtPosition[] | null>;
+    closePosition(symbol: string, closeReason?: CloseReason): Promise<CcxtOrder>;
+}
+export interface HlAttachResult {
+    ok: boolean;
+    latencyMs: number;
+    slCid?: string;
+    tpCid?: string;
+    error?: string;
+    attempts: number;
+}
+export interface HlCoordinatorOpts {
+    maxAttempts?: number;
+    retryBackoffMs?: (attempt: number) => number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function isTerminalBracketState(state: BracketState): boolean;
+export declare class HlBracketCoordinator extends EventEmitter {
+    private readonly executor;
+    private readonly ledger;
+    private readonly maxAttempts;
+    private readonly backoff;
+    private readonly now;
+    private readonly sleep;
+    /** Per-symbol in-flight guard so a WS fill + the createOrder return path
+     *  can't both run attachOnFill concurrently (double-submit). */
+    private readonly inFlight;
+    /** Cloids WE deliberately cancelled (resize/modify supersede, retry cleanup,
+     *  cancelBrackets). Their WS 'canceled' events are OUR OWN and must never
+     *  trip the stripped-protection canary — the T-8 testnet run proved the WS
+     *  event can arrive BEFORE the ledger's fresh-cid update lands, so a
+     *  generation check alone loses the race. Entries pruned after 5 min. */
+    private readonly ownCancels;
+    constructor(executor: HlBracketExecutor, ledger: BracketLedger, opts?: HlCoordinatorOpts);
+    getLedger(): BracketLedger;
+    /** Record a leg cancel WE initiated (see `ownCancels`). The adapter calls
+     *  this for every deliberate leg cancel, including the resize path's direct
+     *  api cancels, BEFORE the cancel request goes out. */
+    noteOwnLegCancel(cloid: string): void;
+    /** Same anti-clobber contract as BracketManager.registerEntry: a duplicate
+     *  fill signal against a non-terminal row is a warned NO-OP, never a fresh
+     *  bracketId that orphans the live legs' ledger identity. */
+    registerEntry(req: BracketRequest, bracketId: BracketId, entryCid: string): void;
+    /** Attach both legs (ONE batched signed action) with retries. Idempotent on
+     *  a non-pending row. On exhaustion: ledger 'failed' + attach_failed event —
+     *  the ADAPTER escalates to auto-flatten (it owns closePosition). */
+    attachOnFill(symbol: string, filledSize: number): Promise<HlAttachResult>;
+    /** ★ T-2: bring the legs to the CURRENT position size (scale-in / partial
+     *  fill growth). Submit-first-then-cancel inside the adapter. Updates the
+     *  ledger's qty + fresh cids on success. */
+    resizeToPosition(symbol: string, newPositionSize: number): Promise<{
+        resized: boolean;
+    }>;
+    /** Move the stop. HL ordering: submit the NEW leg first, then cancel the old
+     *  one — over-protection for a moment beats a naked window (see header). */
+    modifyStop(symbol: string, newStopPrice: number): Promise<void>;
+    modifyTarget(symbol: string, newTargetPrice: number): Promise<void>;
+    private modifyLeg;
+    /** Cancel both legs, mark cancelled. Risk-reducing; best-effort per leg. */
+    cancelBrackets(symbol: string, reason: string): Promise<void>;
+    /**
+     * The HL analog of the Binance ALGO_UPDATE handler — `orderUpdates` is
+     * authoritative for bracket-leg lifecycle. Returns the transition applied
+     * (for the adapter to emit drift/close-bypass signals on triggers).
+     */
+    handleOrderUpdate(update: HlOrderUpdateEvent): 'triggered_sl' | 'triggered_tp' | 'forced_close' | null;
+    /**
+     * ★ T-5 mandate: REST truth-check. Runs after every WS (re)connect AND on the
+     * periodic sweep. TRUSTED reads only — a null positions fetch skips the pass
+     * (never act on unknown). Self-heals: pending rows whose entry filled while
+     * we were blind get their legs attached; undersized legs get resized; flat
+     * positions get their rows closed out (T-1 already cancelled the legs).
+     * Returns symbols whose rows were closed out (close-bypass signals for the
+     * adapter's drift pipeline).
+     */
+    resyncAgainstExchange(reasonTag: string): Promise<{
+        closedSymbols: string[];
+    }>;
+    private emitEvent;
+}

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

@@ -0,0 +1,533 @@
+// HlBracketCoordinator — orchestrates the lifecycle of Hyperliquid bracket legs
+// (issue #209: the wiring that Phase 3 shipped the machinery for).
+//
+// A SIBLING of live/bracket-manager.ts, not a reuse of it: BracketManager's leg
+// layer is Binance-shaped (sequential STOP_MARKET/TAKE_PROFIT_MARKET submits,
+// closePosition:true whole-position semantics, `bkt…` cids), while HL brackets
+// are fixed-size reduce-only trigger legs submitted as ONE batched signed action
+// (nonce mutex — see hl-brackets.ts). The ORCHESTRATION is deliberately the
+// same shape: registerEntry → attach-on-fill with retries → auto-flatten
+// escalation on failure, persisted in the SAME venue-agnostic BracketLedger
+// (its own file — `new BracketLedger('<pluginId>-hl')` — so a venue switch can
+// never cross-contaminate rows), emitting the SAME BracketEvent shapes.
+//
+// THE MEASURED FACTS THIS FILE TURNS ON (testnet 2026-07-12, do NOT re-derive):
+//   ★ T-1: reduce-only trigger legs auto-cancel on flat and behave OCO — no
+//     sibling-canceller needed; a defensive cancel is harmless.
+//   ★ T-2: legs are FIXED SIZE and do NOT follow a scale-in — every position
+//     size increase MUST resize the legs or the added contracts are NAKED.
+//   ★ T-5: the WS replays NOTHING on reconnect — `onResyncNeeded` drives a REST
+//     truth-check here (`resyncAgainstExchange`), and a periodic sweep runs the
+//     same check even while connected (a dropped frame is invisible).
+//
+// Modify semantics differ from Binance ON PURPOSE: Binance modifyStop cancels
+// the old leg then submits the new one (with rollback). On HL we SUBMIT FIRST,
+// then cancel the stale leg — two live reduce-only stops for a few hundred ms
+// are over-protection (reduce-only cannot flip a position, and T-1 cleans up
+// stragglers on flat), whereas cancel-first opens a naked window. Same ordering
+// rule as planResize.
+import { EventEmitter } from 'node:events';
+import { logger, formatError } from '../../logger.js';
+import { parseHlBracketCloid } from './hl-cloid.js';
+const TAG = 'hl-bracket-coordinator';
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_BACKOFF = (attempt) => (attempt === 1 ? 1_000 : 2_000);
+const TERMINAL_STATES = new Set([
+    'triggered_sl',
+    'triggered_tp',
+    'cancelled',
+    'failed',
+]);
+export function isTerminalBracketState(state) {
+    return TERMINAL_STATES.has(state);
+}
+/** Order-update statuses that mean the leg EXECUTED (position closed by it). */
+const TRIGGERED_STATUSES = new Set(['filled', 'triggered']);
+/** A batch item HL rejected. ccxt types status as open|closed|canceled, but a
+ *  per-item rejection surfaces as an `error` entry in the raw batch response
+ *  (`info.error`) — check both shapes rather than trust the narrow type. */
+function isRejectedOrder(o) {
+    if (!o)
+        return true;
+    if (String(o.status ?? '') === 'rejected')
+        return true;
+    const info = o.info;
+    return Boolean(info && info.error);
+}
+/** Expected T-1 cleanup — the sibling of a fired leg self-cancels. */
+const SIBLING_CLEANUP_STATUSES = new Set(['siblingFilledCanceled']);
+/** The position was force-closed out from under the bracket. */
+const FORCED_CLOSE_STATUSES = new Set(['liquidatedCanceled', 'marginCanceled', 'delistedCanceled']);
+export class HlBracketCoordinator extends EventEmitter {
+    executor;
+    ledger;
+    maxAttempts;
+    backoff;
+    now;
+    sleep;
+    /** Per-symbol in-flight guard so a WS fill + the createOrder return path
+     *  can't both run attachOnFill concurrently (double-submit). */
+    inFlight = new Set();
+    /** Cloids WE deliberately cancelled (resize/modify supersede, retry cleanup,
+     *  cancelBrackets). Their WS 'canceled' events are OUR OWN and must never
+     *  trip the stripped-protection canary — the T-8 testnet run proved the WS
+     *  event can arrive BEFORE the ledger's fresh-cid update lands, so a
+     *  generation check alone loses the race. Entries pruned after 5 min. */
+    ownCancels = new Map();
+    constructor(executor, ledger, opts = {}) {
+        super();
+        this.executor = executor;
+        this.ledger = ledger;
+        this.maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+        this.backoff = opts.retryBackoffMs ?? DEFAULT_BACKOFF;
+        this.now = opts.now ?? Date.now;
+        this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    }
+    getLedger() {
+        return this.ledger;
+    }
+    /** Record a leg cancel WE initiated (see `ownCancels`). The adapter calls
+     *  this for every deliberate leg cancel, including the resize path's direct
+     *  api cancels, BEFORE the cancel request goes out. */
+    noteOwnLegCancel(cloid) {
+        const now = this.now();
+        for (const [k, ts] of this.ownCancels) {
+            if (now - ts > 300_000)
+                this.ownCancels.delete(k);
+        }
+        this.ownCancels.set(cloid, now);
+    }
+    /** Same anti-clobber contract as BracketManager.registerEntry: a duplicate
+     *  fill signal against a non-terminal row is a warned NO-OP, never a fresh
+     *  bracketId that orphans the live legs' ledger identity. */
+    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);
+        if (existing && !isTerminalBracketState(existing.state)) {
+            logger.warn(TAG, `registerEntry(${req.symbol}): non-terminal row exists (state=${existing.state}, ` +
+                `bracketId=${existing.bracketId}) — duplicate fill signal, NOT clobbering ` +
+                `(anti-clobber contract; scale-ins go through resizeToPosition)`);
+            return;
+        }
+        if (existing)
+            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(),
+        });
+    }
+    /** Attach both legs (ONE batched signed action) with retries. Idempotent on
+     *  a non-pending row. On exhaustion: ledger 'failed' + attach_failed event —
+     *  the ADAPTER escalates to auto-flatten (it owns closePosition). */
+    async attachOnFill(symbol, filledSize) {
+        const entry = this.ledger.getBySymbol(symbol);
+        if (!entry)
+            throw new Error(`attachOnFill: no ledger entry for ${symbol}`);
+        if (entry.state !== 'pending_entry') {
+            return {
+                ok: entry.state === 'active' || entry.state === 'partial',
+                latencyMs: entry.attachLatencyMs ?? 0,
+                slCid: entry.slCid,
+                tpCid: entry.tpCid,
+                attempts: 0,
+            };
+        }
+        if (this.inFlight.has(entry.symbol)) {
+            logger.warn(TAG, `attachOnFill(${symbol}): attach already in flight — skipping duplicate`);
+            return { ok: false, latencyMs: 0, attempts: 0, error: 'attach_in_flight' };
+        }
+        this.inFlight.add(entry.symbol);
+        try {
+            const startTs = this.now();
+            this.ledger.markState(symbol, 'attaching', {
+                attachStartedAt: new Date(startTs).toISOString(),
+            });
+            this.emitEvent({
+                type: 'bracket.entry_filled',
+                bracketId: entry.bracketId,
+                symbol: entry.symbol,
+                ts: new Date(startTs).toISOString(),
+            });
+            const positionSide = entry.entrySide === 'buy' ? 'long' : 'short';
+            let lastError;
+            for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+                let slCid;
+                let tpCid;
+                try {
+                    const res = await this.executor.attachBrackets({
+                        bracketId: entry.bracketId,
+                        symbol: entry.symbol,
+                        positionSide,
+                        positionSize: filledSize,
+                        stopPrice: entry.stopPrice,
+                        targetPrice: entry.targetPrice,
+                    });
+                    slCid = res.slCid;
+                    tpCid = res.tpCid;
+                    const wanted = (entry.stopPrice !== undefined ? 1 : 0) + (entry.targetPrice !== undefined ? 1 : 0);
+                    const rejected = res.orders.filter((o) => isRejectedOrder(o));
+                    if (res.orders.length < wanted || rejected.length > 0) {
+                        throw new Error(`batch returned ${res.orders.length}/${wanted} legs` +
+                            (rejected.length ? ` (${rejected.length} rejected)` : ''));
+                    }
+                    const latencyMs = this.now() - startTs;
+                    const targetState = slCid && tpCid ? 'active' : 'partial';
+                    this.ledger.markState(symbol, targetState, {
+                        attachCompletedAt: new Date(this.now()).toISOString(),
+                        attachLatencyMs: latencyMs,
+                        slCid,
+                        tpCid,
+                        // Freeze the size the legs were sized to — modify/resize MUST reuse
+                        // it (the Binance 1-contract under-protect lesson carries over).
+                        qty: filledSize,
+                    });
+                    this.emitEvent({
+                        type: 'bracket.attached',
+                        bracketId: entry.bracketId,
+                        symbol: entry.symbol,
+                        latencyMs,
+                        ts: new Date(this.now()).toISOString(),
+                    });
+                    return { ok: true, latencyMs, slCid, tpCid, attempts: attempt };
+                }
+                catch (err) {
+                    lastError = formatError(err);
+                    this.emitEvent({
+                        type: 'bracket.attach_failed',
+                        bracketId: entry.bracketId,
+                        symbol: entry.symbol,
+                        error: lastError,
+                        retryCount: attempt,
+                        ts: new Date(this.now()).toISOString(),
+                    });
+                    // A failed/partial batch may have left a leg on the book. Cancel
+                    // best-effort before retrying with FRESH cloids (a cloid is
+                    // single-use) so the exchange never runs ahead of the ledger.
+                    // T-1 makes a missed cancel harmless (auto-cleanup on flat).
+                    for (const cloid of [slCid, tpCid]) {
+                        if (!cloid)
+                            continue;
+                        try {
+                            await this.executor.cancelBracketLeg(cloid, entry.symbol);
+                        }
+                        catch {
+                            /* idempotent best-effort */
+                        }
+                    }
+                    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 };
+        }
+        finally {
+            this.inFlight.delete(entry.symbol);
+        }
+    }
+    /** ★ T-2: bring the legs to the CURRENT position size (scale-in / partial
+     *  fill growth). Submit-first-then-cancel inside the adapter. Updates the
+     *  ledger's qty + fresh cids on success. */
+    async resizeToPosition(symbol, newPositionSize) {
+        const entry = this.ledger.getBySymbol(symbol);
+        if (!entry)
+            throw new Error(`resizeToPosition: no ledger entry for ${symbol}`);
+        if (entry.state !== 'active' && entry.state !== 'partial') {
+            throw new Error(`resizeToPosition: cannot resize in state ${entry.state}`);
+        }
+        if (!Number.isFinite(newPositionSize) || newPositionSize <= 0) {
+            throw new Error(`resizeToPosition: invalid size ${newPositionSize}`);
+        }
+        const positionSide = entry.entrySide === 'buy' ? 'long' : 'short';
+        const res = await this.executor.resizeBrackets({
+            bracketId: entry.bracketId,
+            symbol: entry.symbol,
+            positionSide,
+            positionSize: newPositionSize,
+        });
+        if (res.resized) {
+            this.ledger.markState(symbol, entry.state, {
+                qty: newPositionSize,
+                ...(res.slCid ? { slCid: res.slCid } : {}),
+                ...(res.tpCid ? { tpCid: res.tpCid } : {}),
+            });
+            logger.info(TAG, `resized ${entry.symbol} legs to ${newPositionSize} (T-2: HL legs do not auto-resize)`);
+        }
+        return { resized: res.resized };
+    }
+    /** Move the stop. HL ordering: submit the NEW leg first, then cancel the old
+     *  one — over-protection for a moment beats a naked window (see header). */
+    async modifyStop(symbol, newStopPrice) {
+        await this.modifyLeg(symbol, 'stop', newStopPrice);
+    }
+    async modifyTarget(symbol, newTargetPrice) {
+        await this.modifyLeg(symbol, 'target', newTargetPrice);
+    }
+    async modifyLeg(symbol, role, newPrice) {
+        if (!Number.isFinite(newPrice) || newPrice <= 0) {
+            throw new Error(`modify ${role}: price must be positive finite, got ${newPrice}`);
+        }
+        const entry = this.ledger.getBySymbol(symbol);
+        if (!entry)
+            throw new Error(`modify ${role}: no ledger entry for ${symbol}`);
+        if (entry.state !== 'active' && entry.state !== 'partial') {
+            throw new Error(`modify ${role}: cannot modify in state ${entry.state}`);
+        }
+        const qty = entry.qty;
+        if (qty === undefined || !Number.isFinite(qty) || qty <= 0) {
+            throw new Error(`modify ${role}: ledger has no valid bracket qty for ${symbol} (qty=${qty}); ` +
+                `refusing to rebuild the leg at a placeholder size — re-attach the bracket first`);
+        }
+        const oldCid = role === 'stop' ? entry.slCid : entry.tpCid;
+        const positionSide = entry.entrySide === 'buy' ? 'long' : 'short';
+        // SUBMIT the replacement first. On failure the old leg is still live —
+        // the position stays protected and we just report the error.
+        const res = await this.executor.attachBrackets({
+            bracketId: entry.bracketId,
+            symbol: entry.symbol,
+            positionSide,
+            positionSize: qty,
+            ...(role === 'stop' ? { stopPrice: newPrice } : { targetPrice: newPrice }),
+        });
+        const newCid = role === 'stop' ? res.slCid : res.tpCid;
+        const submitted = res.orders.filter((o) => !isRejectedOrder(o));
+        if (!newCid || submitted.length === 0) {
+            throw new Error(`modify ${role}: replacement leg submission failed — old leg left in place (still protected)`);
+        }
+        // Then cancel the stale leg. A failed cancel = brief over-protection (two
+        // reduce-only legs), which T-1 cleans up on flat — warn, don't throw.
+        if (oldCid) {
+            try {
+                await this.executor.cancelBracketLeg(oldCid, entry.symbol);
+            }
+            catch (err) {
+                logger.warn(TAG, `modify ${role}(${symbol}): stale leg ${oldCid} cancel failed (over-protection, ` +
+                    `not risk — T-1 cleans up on flat): ${formatError(err)}`);
+            }
+        }
+        const oldPrice = role === 'stop' ? entry.stopPrice : entry.targetPrice;
+        this.ledger.upsert({
+            ...entry,
+            ...(role === 'stop'
+                ? { stopPrice: newPrice, slCid: newCid }
+                : { targetPrice: newPrice, tpCid: newCid }),
+        });
+        this.emitEvent({
+            type: 'bracket.modified',
+            bracketId: entry.bracketId,
+            symbol: entry.symbol,
+            field: role,
+            oldValue: oldPrice ?? NaN,
+            newValue: newPrice,
+            ts: new Date(this.now()).toISOString(),
+        });
+    }
+    /** Cancel both legs, mark cancelled. Risk-reducing; best-effort per leg. */
+    async cancelBrackets(symbol, reason) {
+        const entry = this.ledger.getBySymbol(symbol);
+        if (!entry)
+            return;
+        for (const cloid of [entry.slCid, entry.tpCid]) {
+            if (!cloid)
+                continue;
+            try {
+                await this.executor.cancelBracketLeg(cloid, entry.symbol);
+            }
+            catch (err) {
+                logger.warn(TAG, `cancelBrackets ${entry.symbol} leg ${cloid}: ${formatError(err)}`);
+            }
+        }
+        this.ledger.markState(symbol, 'cancelled', { closeReason: 'cancelled_manual' });
+        this.emitEvent({
+            type: 'bracket.cancelled',
+            bracketId: entry.bracketId,
+            symbol: entry.symbol,
+            reason,
+            ts: new Date(this.now()).toISOString(),
+        });
+    }
+    /**
+     * The HL analog of the Binance ALGO_UPDATE handler — `orderUpdates` is
+     * authoritative for bracket-leg lifecycle. Returns the transition applied
+     * (for the adapter to emit drift/close-bypass signals on triggers).
+     */
+    handleOrderUpdate(update) {
+        const cloid = update.order?.cloid;
+        if (!cloid)
+            return null;
+        const parsed = parseHlBracketCloid(cloid);
+        if (!parsed || parsed.role === 'entry')
+            return null;
+        const status = update.status;
+        const coin = update.order.coin;
+        const entry = this.ledger.getByBracketId(parsed.bracketId);
+        if (!entry)
+            return null;
+        if (TRIGGERED_STATUSES.has(status)) {
+            if (isTerminalBracketState(entry.state))
+                return null; // duplicate signal
+            const next = parsed.role === 'stop' ? 'triggered_sl' : 'triggered_tp';
+            this.ledger.markState(entry.symbol, next, {
+                closeReason: parsed.role === 'stop' ? 'triggered_sl' : 'triggered_tp',
+            });
+            this.emitEvent({
+                type: 'bracket.triggered',
+                bracketId: entry.bracketId,
+                symbol: entry.symbol,
+                side: parsed.role === 'stop' ? 'sl' : 'tp',
+                ts: new Date(this.now()).toISOString(),
+            });
+            logger.info(TAG, `${entry.symbol} ${parsed.role} leg fired (coin=${coin}, status=${status})`);
+            return next;
+        }
+        if (SIBLING_CLEANUP_STATUSES.has(status)) {
+            // Expected T-1 OCO cleanup after the sibling fired — benign.
+            logger.info(TAG, `${entry.symbol} ${parsed.role} leg sibling-cancelled (T-1 cleanup)`);
+            return null;
+        }
+        if (FORCED_CLOSE_STATUSES.has(status)) {
+            if (!isTerminalBracketState(entry.state)) {
+                this.ledger.markState(entry.symbol, 'cancelled', {
+                    closeReason: 'cancelled_auto',
+                    lastError: `leg ${status}`,
+                });
+            }
+            logger.warn(TAG, `${entry.symbol} ${parsed.role} leg ${status} — position force-closed by the exchange`);
+            return 'forced_close';
+        }
+        if (status === 'canceled' && (entry.state === 'active' || entry.state === 'partial')) {
+            // CANCELED-while-active without a trigger/sibling reason = something
+            // stripped protection. Same WARN canary as the Binance ALGO_UPDATE rule.
+            // ONLY for cancels we did NOT initiate: resize/modify supersede legs
+            // with fresh cloids and then cancel the stale ones, and the WS 'canceled'
+            // event can arrive BEFORE the ledger's fresh-cid update (race observed
+            // live on the T-8 testnet run) — so the check is the explicit own-cancel
+            // registry, backstopped by the generation check.
+            const isCurrentLeg = cloid === entry.slCid || cloid === entry.tpCid;
+            if (isCurrentLeg && !this.ownCancels.has(cloid)) {
+                logger.warn(TAG, `CANARY: ${entry.symbol} ${parsed.role} leg CANCELED while bracket ${entry.state} — ` +
+                    `protection may have been stripped out-of-band; coverage audit will re-attach`);
+            }
+        }
+        return null;
+    }
+    /**
+     * ★ T-5 mandate: REST truth-check. Runs after every WS (re)connect AND on the
+     * periodic sweep. TRUSTED reads only — a null positions fetch skips the pass
+     * (never act on unknown). Self-heals: pending rows whose entry filled while
+     * we were blind get their legs attached; undersized legs get resized; flat
+     * positions get their rows closed out (T-1 already cancelled the legs).
+     * Returns symbols whose rows were closed out (close-bypass signals for the
+     * adapter's drift pipeline).
+     */
+    async resyncAgainstExchange(reasonTag) {
+        const closedSymbols = [];
+        const rows = this.ledger.getAll().filter((r) => !isTerminalBracketState(r.state));
+        if (rows.length === 0)
+            return { closedSymbols };
+        const positions = await this.executor.getPositionsOrNull();
+        if (positions === null) {
+            logger.warn(TAG, `resync(${reasonTag}): positions fetch FAILED — state UNKNOWN, skipping this pass ` +
+                `(null ≠ empty; acting would risk closing rows for live positions)`);
+            return { closedSymbols };
+        }
+        const sizeBySymbol = new Map();
+        for (const p of positions) {
+            const contracts = Math.abs(Number(p.contracts ?? 0));
+            if (contracts > 0 && p.symbol)
+                sizeBySymbol.set(baseOf(p.symbol), contracts);
+        }
+        for (const row of rows) {
+            const liveSize = sizeBySymbol.get(baseOf(row.symbol)) ?? 0;
+            if (liveSize === 0) {
+                // Exchange is flat. T-1 already auto-cancelled any legs. If the row
+                // was active, the trigger event was missed (T-5) — close the row out
+                // and let the adapter surface a close-bypass drift.
+                if (row.state === 'active' || row.state === 'partial') {
+                    logger.warn(TAG, `resync(${reasonTag}): ${row.symbol} flat on exchange while bracket ${row.state} — ` +
+                        `missed trigger/close during a WS gap; closing the row (legs auto-cancel on flat, T-1)`);
+                    this.ledger.markState(row.symbol, 'cancelled', {
+                        closeReason: 'cancelled_auto',
+                        lastError: `resync_position_flat:${reasonTag}`,
+                    });
+                    closedSymbols.push(row.symbol);
+                }
+                else {
+                    // pending_entry/attaching with no position: entry never filled (or
+                    // filled and closed inside the gap — the journal reconcile owns
+                    // that). Remove the stale row so the next entry starts clean.
+                    logger.info(TAG, `resync(${reasonTag}): ${row.symbol} row ${row.state} with no position — clearing stale row`);
+                    this.ledger.markState(row.symbol, 'cancelled', {
+                        closeReason: 'cancelled_auto',
+                        lastError: `resync_no_position:${reasonTag}`,
+                    });
+                }
+                continue;
+            }
+            // Position is live.
+            if (row.state === 'pending_entry') {
+                // Entry filled while we were blind — attach now, sized to the position.
+                logger.warn(TAG, `resync(${reasonTag}): ${row.symbol} position live (${liveSize}) with bracket still ` +
+                    `pending_entry — the fill event was missed; attaching legs now`);
+                const res = await this.attachOnFill(row.symbol, liveSize).catch((err) => {
+                    logger.error(TAG, `resync attach failed for ${row.symbol}: ${formatError(err)}`);
+                    return null;
+                });
+                if (res && !res.ok) {
+                    this.emitEvent({
+                        type: 'bracket.attach_failed',
+                        bracketId: row.bracketId,
+                        symbol: row.symbol,
+                        error: res.error ?? 'resync attach failed',
+                        retryCount: res.attempts,
+                        ts: new Date(this.now()).toISOString(),
+                    });
+                }
+                continue;
+            }
+            if (row.state === 'active' || row.state === 'partial') {
+                // ★ T-2 invariant: do the live legs cover the live size?
+                try {
+                    const audit = await this.executor.auditBracketCoverage(row.symbol, liveSize);
+                    if (!audit.covered) {
+                        logger.warn(TAG, `resync(${reasonTag}): ${row.symbol} legs do NOT cover position ` +
+                            `(size=${liveSize}, shortfall=${JSON.stringify(audit.shortfall)}, ` +
+                            `missing=${audit.missing.join(',') || 'none'}) — resizing (naked size is a ` +
+                            `safety-floor breach)`);
+                        await this.resizeToPosition(row.symbol, liveSize);
+                    }
+                }
+                catch (err) {
+                    // getOpenOrders threw (unknown state) — honest skip, next sweep retries.
+                    logger.warn(TAG, `resync(${reasonTag}): ${row.symbol} coverage unverifiable (${formatError(err)}) — ` +
+                        `not acting on unknown state; next sweep retries`);
+                }
+            }
+        }
+        return { closedSymbols };
+    }
+    emitEvent(event) {
+        this.emit('event', event);
+    }
+}
+/** Compare symbols by base asset (`BTC/USDC` vs `BTC/USDC:USDC`). */
+function baseOf(symbol) {
+    return symbol.split(':')[0];
+}