@reefclaw/openclaw-plugin 0.1.5 → 0.1.6

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