@reefclaw/openclaw-plugin 0.1.5 → 0.1.7

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;
+}

package/wave9/live-durable-reconciliation-scheduler.js

@@ -0,0 +1,115 @@
+const DEFAULT_RETRY_DELAYS_MS = [1_000, 3_000, 10_000];
+const DEFAULT_PERIODIC_MS = 60_000;
+/**
+ * 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 class Wave9LiveDurableReconciliationScheduler {
+    options;
+    retryDelaysMs;
+    periodicMs;
+    active;
+    constructor(options) {
+        this.options = options;
+        this.retryDelaysMs = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+        this.periodicMs = options.periodicMs ?? DEFAULT_PERIODIC_MS;
+        if (this.retryDelaysMs.some((delay) => !Number.isFinite(delay) || delay < 0)) {
+            throw new Error('Wave 9 reconciliation retry delays must be finite and non-negative');
+        }
+        if (!Number.isFinite(this.periodicMs) || this.periodicMs <= 0) {
+            throw new Error('Wave 9 reconciliation periodic interval must be positive and finite');
+        }
+    }
+    attach(source) {
+        if (this.active?.source === source && !this.active.stopped)
+            return;
+        this.stop();
+        const state = { source, stopped: false };
+        this.active = state;
+        source.on('readiness_changed', (readiness) => {
+            // Runtime installs this listener immediately before it publishes a
+            // reconnect adapter. Queue first, then let the timer callback verify
+            // current source identity, so a synchronously-fast READY cannot be lost.
+            if (readiness === 'READY' && !state.stopped) {
+                this.schedule(state, 0, 0, 'ready');
+            }
+        });
+        if (source.readiness === 'READY') {
+            this.schedule(state, 0, 0, 'ready_replay');
+        }
+    }
+    stopIfSourceChanged(current) {
+        if (this.active && this.active.source !== current)
+            this.stop();
+    }
+    stop() {
+        const state = this.active;
+        if (!state)
+            return;
+        state.stopped = true;
+        if (state.timer !== undefined)
+            clearTimeout(state.timer);
+        state.timer = undefined;
+        this.active = undefined;
+    }
+    isCurrentReady(state) {
+        const source = state.source;
+        return !state.stopped
+            && this.active === state
+            && this.options.isCurrentSource(source)
+            && source.isLive
+            && source.mode === 'LIVE'
+            && source.readiness === 'READY';
+    }
+    schedule(state, delayMs, retryIndex, trigger) {
+        if (state.stopped || this.active !== state || state.timer !== undefined || state.inFlight) {
+            return;
+        }
+        const timer = setTimeout(() => {
+            state.timer = undefined;
+            if (!this.isCurrentReady(state)) {
+                if (!this.options.isCurrentSource(state.source)) {
+                    state.stopped = true;
+                    if (this.active === state)
+                        this.active = undefined;
+                }
+                return;
+            }
+            let passResult;
+            let passFailed = false;
+            const pass = this.options.operationLock.withAccountLock(`wave9_live_durable_reconciliation:${trigger}`, async () => {
+                if (!this.isCurrentReady(state))
+                    return;
+                passResult = await this.options.reconcile(state.source);
+                this.options.onResult?.(trigger, passResult);
+            }).catch((error) => {
+                passFailed = true;
+                this.options.onError?.(trigger, error);
+            }).finally(() => {
+                state.inFlight = undefined;
+                if (!this.isCurrentReady(state)) {
+                    if (!this.options.isCurrentSource(state.source)) {
+                        state.stopped = true;
+                        if (this.active === state)
+                            this.active = undefined;
+                    }
+                    return;
+                }
+                const retryable = passFailed || passResult?.retryable === true;
+                if (retryable && retryIndex < this.retryDelaysMs.length) {
+                    this.schedule(state, this.retryDelaysMs[retryIndex], retryIndex + 1, `ready_retry_${retryIndex + 1}`);
+                    return;
+                }
+                // Always retain a periodic pass. It catches ATTEMPTED/OPEN rows born
+                // after READY when a live submit's exact CID read was transiently
+                // unknown, while healthy rows are a cheap exact-stop no-op.
+                this.schedule(state, this.periodicMs, 0, 'periodic');
+            });
+            state.inFlight = pass;
+        }, delayMs);
+        timer.unref();
+        state.timer = timer;
+    }
+}

package/wave9/live-execution-ledger.d.ts

@@ -0,0 +1,107 @@
+import { type Wave9StrategyName } from '../portfolio/wave9-policy.js';
+export type Wave9LiveExecutionState = 'attempted' | 'open' | 'closed';
+export type Wave9LiveDirection = 'LONG' | 'SHORT';
+export type Wave9LiveOrderSide = 'buy' | 'sell';
+export type Wave9LivePositionSide = 'long' | 'short';
+export interface Wave9LiveExecutionRecord {
+    candidateId: string;
+    missionId: string;
+    eventTime: string;
+    /** Canonical frozen-universe form, e.g. BTCUSDT. */
+    symbol: string;
+    strategy: Wave9StrategyName;
+    direction: Wave9LiveDirection;
+    side: Wave9LiveOrderSide;
+    /** Exact quantity authorized for the market-order attempt. */
+    quantity: number;
+    initialStop: number;
+    /** Deterministic Binance-safe idempotency key. */
+    clientOrderId: string;
+    state: Wave9LiveExecutionState;
+    attemptedAt: number;
+    updatedAt: number;
+    openedAt?: number;
+    closedAt?: number;
+    filledQuantity?: number;
+    entryPrice?: number;
+    exchangeOrderId?: string;
+}
+export interface Wave9LiveAttemptInput {
+    candidateId: string;
+    missionId: string;
+    eventTime: string;
+    symbol: string;
+    strategy: Wave9StrategyName;
+    direction: Wave9LiveDirection;
+    side: Wave9LiveOrderSide;
+    quantity: number;
+    initialStop: number;
+    clientOrderId: string;
+}
+export interface Wave9LiveOpenInput {
+    filledQuantity?: number;
+    entryPrice?: number;
+    exchangeOrderId?: string;
+}
+/** Final fill learned by resolving the exact deterministic entry CID. */
+export interface Wave9LiveExactOrderFillInput {
+    filledQuantity: number;
+    exchangeOrderId: string;
+    entryPrice?: number;
+}
+export interface Wave9LiveExecutionLedgerOptions {
+    pluginId?: string;
+    basePath?: string;
+    now?: () => number;
+}
+/** Stable Binance-compatible client order id (35 chars; Binance max is 36). */
+export declare function wave9ClientOrderId(candidateId: string): string;
+/** Backwards-compatible descriptive alias. */
+export declare const wave9LiveClientOrderId: typeof wave9ClientOrderId;
+export declare class Wave9LiveExecutionLedger {
+    private readonly filePath;
+    private readonly dir;
+    private readonly now;
+    private readonly entries;
+    constructor(options?: Wave9LiveExecutionLedgerOptions);
+    /**
+     * Persist an execution attempt before exchange submission. Repeating the
+     * exact immutable authorization is idempotent; any mismatch fails closed.
+     */
+    recordAttempt(input: Wave9LiveAttemptInput): Wave9LiveExecutionRecord;
+    /** Mark a confirmed fill. Repeating the exact confirmation is idempotent. */
+    markOpen(candidateId: string, input?: Wave9LiveOpenInput): Wave9LiveExecutionRecord;
+    /**
+     * Enrich an already-OPEN row after an exact deterministic entry lookup has
+     * proven the order terminal. This is deliberately narrower than markOpen:
+     * the final fill may populate a previously missing value or increase a
+     * crash-time partial fill, but it can never decrease, exceed authorization,
+     * or replace an already-bound exchange order identity.
+     */
+    reconcileOpenFillFromExactOrder(candidateId: string, input: Wave9LiveExactOrderFillInput): Wave9LiveExecutionRecord;
+    /** Mark an attempted/open record terminal. Terminal rows are never deleted. */
+    markClosed(candidateId: string): Wave9LiveExecutionRecord;
+    getByCandidateId(candidateId: string): Wave9LiveExecutionRecord | undefined;
+    /**
+     * Latest confirmed-open row matching an exchange position.
+     *
+     * An `attempted` row is a durable replay tombstone: the exchange outcome
+     * may be ambiguous, so the candidate must never execute again, but the row
+     * is not proof that a later same-symbol/same-side position belongs to Wave 9.
+     * Only `markOpen()` establishes durable position ownership.
+     */
+    findLatestForPosition(symbol: string, side: Wave9LivePositionSide | Wave9LiveOrderSide): Wave9LiveExecutionRecord | undefined;
+    /** Attempts count as executed because exchange outcome can be crash-ambiguous. */
+    getExecutedCandidateIds(): string[];
+    getAll(): Wave9LiveExecutionRecord[];
+    getFilePath(): string;
+    private currentTimestamp;
+    private requireCandidate;
+    private validateAttemptInput;
+    private validateOpenInput;
+    private sameAttempt;
+    private loadOrInit;
+    private persist;
+    private validateFile;
+    private validateStoredRecord;
+}