@reefclaw/openclaw-plugin 0.1.5 → 0.1.7

package/wave9/live-residual-protection.js

@@ -0,0 +1,250 @@
+import { formatError } from '../logger.js';
+import { generateBracketId, parseBracketCid } from '../live/bracket-id.js';
+import { confirmWave9LiveNativeStop } from './live-account-capture.js';
+const NON_TERMINAL_BRACKET_STATES = new Set(['pending_entry', 'attaching', 'active', 'partial']);
+function canonicalSymbol(symbol) {
+    return symbol.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+}
+function sameQuantity(left, right) {
+    return Math.abs(left - right) <= 1e-9 * Math.max(1, Math.abs(left), Math.abs(right));
+}
+function bracketCids(orders) {
+    const cids = new Set();
+    for (const order of orders) {
+        if (order.status !== 'open' || !order.clientOrderId)
+            continue;
+        const parsed = parseBracketCid(order.clientOrderId);
+        if (parsed?.role === 'stop' || parsed?.role === 'target')
+            cids.add(order.clientOrderId);
+    }
+    return [...cids].sort((left, right) => left.localeCompare(right));
+}
+function manual(candidateId, symbol, stopPrice, detail, residualQuantity) {
+    return {
+        status: 'manual_intervention',
+        detail: `IMMEDIATE MANUAL INTERVENTION REQUIRED: ${detail}`,
+        candidateId,
+        symbol,
+        stopPrice,
+        ...(residualQuantity !== undefined ? { residualQuantity } : {}),
+    };
+}
+function asResidualProtectionAdapter(adapter) {
+    const candidate = adapter;
+    return typeof candidate.getBracketManager === 'function'
+        && typeof candidate.getBracketLedger === 'function'
+        && typeof candidate.cancelSymbolBracketOrders === 'function'
+        && typeof candidate.resolveBracketLegLiveness === 'function'
+        && typeof candidate.resolveBracketLegProof === 'function'
+        ? candidate
+        : null;
+}
+/**
+ * Re-arm the exact frozen Wave 9 stop after a reduce-only close leaves a
+ * residual. Success means one current residual was observed and its newly
+ * candidate-bound native close-all STOP_MARKET was proven by exact CID.
+ * Every unverifiable state remains OPEN and escalates manual intervention.
+ */
+export async function reprotectWave9LiveResidual(adapter, executionLedger, candidateId, symbol) {
+    const record = executionLedger.getByCandidateId(candidateId);
+    const fallbackStop = record?.initialStop ?? 0;
+    if (!record || record.state === 'closed') {
+        return manual(candidateId, symbol, fallbackStop, 'durable Wave 9 execution ownership is unavailable');
+    }
+    if (record.symbol !== canonicalSymbol(symbol)) {
+        return manual(candidateId, symbol, record.initialStop, 'candidate symbol does not match the residual symbol');
+    }
+    const native = asResidualProtectionAdapter(adapter);
+    if (!native) {
+        return manual(candidateId, symbol, record.initialStop, 'native bracket re-protection capability is unavailable');
+    }
+    const manager = native.getBracketManager();
+    const bracketLedger = native.getBracketLedger();
+    if (!manager || !bracketLedger) {
+        return manual(candidateId, symbol, record.initialStop, 'native bracket manager or ledger is unavailable');
+    }
+    let positions;
+    try {
+        positions = await adapter.getPositionsOrNull(symbol);
+    }
+    catch (err) {
+        return manual(candidateId, symbol, record.initialStop, `residual position read threw: ${formatError(err)}`);
+    }
+    if (positions === null) {
+        return manual(candidateId, symbol, record.initialStop, 'residual position state is unknown');
+    }
+    const matches = positions.filter((position) => canonicalSymbol(position.symbol) === record.symbol
+        && typeof position.contracts === 'number'
+        && Number.isFinite(position.contracts)
+        && position.contracts > 0);
+    if (matches.length !== 1) {
+        return manual(candidateId, symbol, record.initialStop, matches.length === 0
+            ? 'no residual is currently visible, but stable flat was not established'
+            : 'multiple residual positions match the candidate symbol');
+    }
+    const residual = matches[0];
+    const expectedSide = record.side === 'buy' ? 'long' : 'short';
+    if (residual.side !== expectedSide) {
+        return manual(candidateId, symbol, record.initialStop, `residual side ${residual.side} does not match candidate side ${expectedSide}`, residual.contracts);
+    }
+    const maximumAuthorizedQuantity = record.filledQuantity ?? record.quantity;
+    if (residual.contracts > maximumAuthorizedQuantity
+        && !sameQuantity(residual.contracts, maximumAuthorizedQuantity)) {
+        return manual(candidateId, symbol, record.initialStop, `residual quantity ${residual.contracts} exceeds authorized quantity ${maximumAuthorizedQuantity}`, residual.contracts);
+    }
+    const confirmationInput = {
+        candidateId,
+        symbol,
+        entryClientOrderId: record.clientOrderId,
+        entrySide: record.side,
+        stopPrice: record.initialStop,
+        filledQuantity: residual.contracts,
+    };
+    try {
+        if (await confirmWave9LiveNativeStop(adapter, confirmationInput)) {
+            const existing = bracketLedger.getBySymbol(symbol);
+            return {
+                status: 'protected',
+                detail: 'existing exact candidate-bound native close-all stop is proven live',
+                candidateId,
+                symbol,
+                stopPrice: record.initialStop,
+                residualQuantity: residual.contracts,
+                ...(existing?.slCid ? { stopClientOrderId: existing.slCid } : {}),
+            };
+        }
+    }
+    catch {
+        // Continue only when it is safe to replace a terminal/missing row below.
+    }
+    const existing = bracketLedger.getBySymbol(symbol);
+    let inventoriedCids;
+    try {
+        const openOrders = await adapter.getOpenOrders(symbol);
+        if (!Array.isArray(openOrders))
+            throw new Error('open-order inventory was not an array');
+        inventoriedCids = bracketCids(openOrders);
+    }
+    catch (err) {
+        return manual(candidateId, symbol, record.initialStop, `could not obtain trusted pre-cancel bracket inventory: ${formatError(err)}`, residual.contracts);
+    }
+    // Never cancel a stop that may still be protecting the position. A direct
+    // exact-stop confirmation above already accepted the fully valid case. If
+    // any other stored/inventoried stop is live or its state is unknown, retain
+    // it and escalate instead of creating a cancel-then-attach protection gap.
+    const inventoriedStopCids = inventoriedCids.filter((cid) => parseBracketCid(cid)?.role === 'stop');
+    const stopCidsToProve = [...new Set([
+            ...inventoriedStopCids,
+            ...(existing?.slCid ? [existing.slCid] : []),
+        ])].sort((left, right) => left.localeCompare(right));
+    for (const cid of stopCidsToProve) {
+        let liveness;
+        try {
+            liveness = await native.resolveBracketLegLiveness(cid);
+        }
+        catch {
+            liveness = 'unknown';
+        }
+        if (liveness !== 'terminal') {
+            return manual(candidateId, symbol, record.initialStop, `existing stop ${cid} is ${liveness}; retaining it rather than opening a cancel/re-arm gap`, residual.contracts);
+        }
+    }
+    try {
+        await native.cancelSymbolBracketOrders(symbol);
+    }
+    catch (err) {
+        return manual(candidateId, symbol, record.initialStop, `could not cancel stale bracket orders before re-arm: ${formatError(err)}`, residual.contracts);
+    }
+    const oldCids = [...new Set([
+            ...inventoriedCids,
+            ...[existing?.slCid, existing?.tpCid].filter((cid) => !!cid),
+        ])].sort((left, right) => left.localeCompare(right));
+    for (const cid of oldCids) {
+        let liveness;
+        try {
+            liveness = await native.resolveBracketLegLiveness(cid);
+        }
+        catch {
+            liveness = 'unknown';
+        }
+        if (liveness !== 'terminal') {
+            return manual(candidateId, symbol, record.initialStop, `prior bracket leg ${cid} is ${liveness}; refusing an unverified duplicate stop`, residual.contracts);
+        }
+    }
+    try {
+        const afterCancel = await adapter.getOpenOrders(symbol);
+        if (!Array.isArray(afterCancel))
+            throw new Error('post-cancel open-order inventory was not an array');
+        const remainingBracketCids = bracketCids(afterCancel);
+        if (remainingBracketCids.length > 0) {
+            return manual(candidateId, symbol, record.initialStop, `post-cancel inventory still contains bracket leg(s): ${remainingBracketCids.join(', ')}`, residual.contracts);
+        }
+    }
+    catch (err) {
+        return manual(candidateId, symbol, record.initialStop, `could not prove a clean post-cancel bracket inventory: ${formatError(err)}`, residual.contracts);
+    }
+    const currentBracket = bracketLedger.getBySymbol(symbol);
+    if (currentBracket && (!existing || currentBracket.bracketId !== existing.bracketId)) {
+        return manual(candidateId, symbol, record.initialStop, 'bracket ownership changed during residual re-protection', residual.contracts);
+    }
+    if (currentBracket && NON_TERMINAL_BRACKET_STATES.has(currentBracket.state)) {
+        try {
+            bracketLedger.markState(symbol, 'cancelled', {
+                closeReason: 'cancelled_auto',
+            });
+        }
+        catch (err) {
+            return manual(candidateId, symbol, record.initialStop, `could not terminalize the proven-cancelled bracket row: ${formatError(err)}`, residual.contracts);
+        }
+    }
+    let currentResidualQuantity;
+    try {
+        const currentPositions = await adapter.getPositionsOrNull(symbol);
+        if (currentPositions === null)
+            throw new Error('position state is unknown');
+        const currentMatches = currentPositions.filter((position) => canonicalSymbol(position.symbol) === record.symbol
+            && typeof position.contracts === 'number'
+            && Number.isFinite(position.contracts)
+            && position.contracts > 0);
+        if (currentMatches.length !== 1 || currentMatches[0].side !== expectedSide) {
+            throw new Error(currentMatches.length === 0
+                ? 'no residual is visible after cancellation, but stable flat was not established'
+                : 'residual identity changed during bracket cancellation');
+        }
+        currentResidualQuantity = currentMatches[0].contracts;
+        if (currentResidualQuantity > maximumAuthorizedQuantity
+            && !sameQuantity(currentResidualQuantity, maximumAuthorizedQuantity)) {
+            throw new Error(`residual quantity ${currentResidualQuantity} exceeds authorized quantity ${maximumAuthorizedQuantity}`);
+        }
+    }
+    catch (err) {
+        return manual(candidateId, symbol, record.initialStop, `could not bind the current residual after cancellation: ${formatError(err)}`, residual.contracts);
+    }
+    const bracketId = generateBracketId();
+    try {
+        manager.registerEntry({ symbol, side: record.side, stopPrice: record.initialStop }, bracketId, record.clientOrderId);
+        const attached = await manager.attachBrackets(symbol, currentResidualQuantity);
+        if (!attached.ok || !attached.slCid) {
+            return manual(candidateId, symbol, record.initialStop, `exact frozen stop attach failed after ${attached.attempts} attempt(s): ${attached.error ?? 'no stop CID'}`, currentResidualQuantity);
+        }
+        const verified = await confirmWave9LiveNativeStop(adapter, {
+            ...confirmationInput,
+            filledQuantity: currentResidualQuantity,
+        });
+        if (!verified) {
+            return manual(candidateId, symbol, record.initialStop, `new stop ${attached.slCid} could not be proven as the exact native close-all STOP_MARKET`, currentResidualQuantity);
+        }
+        return {
+            status: 'protected',
+            detail: 'exact frozen candidate-bound native close-all stop was re-attached and proven live',
+            candidateId,
+            symbol,
+            stopPrice: record.initialStop,
+            residualQuantity: currentResidualQuantity,
+            stopClientOrderId: attached.slCid,
+        };
+    }
+    catch (err) {
+        return manual(candidateId, symbol, record.initialStop, `exact frozen stop re-arm threw: ${formatError(err)}`, currentResidualQuantity);
+    }
+}

package/wave9/live-startup-reconciliation.d.ts

@@ -0,0 +1,38 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import { type Wave9LiveStopConfirmationInput } from './live-account-capture.js';
+import { recoverWave9LiveExposure, type Wave9LiveAutonomousProtectionOptions } from './live-autonomous-protection.js';
+import type { Wave9LiveExecutionLedger } from './live-execution-ledger.js';
+import { type Wave9LiveFlatConfirmation, type Wave9LiveFlatConfirmationOptions } from './live-position-confirmation.js';
+export type Wave9LiveStartupRowStatus = 'protected' | 'closed' | 'manual_intervention';
+export interface Wave9LiveStartupRowResult {
+    candidateId: string;
+    symbol: string;
+    priorState: 'attempted' | 'open';
+    status: Wave9LiveStartupRowStatus;
+    detail: string;
+    /** True only for a read/settlement state that a bounded READY retry may heal. */
+    retryable: boolean;
+}
+export interface Wave9LiveStartupReconciliationResult {
+    rows: Wave9LiveStartupRowResult[];
+    unresolvedCount: number;
+    protectedCount: number;
+    closedCount: number;
+    manualInterventionCount: number;
+    retryable: boolean;
+}
+export interface Wave9LiveStartupReconciliationOptions {
+    confirmFlat?: (adapter: IExchangeAdapter, symbol: string, options?: Wave9LiveFlatConfirmationOptions) => Promise<Wave9LiveFlatConfirmation>;
+    flatConfirmation?: Wave9LiveFlatConfirmationOptions;
+    confirmStop?: (adapter: IExchangeAdapter, input: Wave9LiveStopConfirmationInput) => Promise<boolean>;
+    recoverExposure?: typeof recoverWave9LiveExposure;
+    recoveryOptions?: Omit<Wave9LiveAutonomousProtectionOptions, 'authorizeExposureMutation'>;
+}
+/**
+ * Reconcile crash-ambiguous durable Wave 9 rows after a LIVE adapter reaches
+ * READY. The caller must hold the shared trading-operation lock. This function
+ * never submits another entry. It only cancels an exact candidate entry
+ * remainder, persists stably-flat terminal state, or repairs/flattens exposure
+ * after exact entry-CID and current-position identity both agree.
+ */
+export declare function reconcileWave9LiveDurableRows(adapter: IExchangeAdapter, ledger: Wave9LiveExecutionLedger, options?: Wave9LiveStartupReconciliationOptions): Promise<Wave9LiveStartupReconciliationResult>;