@reefclaw/openclaw-plugin 0.1.5 → 0.1.6

package/wave9/live-account-capture.js

@@ -0,0 +1,435 @@
+import { createHash } from 'node:crypto';
+import { getQuoteWalletBalance } from '../balance-utils.js';
+import { parseBracketCid } from '../live/bracket-id.js';
+import { WAVE9_BUNDLE_SETUP_TYPE, } from './paper-admission-guard.js';
+import { wave9ClientOrderId, } from './live-execution-ledger.js';
+function canonicalSymbol(symbol) {
+    return symbol.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+}
+function finitePositive(value, label) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        throw new Error(`Wave 9 live snapshot requires positive ${label}`);
+    }
+    return value;
+}
+function nearlyEqual(left, right) {
+    return Math.abs(left - right) <= 1e-9 * Math.max(1, Math.abs(left), Math.abs(right));
+}
+/**
+ * Binance may tick-normalize the submitted trigger while the local bracket
+ * row retains the requested ATR-derived value. One basis point matches the
+ * existing bracket idempotency tolerance, admits normal tick rounding, and
+ * still rejects any materially different stop.
+ */
+function exchangeStopPriceMatches(actual, requested) {
+    return Math.abs(actual - requested)
+        <= Math.max(1e-12, Math.abs(requested) * 1e-4);
+}
+function asNativeStopAdapter(adapter) {
+    const candidate = adapter;
+    return typeof candidate.getBracketLedger === 'function'
+        && typeof candidate.resolveBracketLegLiveness === 'function'
+        ? candidate
+        : null;
+}
+function openWave9Record(ledger, symbol, side) {
+    const canonical = canonicalSymbol(symbol);
+    const orderSide = side === 'long' ? 'buy' : 'sell';
+    const matches = ledger.getAll().filter((record) => record.state === 'open'
+        && record.symbol === canonical
+        && record.side === orderSide);
+    matches.sort((left, right) => right.updatedAt - left.updatedAt || right.candidateId.localeCompare(left.candidateId));
+    return matches[0];
+}
+function emptyStopObservation(reason) {
+    return {
+        verified: false,
+        reason,
+        bracketId: null,
+        bracketState: null,
+        entryClientOrderId: null,
+        stopClientOrderId: null,
+        exchangeOrderId: null,
+        entrySide: null,
+        stopSide: null,
+        stopPrice: null,
+        bracketQuantity: null,
+        closePosition: null,
+        liveness: null,
+    };
+}
+function rawOrderField(order, key) {
+    const direct = order.info?.[key];
+    if (direct !== undefined)
+        return direct;
+    const nested = order.info?.info;
+    return typeof nested === 'object' && nested !== null && !Array.isArray(nested)
+        ? nested[key]
+        : undefined;
+}
+function boolField(value) {
+    if (value === true || value === 'true' || value === 'TRUE')
+        return true;
+    if (value === false || value === 'false' || value === 'FALSE')
+        return false;
+    return null;
+}
+function finiteOrderStopPrice(order) {
+    if (!order)
+        return null;
+    const candidates = [order.price, rawOrderField(order, 'triggerPrice'), rawOrderField(order, 'stopPrice')];
+    for (const value of candidates) {
+        const parsed = typeof value === 'number' ? value : Number(value);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return null;
+}
+function proofLiveness(proof) {
+    if (!proof)
+        return 'unknown';
+    if (proof.algoStatus === 'NEW'
+        || proof.algoStatus === 'WORKING'
+        || proof.algoStatus === 'TRIGGERING')
+        return 'live';
+    if (proof.algoStatus === 'TRIGGERED'
+        || proof.algoStatus === 'CANCELED'
+        || proof.algoStatus === 'FINISHED'
+        || proof.algoStatus === 'EXPIRED'
+        || proof.algoStatus === 'REJECTED')
+        return 'terminal';
+    return 'unknown';
+}
+/**
+ * Bind one durable Wave 9 execution identity to the exact exchange-native
+ * stop currently protecting it. A failed observation remains structural data
+ * (so ownership/reversal handling survives) but can never authorize admission.
+ */
+async function observeNativeStop(adapter, openOrders, expectation) {
+    const native = asNativeStopAdapter(adapter);
+    if (!native)
+        return emptyStopObservation('native_stop_adapter_unavailable');
+    const bracket = native.getBracketLedger()?.getBySymbol(expectation.symbol);
+    if (!bracket)
+        return emptyStopObservation('native_stop_ledger_row_missing');
+    const stopOrders = bracket.slCid
+        ? openOrders.filter((order) => order.clientOrderId === bracket.slCid)
+        : [];
+    const stopOrder = stopOrders.length === 1 ? stopOrders[0] : undefined;
+    const directProofRequired = !expectation.requireExchangeOrderDetails;
+    let directProof = null;
+    let liveness = null;
+    if (bracket.slCid) {
+        if (directProofRequired) {
+            try {
+                directProof = await native.resolveBracketLegProof?.(bracket.slCid) ?? null;
+            }
+            catch {
+                directProof = null;
+            }
+            liveness = proofLiveness(directProof);
+        }
+        else {
+            try {
+                liveness = await native.resolveBracketLegLiveness(bracket.slCid);
+            }
+            catch {
+                liveness = 'unknown';
+            }
+        }
+    }
+    const exchangeStopPrice = directProofRequired
+        ? directProof?.triggerPrice ?? null
+        : finiteOrderStopPrice(stopOrder);
+    const closePosition = directProofRequired
+        ? directProof?.closePosition ?? null
+        : stopOrder ? boolField(rawOrderField(stopOrder, 'closePosition')) : null;
+    const exchangeSymbol = directProofRequired ? directProof?.symbol : stopOrder?.symbol;
+    const exchangeSide = directProofRequired ? directProof?.side : stopOrder?.side;
+    const orderType = directProofRequired
+        ? directProof?.orderType ?? ''
+        : stopOrder ? String(rawOrderField(stopOrder, 'orderType') ?? '').toUpperCase() : '';
+    const observation = {
+        verified: false,
+        reason: 'native_stop_unverified',
+        bracketId: bracket.bracketId,
+        bracketState: bracket.state,
+        entryClientOrderId: bracket.entryCid,
+        stopClientOrderId: bracket.slCid ?? null,
+        exchangeOrderId: directProofRequired ? directProof?.algoId ?? null : stopOrder?.id ?? null,
+        entrySide: bracket.entrySide,
+        stopSide: exchangeSide ?? null,
+        stopPrice: exchangeStopPrice ?? (Number.isFinite(bracket.stopPrice) ? bracket.stopPrice : null),
+        bracketQuantity: Number.isFinite(bracket.qty) ? bracket.qty : null,
+        closePosition,
+        liveness,
+    };
+    const parsedStopCid = bracket.slCid ? parseBracketCid(bracket.slCid) : null;
+    const expectedStopSide = expectation.entrySide === 'buy' ? 'sell' : 'buy';
+    const expectedEntryCid = wave9ClientOrderId(expectation.candidateId);
+    const quantityTolerance = 1e-9 * Math.max(1, expectation.currentPositionQuantity, expectation.filledQuantity, typeof bracket.qty === 'number' ? Math.abs(bracket.qty) : 0);
+    const exactCurrentQuantity = nearlyEqual(expectation.currentPositionQuantity, expectation.filledQuantity);
+    const bracketQuantityValid = typeof bracket.qty === 'number'
+        && Number.isFinite(bracket.qty)
+        && bracket.qty > 0
+        && (expectation.requireExactPositionQuantity
+            ? nearlyEqual(bracket.qty, expectation.filledQuantity)
+            : bracket.qty + quantityTolerance >= expectation.currentPositionQuantity
+                && bracket.qty <= expectation.filledQuantity + quantityTolerance);
+    if (expectation.entryClientOrderId !== expectedEntryCid) {
+        observation.reason = 'expected_entry_client_order_id_is_not_candidate_bound';
+    }
+    else if (bracket.state !== 'active' && bracket.state !== 'partial') {
+        observation.reason = 'native_stop_bracket_not_active';
+    }
+    else if (bracket.entryCid !== expectation.entryClientOrderId) {
+        observation.reason = 'native_stop_entry_client_order_id_mismatch';
+    }
+    else if (bracket.entrySide !== expectation.entrySide) {
+        observation.reason = 'native_stop_entry_side_mismatch';
+    }
+    else if (!bracket.slCid || parsedStopCid?.role !== 'stop'
+        || parsedStopCid.bracketId !== bracket.bracketId) {
+        observation.reason = 'native_stop_client_order_id_invalid';
+    }
+    else if (typeof bracket.stopPrice !== 'number'
+        || !Number.isFinite(bracket.stopPrice)
+        || !nearlyEqual(bracket.stopPrice, expectation.stopPrice)) {
+        observation.reason = 'native_stop_ledger_price_mismatch';
+    }
+    else if (expectation.currentPositionQuantity
+        > expectation.filledQuantity + quantityTolerance
+        || (expectation.requireExactPositionQuantity && !exactCurrentQuantity)) {
+        observation.reason = 'native_stop_position_quantity_not_covered';
+    }
+    else if (!bracketQuantityValid) {
+        observation.reason = 'native_stop_bracket_quantity_mismatch';
+    }
+    else if (directProofRequired && !directProof) {
+        observation.reason = 'native_stop_exact_exchange_proof_unavailable';
+    }
+    else if (directProofRequired && directProof?.clientAlgoId !== bracket.slCid) {
+        observation.reason = 'native_stop_exact_exchange_identity_mismatch';
+    }
+    else if (liveness !== 'live') {
+        observation.reason = 'native_stop_exchange_liveness_unverified';
+    }
+    else if (!directProofRequired
+        && (stopOrders.length !== 1 || !stopOrder || stopOrder.status !== 'open')) {
+        observation.reason = 'native_stop_exchange_order_missing';
+    }
+    else if (!exchangeSymbol
+        || canonicalSymbol(exchangeSymbol) !== canonicalSymbol(expectation.symbol)) {
+        observation.reason = 'native_stop_exchange_symbol_mismatch';
+    }
+    else if (exchangeSide !== expectedStopSide) {
+        observation.reason = 'native_stop_exchange_side_mismatch';
+    }
+    else if (orderType !== 'STOP_MARKET') {
+        observation.reason = 'native_stop_exchange_type_mismatch';
+    }
+    else if (exchangeStopPrice === null
+        || !exchangeStopPriceMatches(exchangeStopPrice, expectation.stopPrice)) {
+        observation.reason = 'native_stop_exchange_price_mismatch';
+    }
+    else if (closePosition !== true) {
+        observation.reason = 'native_stop_is_not_close_all_position';
+    }
+    else {
+        observation.verified = true;
+        observation.reason = 'verified_exchange_native_close_all_stop';
+    }
+    return observation;
+}
+/** One-shot post-fill confirmation used after the bracket row becomes active. */
+export async function confirmWave9LiveNativeStop(adapter, input) {
+    if (!adapter.isLive || adapter.mode !== 'LIVE' || adapter.readiness !== 'READY')
+        return false;
+    const observation = await observeNativeStop(adapter, [], {
+        ...input,
+        currentPositionQuantity: input.filledQuantity,
+        requireExactPositionQuantity: true,
+        requireExchangeOrderDetails: false,
+    });
+    return observation.verified;
+}
+function validatePositions(positions) {
+    for (const position of positions) {
+        if (typeof position.symbol !== 'string' || position.symbol.length === 0) {
+            throw new Error('Wave 9 live snapshot contains a malformed position symbol');
+        }
+        if (position.side !== 'long' && position.side !== 'short') {
+            throw new Error(`Wave 9 live snapshot contains a malformed ${position.symbol} side`);
+        }
+        if (typeof position.contracts !== 'number'
+            || !Number.isFinite(position.contracts)
+            || position.contracts < 0) {
+            throw new Error(`Wave 9 live snapshot contains malformed ${position.symbol} contracts`);
+        }
+    }
+}
+function isProtectiveOrder(order) {
+    if (order.clientOrderId) {
+        const parsed = parseBracketCid(order.clientOrderId);
+        if (parsed?.role === 'stop' || parsed?.role === 'target')
+            return true;
+    }
+    const info = order.info ?? {};
+    if (info.reduceOnly === true || info.closePosition === true)
+        return true;
+    const orderType = String(info.orderType ?? info.type ?? '').toUpperCase();
+    return Boolean((orderType === 'STOP_MARKET' || orderType === 'TAKE_PROFIT_MARKET')
+        && (info.closePosition === true || info.reduceOnly === true));
+}
+function structuralPosition(position) {
+    return {
+        symbol: canonicalSymbol(position.symbol),
+        side: position.side,
+        contracts: position.contracts,
+        entryPrice: position.entryPrice,
+    };
+}
+function structuralOrder(order) {
+    return {
+        id: order.id,
+        clientOrderId: order.clientOrderId ?? null,
+        symbol: canonicalSymbol(order.symbol),
+        side: order.side,
+        type: order.type,
+        amount: order.amount,
+        filled: order.filled,
+        price: order.price,
+    };
+}
+function positionFingerprint(position) {
+    const structural = {
+        symbol: canonicalSymbol(position.symbol),
+        side: position.side,
+        quantity: position.quantity,
+        entryPrice: position.entryPrice,
+        stopPrice: position.stopPrice ?? null,
+        missionId: position.missionId ?? null,
+        setupType: position.setupType ?? null,
+        candidateId: position.candidateId ?? null,
+        strategy: position.strategy ?? null,
+        openedAt: position.openedAt ?? null,
+        nativeStop: position.nativeStop ?? null,
+    };
+    return createHash('sha256').update(JSON.stringify(structural)).digest('hex');
+}
+/**
+ * Capture exchange-authoritative LIVE geometry without volatile mark prices in
+ * the authorization fingerprint. Wallet cash, positions, pending
+ * exposure-increasing orders, and durable Wave 9 identities are all bound.
+ */
+export async function captureWave9LiveAccount(adapter, ledger, mode) {
+    if (!adapter.isLive || mode !== 'LIVE' || adapter.mode !== 'LIVE') {
+        throw new Error('Wave 9 live snapshot requires a LIVE adapter in LIVE mode');
+    }
+    if (adapter.readiness !== 'READY') {
+        throw new Error(`Wave 9 live snapshot requires adapter READY (got ${adapter.readiness})`);
+    }
+    const [balance, positions, openOrders] = await Promise.all([
+        adapter.getBalance(),
+        adapter.getPositionsOrNull(),
+        adapter.getOpenOrders(),
+    ]);
+    if (positions === null) {
+        throw new Error('Wave 9 live position snapshot is unavailable');
+    }
+    validatePositions(positions);
+    const cashEquityUsd = finitePositive(getQuoteWalletBalance(balance), 'wallet cash');
+    const pendingExposureOrders = openOrders
+        .filter((order) => order.status === 'open' && !isProtectiveOrder(order))
+        .sort((left, right) => left.id.localeCompare(right.id));
+    const observed = await Promise.all(positions
+        .filter((position) => Number.isFinite(position.contracts) && position.contracts > 0)
+        .map(async (position) => {
+        const record = openWave9Record(ledger, position.symbol, position.side);
+        const row = {
+            symbol: position.symbol,
+            side: position.side,
+            quantity: finitePositive(position.contracts, `${position.symbol} contracts`),
+            entryPrice: finitePositive(position.entryPrice, `${position.symbol} entry price`),
+            markPrice: finitePositive(position.markPrice, `${position.symbol} mark price`),
+        };
+        if (!record)
+            return row;
+        const nativeStop = await observeNativeStop(adapter, openOrders, {
+            candidateId: record.candidateId,
+            symbol: position.symbol,
+            entryClientOrderId: record.clientOrderId,
+            entrySide: record.side,
+            stopPrice: record.initialStop,
+            filledQuantity: record.filledQuantity ?? record.quantity,
+            currentPositionQuantity: position.contracts,
+            requireExactPositionQuantity: false,
+            requireExchangeOrderDetails: true,
+        });
+        row.initialStopPrice = record.initialStop;
+        if (nativeStop.stopPrice !== null)
+            row.stopPrice = nativeStop.stopPrice;
+        row.missionId = record.missionId;
+        row.setupType = WAVE9_BUNDLE_SETUP_TYPE;
+        row.candidateId = record.candidateId;
+        row.strategy = record.strategy;
+        row.accruedFundingUsd = 0;
+        row.openedAt = new Date(record.openedAt ?? record.attemptedAt).toISOString();
+        row.nativeStop = nativeStop;
+        row.positionFingerprint = positionFingerprint(row);
+        return row;
+    }));
+    observed
+        .sort((left, right) => canonicalSymbol(left.symbol).localeCompare(canonicalSymbol(right.symbol)));
+    const executedCandidateIds = ledger.getExecutedCandidateIds().sort((a, b) => a.localeCompare(b));
+    const ownedPositions = observed.filter((position) => position.candidateId);
+    const nativeStopIssues = ownedPositions
+        .filter((position) => position.nativeStop?.verified !== true)
+        .map((position) => `${position.candidateId}:${position.nativeStop?.reason ?? 'native_stop_missing'}`)
+        .sort((left, right) => left.localeCompare(right));
+    const structural = {
+        schema: 'wave9-live-account-v1',
+        mode,
+        walletCashUsd: cashEquityUsd,
+        positions: positions
+            .filter((position) => Number.isFinite(position.contracts) && position.contracts > 0)
+            .map(structuralPosition)
+            .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right))),
+        pendingExposureOrders: pendingExposureOrders.map(structuralOrder),
+        wave9Identities: ledger.getAll().map((record) => ({
+            candidateId: record.candidateId,
+            missionId: record.missionId,
+            symbol: record.symbol,
+            side: record.side,
+            quantity: record.quantity,
+            initialStop: record.initialStop,
+            state: record.state,
+        })),
+        wave9NativeStops: ownedPositions.map((position) => ({
+            candidateId: position.candidateId,
+            nativeStop: position.nativeStop ?? null,
+        })),
+        executedCandidateIds,
+    };
+    return {
+        fingerprint: createHash('sha256').update(JSON.stringify(structural)).digest('hex'),
+        cashEquityUsd,
+        positions: observed,
+        pendingExposureOrderCount: pendingExposureOrders.length,
+        executedCandidateIds,
+        nativeStopProtectionComplete: nativeStopIssues.length === 0,
+        nativeStopIssues,
+        authoritative: true,
+        runtimeParity: false,
+        provenance: 'live_exchange_structural_snapshot_and_durable_wave9_ledger',
+    };
+}
+export async function captureWave9LivePosition(adapter, ledger, mode, symbol) {
+    const account = await captureWave9LiveAccount(adapter, ledger, mode);
+    const canonical = canonicalSymbol(symbol);
+    const matches = account.positions.filter((position) => canonicalSymbol(position.symbol) === canonical && position.candidateId);
+    if (matches.length !== 1 || !matches[0].positionFingerprint) {
+        throw new Error(`Wave 9 live position snapshot requires exactly one durable ${canonical} position`);
+    }
+    return { fingerprint: matches[0].positionFingerprint, position: matches[0] };
+}

package/wave9/live-autonomous-protection.d.ts

@@ -0,0 +1,39 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { Wave9LiveExecutionLedger } from './live-execution-ledger.js';
+import { type Wave9LiveFlatConfirmation, type Wave9LiveFlatConfirmationOptions } from './live-position-confirmation.js';
+import { reprotectWave9LiveResidual, type Wave9LiveResidualProtectionResult } from './live-residual-protection.js';
+export interface Wave9LiveFlatRecoveryResult {
+    status: 'flat';
+    detail: string;
+    candidateId: string;
+    symbol: string;
+}
+export type Wave9LiveAutonomousProtectionResult = Wave9LiveFlatRecoveryResult | Wave9LiveResidualProtectionResult;
+/** Test seams are optional; production callers always use the exact defaults. */
+export interface Wave9LiveAutonomousProtectionOptions {
+    flatConfirmation?: Wave9LiveFlatConfirmationOptions;
+    confirmFlat?: (adapter: IExchangeAdapter, symbol: string, options?: Wave9LiveFlatConfirmationOptions) => Promise<Wave9LiveFlatConfirmation>;
+    reprotect?: typeof reprotectWave9LiveResidual;
+    /**
+     * Optional crash-recovery identity fence. Startup reconciliation supplies
+     * this after binding the durable candidate to its exact exchange entry CID.
+     * It is re-evaluated immediately before every operation that may cancel,
+     * replace, or close same-symbol exposure. A failed/unknown fence leaves the
+     * durable row unresolved and performs no exchange mutation.
+     */
+    authorizeExposureMutation?: () => Promise<{
+        authorized: boolean;
+        detail: string;
+    }>;
+}
+/**
+ * Resolve a Wave 9 LIVE exposure after a close acknowledgement or a native
+ * stop-loss event. The only successful terminal state is stable exchange
+ * flatness persisted to the durable execution ledger. Otherwise the exact
+ * frozen candidate stop is proven/re-armed. If that cannot be done, issue one
+ * emergency reduce-only close, prove flatness again, and make one final
+ * re-protection attempt for any residual. Every unresolved state stays OPEN.
+ *
+ * The caller must hold the shared trading-operation lock for the whole call.
+ */
+export declare function recoverWave9LiveExposure(adapter: IExchangeAdapter, executionLedger: Wave9LiveExecutionLedger, candidateId: string, symbol: string, options?: Wave9LiveAutonomousProtectionOptions): Promise<Wave9LiveAutonomousProtectionResult>;

package/wave9/live-autonomous-protection.js

@@ -0,0 +1,112 @@
+import { confirmWave9LivePositionFlat, } from './live-position-confirmation.js';
+import { reprotectWave9LiveResidual, } from './live-residual-protection.js';
+function manualResult(ledger, candidateId, symbol, detail) {
+    return {
+        status: 'manual_intervention',
+        detail: `IMMEDIATE MANUAL INTERVENTION REQUIRED: ${detail}`,
+        candidateId,
+        symbol,
+        stopPrice: ledger.getByCandidateId(candidateId)?.initialStop ?? Number.NaN,
+    };
+}
+function combineManualDetail(result, prefix) {
+    return {
+        ...result,
+        detail: `IMMEDIATE MANUAL INTERVENTION REQUIRED: ${prefix}; ${result.detail}`,
+    };
+}
+async function authorizeMutation(ledger, candidateId, symbol, action, authorize) {
+    if (!authorize)
+        return undefined;
+    try {
+        const result = await authorize();
+        if (result.authorized)
+            return undefined;
+        return manualResult(ledger, candidateId, symbol, `${action} was refused by the exact entry/position identity fence: ${result.detail}`);
+    }
+    catch (error) {
+        return manualResult(ledger, candidateId, symbol, `${action} identity verification threw: ${String(error)}`);
+    }
+}
+async function markConfirmedFlat(ledger, candidateId, symbol, confirmation) {
+    try {
+        ledger.markClosed(candidateId);
+        return {
+            status: 'flat',
+            detail: confirmation.detail,
+            candidateId,
+            symbol,
+        };
+    }
+    catch (error) {
+        return manualResult(ledger, candidateId, symbol, `exchange flatness was proven but durable closure could not be persisted: ${String(error)}`);
+    }
+}
+/**
+ * Resolve a Wave 9 LIVE exposure after a close acknowledgement or a native
+ * stop-loss event. The only successful terminal state is stable exchange
+ * flatness persisted to the durable execution ledger. Otherwise the exact
+ * frozen candidate stop is proven/re-armed. If that cannot be done, issue one
+ * emergency reduce-only close, prove flatness again, and make one final
+ * re-protection attempt for any residual. Every unresolved state stays OPEN.
+ *
+ * The caller must hold the shared trading-operation lock for the whole call.
+ */
+export async function recoverWave9LiveExposure(adapter, executionLedger, candidateId, symbol, options = {}) {
+    const confirmFlat = options.confirmFlat ?? confirmWave9LivePositionFlat;
+    const reprotect = options.reprotect ?? reprotectWave9LiveResidual;
+    const firstFlat = await confirmFlat(adapter, symbol, options.flatConfirmation);
+    if (firstFlat.confirmed) {
+        return markConfirmedFlat(executionLedger, candidateId, symbol, firstFlat);
+    }
+    const initialMutationRefusal = await authorizeMutation(executionLedger, candidateId, symbol, 'initial residual re-protection', options.authorizeExposureMutation);
+    if (initialMutationRefusal)
+        return initialMutationRefusal;
+    let firstProtection;
+    try {
+        firstProtection = await reprotect(adapter, executionLedger, candidateId, symbol);
+    }
+    catch (error) {
+        firstProtection = manualResult(executionLedger, candidateId, symbol, `initial residual re-protection threw: ${String(error)}`);
+    }
+    if (firstProtection.status === 'protected')
+        return firstProtection;
+    const closeRefusal = await authorizeMutation(executionLedger, candidateId, symbol, 'emergency close', options.authorizeExposureMutation);
+    if (closeRefusal) {
+        return combineManualDetail(closeRefusal, firstProtection.detail);
+    }
+    let emergencyCloseError;
+    try {
+        await adapter.closePosition(symbol, 'emergency');
+    }
+    catch (error) {
+        // A post-submit exception is not proof the exchange rejected the close.
+        // Always inspect stable exchange position state before deciding what is
+        // left to protect.
+        emergencyCloseError = String(error);
+    }
+    const afterEmergencyFlat = await confirmFlat(adapter, symbol, options.flatConfirmation);
+    if (afterEmergencyFlat.confirmed) {
+        return markConfirmedFlat(executionLedger, candidateId, symbol, afterEmergencyFlat);
+    }
+    const finalMutationRefusal = await authorizeMutation(executionLedger, candidateId, symbol, 'final residual re-protection', options.authorizeExposureMutation);
+    if (finalMutationRefusal) {
+        const closeDetail = emergencyCloseError
+            ? `emergency close threw (${emergencyCloseError}) and stable flatness was not proven`
+            : 'emergency close was acknowledged but stable flatness was not proven';
+        return combineManualDetail(finalMutationRefusal, `${firstProtection.detail}; ${closeDetail}`);
+    }
+    let finalProtection;
+    try {
+        finalProtection = await reprotect(adapter, executionLedger, candidateId, symbol);
+    }
+    catch (error) {
+        finalProtection = manualResult(executionLedger, candidateId, symbol, `final residual re-protection threw: ${String(error)}`);
+    }
+    if (finalProtection.status === 'protected')
+        return finalProtection;
+    const closeDetail = emergencyCloseError
+        ? `emergency close threw (${emergencyCloseError}) and stable flatness was not proven`
+        : 'emergency close was acknowledged but stable flatness was not proven';
+    return combineManualDetail(finalProtection, `${firstProtection.detail}; ${closeDetail}; final residual remains unverified`);
+}

package/wave9/live-durable-reconciliation-scheduler.d.ts

@@ -0,0 +1,33 @@
+import type { AdapterReadiness, IExchangeAdapter } from '../exchange-adapter.js';
+import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
+import type { Wave9LiveStartupReconciliationResult } from './live-startup-reconciliation.js';
+export interface Wave9LiveReadySource extends IExchangeAdapter {
+    on(event: 'readiness_changed', listener: (readiness: AdapterReadiness, detail?: string) => void): unknown;
+}
+export interface Wave9LiveDurableReconciliationSchedulerOptions {
+    operationLock: TradingOperationLock;
+    isCurrentSource(source: Wave9LiveReadySource): boolean;
+    reconcile(source: Wave9LiveReadySource): Promise<Wave9LiveStartupReconciliationResult>;
+    onResult?(trigger: string, result: Wave9LiveStartupReconciliationResult): void;
+    onError?(trigger: string, error: unknown): void;
+    retryDelaysMs?: readonly number[];
+    periodicMs?: number;
+}
+/**
+ * Source-bound READY/periodic driver for durable Wave 9 recovery. At most one
+ * timer and one lock-serialized pass exist for the active adapter. A replaced
+ * adapter is stopped synchronously and an in-flight old pass cannot reschedule
+ * itself. Timers are unref'ed so this safety loop never keeps Node alive.
+ */
+export declare class Wave9LiveDurableReconciliationScheduler {
+    private readonly options;
+    private readonly retryDelaysMs;
+    private readonly periodicMs;
+    private active?;
+    constructor(options: Wave9LiveDurableReconciliationSchedulerOptions);
+    attach(source: Wave9LiveReadySource): void;
+    stopIfSourceChanged(current: IExchangeAdapter): void;
+    stop(): void;
+    private isCurrentReady;
+    private schedule;
+}