@reefclaw/openclaw-plugin 0.1.5 → 0.1.6

package/wave9/live-execution-ledger.js

@@ -0,0 +1,498 @@
+// Durable Wave 9 live-execution identity and replay ledger.
+//
+// A live market-order outcome can become ambiguous across a process crash: the
+// exchange may have accepted the order even when the local caller never saw the
+// acknowledgement. Therefore an attempt is persisted before submission and is
+// permanently treated as executed for same-event replay prevention. Terminal
+// rows are retained so a restart cannot forget a candidate that already ran.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DAY_MS, WAVE9_LONG_STRATEGY, WAVE9_SHORT_STRATEGY, WAVE9_SYMBOL_PRIORITY, } from '../portfolio/wave9-policy.js';
+import { resolvePluginsBaseDir } from '../util/plugin-paths.js';
+const DEFAULT_PLUGIN_ID = 'reefclaw-paper-trading';
+const LEDGER_FILENAME = 'wave9-live-execution-ledger.json';
+const SCHEMA_VERSION = 1;
+const MAX_TEXT_LENGTH = 512;
+const CLIENT_ORDER_ID_PATTERN = /^w9e[a-f0-9]{32}$/;
+/** Stable Binance-compatible client order id (35 chars; Binance max is 36). */
+export function wave9ClientOrderId(candidateId) {
+    requireText(candidateId, 'candidateId');
+    return `w9e${createHash('sha256').update(candidateId).digest('hex').slice(0, 32)}`;
+}
+/** Backwards-compatible descriptive alias. */
+export const wave9LiveClientOrderId = wave9ClientOrderId;
+/** Stable Wave 9 mission identity, mirrored from the status authorization path. */
+function expectedMissionId(candidateId) {
+    return `wave9_${createHash('sha256').update(candidateId).digest('hex').slice(0, 32)}`;
+}
+function canonicalSymbol(value) {
+    requireText(value, 'symbol');
+    return value.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+}
+function requireText(value, label) {
+    if (typeof value !== 'string'
+        || value.length === 0
+        || value.length > MAX_TEXT_LENGTH
+        || value.trim() !== value) {
+        throw new Error(`wave9-live-execution-ledger: ${label} is malformed`);
+    }
+}
+function requirePositiveFinite(value, label) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        throw new Error(`wave9-live-execution-ledger: ${label} must be positive and finite`);
+    }
+}
+function requireTimestamp(value, label) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`wave9-live-execution-ledger: ${label} must be a non-negative safe integer`);
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertExactKeys(value, required, optional, label) {
+    const allowed = new Set([...required, ...optional]);
+    for (const key of required) {
+        if (!(key in value))
+            throw new Error(`wave9-live-execution-ledger: ${label} missing ${key}`);
+    }
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            throw new Error(`wave9-live-execution-ledger: ${label} has unknown field ${key}`);
+    }
+}
+function cloneRecord(record) {
+    return { ...record };
+}
+function sameOptional(left, right) {
+    return left === right;
+}
+export class Wave9LiveExecutionLedger {
+    filePath;
+    dir;
+    now;
+    entries = new Map();
+    constructor(options = {}) {
+        const base = resolvePluginsBaseDir(options.basePath);
+        this.dir = join(base, options.pluginId ?? DEFAULT_PLUGIN_ID);
+        this.filePath = join(this.dir, LEDGER_FILENAME);
+        this.now = options.now ?? Date.now;
+        if (!existsSync(this.dir))
+            mkdirSync(this.dir, { recursive: true });
+        this.loadOrInit();
+    }
+    /**
+     * Persist an execution attempt before exchange submission. Repeating the
+     * exact immutable authorization is idempotent; any mismatch fails closed.
+     */
+    recordAttempt(input) {
+        const normalized = this.validateAttemptInput(input);
+        const existing = this.entries.get(normalized.candidateId);
+        if (existing) {
+            if (!this.sameAttempt(existing, normalized)) {
+                throw new Error(`wave9-live-execution-ledger: candidate ${normalized.candidateId} already exists with different authorization`);
+            }
+            return cloneRecord(existing);
+        }
+        const attemptedAt = this.currentTimestamp('attemptedAt');
+        const record = {
+            ...normalized,
+            state: 'attempted',
+            attemptedAt,
+            updatedAt: attemptedAt,
+        };
+        if ([...this.entries.values()].some((row) => row.clientOrderId === record.clientOrderId)) {
+            throw new Error('wave9-live-execution-ledger: deterministic clientOrderId collision');
+        }
+        this.entries.set(record.candidateId, record);
+        this.persist();
+        return cloneRecord(record);
+    }
+    /** Mark a confirmed fill. Repeating the exact confirmation is idempotent. */
+    markOpen(candidateId, input = {}) {
+        requireText(candidateId, 'candidateId');
+        const existing = this.requireCandidate(candidateId);
+        const normalized = this.validateOpenInput(existing, input);
+        if (existing.state === 'closed') {
+            throw new Error(`wave9-live-execution-ledger: closed candidate ${candidateId} cannot reopen`);
+        }
+        if (existing.state === 'open') {
+            if (!sameOptional(existing.filledQuantity, normalized.filledQuantity)
+                || !sameOptional(existing.entryPrice, normalized.entryPrice)
+                || !sameOptional(existing.exchangeOrderId, normalized.exchangeOrderId)) {
+                throw new Error(`wave9-live-execution-ledger: candidate ${candidateId} already open with different fill`);
+            }
+            return cloneRecord(existing);
+        }
+        const openedAt = this.currentTimestamp('openedAt');
+        if (openedAt < existing.attemptedAt) {
+            throw new Error('wave9-live-execution-ledger: openedAt precedes attemptedAt');
+        }
+        const updated = {
+            ...existing,
+            ...normalized,
+            state: 'open',
+            openedAt,
+            updatedAt: openedAt,
+        };
+        this.entries.set(candidateId, updated);
+        this.persist();
+        return cloneRecord(updated);
+    }
+    /**
+     * 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, input) {
+        requireText(candidateId, 'candidateId');
+        const existing = this.requireCandidate(candidateId);
+        if (existing.state !== 'open') {
+            throw new Error(`wave9-live-execution-ledger: exact-order fill reconciliation requires OPEN candidate ${candidateId}`);
+        }
+        if (!isRecord(input)) {
+            throw new Error('wave9-live-execution-ledger: exact-order fill is not an object');
+        }
+        assertExactKeys(input, ['filledQuantity', 'exchangeOrderId'], ['entryPrice'], 'exact-order fill');
+        requirePositiveFinite(input.filledQuantity, 'filledQuantity');
+        if (input.filledQuantity > existing.quantity) {
+            throw new Error('wave9-live-execution-ledger: exact-order fill exceeds authorized quantity');
+        }
+        requireText(input.exchangeOrderId, 'exchangeOrderId');
+        if (existing.exchangeOrderId !== undefined
+            && existing.exchangeOrderId !== input.exchangeOrderId) {
+            throw new Error('wave9-live-execution-ledger: exact-order exchangeOrderId disagrees with durable identity');
+        }
+        if (existing.filledQuantity !== undefined
+            && input.filledQuantity < existing.filledQuantity) {
+            throw new Error('wave9-live-execution-ledger: exact-order fill cannot decrease');
+        }
+        if (input.entryPrice !== undefined) {
+            this.validateOpenInput(existing, { entryPrice: input.entryPrice });
+            if (existing.filledQuantity === input.filledQuantity
+                && existing.entryPrice !== undefined
+                && existing.entryPrice !== input.entryPrice) {
+                throw new Error('wave9-live-execution-ledger: exact-order entryPrice changed without a larger final fill');
+            }
+        }
+        const nextEntryPrice = input.entryPrice ?? existing.entryPrice;
+        const unchanged = existing.filledQuantity === input.filledQuantity
+            && existing.exchangeOrderId === input.exchangeOrderId
+            && existing.entryPrice === nextEntryPrice;
+        if (unchanged)
+            return cloneRecord(existing);
+        const updatedAt = this.currentTimestamp('updatedAt');
+        if (updatedAt < (existing.openedAt ?? existing.attemptedAt)) {
+            throw new Error('wave9-live-execution-ledger: updatedAt precedes the execution lifecycle');
+        }
+        const updated = {
+            ...existing,
+            filledQuantity: input.filledQuantity,
+            exchangeOrderId: input.exchangeOrderId,
+            ...(nextEntryPrice !== undefined ? { entryPrice: nextEntryPrice } : {}),
+            updatedAt,
+        };
+        this.entries.set(candidateId, updated);
+        try {
+            this.persist();
+        }
+        catch (error) {
+            // Do not let a failed disk replace make this process believe a final
+            // fill that the next process cannot load.
+            this.entries.set(candidateId, existing);
+            throw error;
+        }
+        return cloneRecord(updated);
+    }
+    /** Mark an attempted/open record terminal. Terminal rows are never deleted. */
+    markClosed(candidateId) {
+        requireText(candidateId, 'candidateId');
+        const existing = this.requireCandidate(candidateId);
+        if (existing.state === 'closed')
+            return cloneRecord(existing);
+        const closedAt = this.currentTimestamp('closedAt');
+        if (closedAt < existing.attemptedAt || (existing.openedAt !== undefined && closedAt < existing.openedAt)) {
+            throw new Error('wave9-live-execution-ledger: closedAt precedes the execution lifecycle');
+        }
+        const updated = {
+            ...existing,
+            state: 'closed',
+            closedAt,
+            updatedAt: closedAt,
+        };
+        this.entries.set(candidateId, updated);
+        this.persist();
+        return cloneRecord(updated);
+    }
+    getByCandidateId(candidateId) {
+        const record = this.entries.get(candidateId);
+        return record ? cloneRecord(record) : 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, side) {
+        const canonical = canonicalSymbol(symbol);
+        if (side !== 'long' && side !== 'short' && side !== 'buy' && side !== 'sell') {
+            throw new Error('wave9-live-execution-ledger: position side is malformed');
+        }
+        const orderSide = side === 'long' || side === 'buy' ? 'buy' : 'sell';
+        const matches = [...this.entries.values()].filter((row) => row.state === 'open' && row.symbol === canonical && row.side === orderSide);
+        matches.sort((left, right) => right.attemptedAt - left.attemptedAt
+            || right.updatedAt - left.updatedAt
+            || right.candidateId.localeCompare(left.candidateId));
+        return matches[0] ? cloneRecord(matches[0]) : undefined;
+    }
+    /** Attempts count as executed because exchange outcome can be crash-ambiguous. */
+    getExecutedCandidateIds() {
+        return [...this.entries.keys()].sort((left, right) => left.localeCompare(right));
+    }
+    getAll() {
+        return [...this.entries.values()]
+            .sort((left, right) => left.attemptedAt - right.attemptedAt
+            || left.candidateId.localeCompare(right.candidateId))
+            .map(cloneRecord);
+    }
+    getFilePath() {
+        return this.filePath;
+    }
+    currentTimestamp(label) {
+        const value = this.now();
+        requireTimestamp(value, label);
+        return value;
+    }
+    requireCandidate(candidateId) {
+        const record = this.entries.get(candidateId);
+        if (!record)
+            throw new Error(`wave9-live-execution-ledger: unknown candidate ${candidateId}`);
+        return record;
+    }
+    validateAttemptInput(input) {
+        if (!isRecord(input))
+            throw new Error('wave9-live-execution-ledger: attempt is not an object');
+        assertExactKeys(input, [
+            'candidateId', 'missionId', 'eventTime', 'symbol', 'strategy',
+            'direction', 'side', 'quantity', 'initialStop', 'clientOrderId',
+        ], [], 'attempt');
+        requireText(input.candidateId, 'candidateId');
+        requireText(input.missionId, 'missionId');
+        requireText(input.eventTime, 'eventTime');
+        const eventMs = Date.parse(input.eventTime);
+        if (!Number.isFinite(eventMs)
+            || new Date(eventMs).toISOString() !== input.eventTime
+            || eventMs % DAY_MS !== 0) {
+            throw new Error('wave9-live-execution-ledger: eventTime must be a UTC daily boundary');
+        }
+        const symbol = canonicalSymbol(input.symbol);
+        if (!WAVE9_SYMBOL_PRIORITY.includes(symbol)) {
+            throw new Error(`wave9-live-execution-ledger: unsupported Wave 9 symbol ${symbol}`);
+        }
+        if (input.strategy !== WAVE9_LONG_STRATEGY && input.strategy !== WAVE9_SHORT_STRATEGY) {
+            throw new Error('wave9-live-execution-ledger: unsupported Wave 9 strategy');
+        }
+        if (input.direction !== 'LONG' && input.direction !== 'SHORT') {
+            throw new Error('wave9-live-execution-ledger: direction is malformed');
+        }
+        if (input.side !== 'buy' && input.side !== 'sell') {
+            throw new Error('wave9-live-execution-ledger: side is malformed');
+        }
+        const expectedDirection = input.strategy === WAVE9_LONG_STRATEGY ? 'LONG' : 'SHORT';
+        const expectedSide = expectedDirection === 'LONG' ? 'buy' : 'sell';
+        if (input.direction !== expectedDirection || input.side !== expectedSide) {
+            throw new Error('wave9-live-execution-ledger: strategy, direction, and side disagree');
+        }
+        const expectedCandidateId = `${input.eventTime}|${symbol}|${input.strategy}|${input.direction}`;
+        if (input.candidateId !== expectedCandidateId) {
+            throw new Error('wave9-live-execution-ledger: candidateId does not match its frozen identity');
+        }
+        if (input.missionId !== expectedMissionId(input.candidateId)) {
+            throw new Error('wave9-live-execution-ledger: missionId does not match candidateId');
+        }
+        requirePositiveFinite(input.quantity, 'quantity');
+        requirePositiveFinite(input.initialStop, 'initialStop');
+        requireText(input.clientOrderId, 'clientOrderId');
+        if (!CLIENT_ORDER_ID_PATTERN.test(input.clientOrderId)
+            || input.clientOrderId !== wave9ClientOrderId(input.candidateId)) {
+            throw new Error('wave9-live-execution-ledger: clientOrderId is not deterministic');
+        }
+        return {
+            ...input,
+            symbol,
+        };
+    }
+    validateOpenInput(record, input) {
+        if (!isRecord(input))
+            throw new Error('wave9-live-execution-ledger: open confirmation is not an object');
+        assertExactKeys(input, [], ['filledQuantity', 'entryPrice', 'exchangeOrderId'], 'open confirmation');
+        if (input.filledQuantity !== undefined) {
+            requirePositiveFinite(input.filledQuantity, 'filledQuantity');
+            if (input.filledQuantity > record.quantity * (1 + 1e-9)) {
+                throw new Error('wave9-live-execution-ledger: filledQuantity exceeds authorized quantity');
+            }
+        }
+        if (input.entryPrice !== undefined) {
+            requirePositiveFinite(input.entryPrice, 'entryPrice');
+            if ((record.direction === 'LONG' && record.initialStop >= input.entryPrice)
+                || (record.direction === 'SHORT' && record.initialStop <= input.entryPrice)) {
+                throw new Error('wave9-live-execution-ledger: fill/initial-stop geometry is invalid');
+            }
+        }
+        if (input.exchangeOrderId !== undefined)
+            requireText(input.exchangeOrderId, 'exchangeOrderId');
+        return { ...input };
+    }
+    sameAttempt(existing, input) {
+        return existing.candidateId === input.candidateId
+            && existing.missionId === input.missionId
+            && existing.eventTime === input.eventTime
+            && existing.symbol === input.symbol
+            && existing.strategy === input.strategy
+            && existing.direction === input.direction
+            && existing.side === input.side
+            && existing.quantity === input.quantity
+            && existing.initialStop === input.initialStop
+            && existing.clientOrderId === input.clientOrderId
+            && existing.clientOrderId === wave9ClientOrderId(input.candidateId);
+    }
+    loadOrInit() {
+        if (!existsSync(this.filePath))
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(this.filePath, 'utf8'));
+        }
+        catch (error) {
+            throw new Error(`wave9-live-execution-ledger: failed to read valid JSON from ${this.filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const file = this.validateFile(parsed);
+        const clientOrderIds = new Set();
+        for (const entry of file.entries) {
+            if (this.entries.has(entry.candidateId)) {
+                throw new Error(`wave9-live-execution-ledger: duplicate candidate ${entry.candidateId}`);
+            }
+            if (clientOrderIds.has(entry.clientOrderId)) {
+                throw new Error(`wave9-live-execution-ledger: duplicate clientOrderId ${entry.clientOrderId}`);
+            }
+            this.entries.set(entry.candidateId, entry);
+            clientOrderIds.add(entry.clientOrderId);
+        }
+    }
+    persist() {
+        const file = {
+            schemaVersion: SCHEMA_VERSION,
+            entries: this.getAll(),
+        };
+        const tempPath = `${this.filePath}.tmp`;
+        writeFileSync(tempPath, JSON.stringify(file, null, 2), { mode: 0o600 });
+        renameSync(tempPath, this.filePath);
+    }
+    validateFile(raw) {
+        if (!isRecord(raw))
+            throw new Error('wave9-live-execution-ledger: file root is not an object');
+        assertExactKeys(raw, ['schemaVersion', 'entries'], [], 'file');
+        if (raw.schemaVersion !== SCHEMA_VERSION) {
+            throw new Error(`wave9-live-execution-ledger: unsupported schemaVersion ${String(raw.schemaVersion)} (expected ${SCHEMA_VERSION})`);
+        }
+        if (!Array.isArray(raw.entries)) {
+            throw new Error('wave9-live-execution-ledger: entries is not an array');
+        }
+        return {
+            schemaVersion: SCHEMA_VERSION,
+            entries: raw.entries.map((entry) => this.validateStoredRecord(entry)),
+        };
+    }
+    validateStoredRecord(raw) {
+        if (!isRecord(raw))
+            throw new Error('wave9-live-execution-ledger: stored entry is not an object');
+        assertExactKeys(raw, [
+            'candidateId', 'missionId', 'eventTime', 'symbol', 'strategy', 'direction',
+            'side', 'quantity', 'initialStop', 'clientOrderId', 'state',
+            'attemptedAt', 'updatedAt',
+        ], ['openedAt', 'closedAt', 'filledQuantity', 'entryPrice', 'exchangeOrderId'], 'stored entry');
+        const attempt = this.validateAttemptInput({
+            candidateId: raw.candidateId,
+            missionId: raw.missionId,
+            eventTime: raw.eventTime,
+            symbol: raw.symbol,
+            strategy: raw.strategy,
+            direction: raw.direction,
+            side: raw.side,
+            quantity: raw.quantity,
+            initialStop: raw.initialStop,
+            clientOrderId: raw.clientOrderId,
+        });
+        requireText(raw.clientOrderId, 'clientOrderId');
+        if (!CLIENT_ORDER_ID_PATTERN.test(raw.clientOrderId)
+            || raw.clientOrderId !== wave9ClientOrderId(attempt.candidateId)) {
+            throw new Error('wave9-live-execution-ledger: clientOrderId is not deterministic');
+        }
+        if (raw.state !== 'attempted' && raw.state !== 'open' && raw.state !== 'closed') {
+            throw new Error('wave9-live-execution-ledger: state is malformed');
+        }
+        requireTimestamp(raw.attemptedAt, 'attemptedAt');
+        requireTimestamp(raw.updatedAt, 'updatedAt');
+        if (raw.updatedAt < raw.attemptedAt) {
+            throw new Error('wave9-live-execution-ledger: updatedAt precedes attemptedAt');
+        }
+        const openInput = this.validateOpenInput(attempt, {
+            ...(raw.filledQuantity !== undefined ? { filledQuantity: raw.filledQuantity } : {}),
+            ...(raw.entryPrice !== undefined ? { entryPrice: raw.entryPrice } : {}),
+            ...(raw.exchangeOrderId !== undefined ? { exchangeOrderId: raw.exchangeOrderId } : {}),
+        });
+        if (raw.openedAt !== undefined)
+            requireTimestamp(raw.openedAt, 'openedAt');
+        if (raw.closedAt !== undefined)
+            requireTimestamp(raw.closedAt, 'closedAt');
+        if (raw.state === 'attempted'
+            && (raw.openedAt !== undefined || raw.closedAt !== undefined || Object.keys(openInput).length > 0)) {
+            throw new Error('wave9-live-execution-ledger: attempted entry contains fill/terminal fields');
+        }
+        if (raw.state === 'open' && raw.openedAt === undefined) {
+            throw new Error('wave9-live-execution-ledger: open entry is missing openedAt');
+        }
+        if (raw.state === 'open' && raw.closedAt !== undefined) {
+            throw new Error('wave9-live-execution-ledger: open entry contains closedAt');
+        }
+        if (raw.state === 'closed' && raw.closedAt === undefined) {
+            throw new Error('wave9-live-execution-ledger: closed entry is missing closedAt');
+        }
+        if (raw.openedAt !== undefined && raw.openedAt < raw.attemptedAt) {
+            throw new Error('wave9-live-execution-ledger: openedAt precedes attemptedAt');
+        }
+        if (raw.closedAt !== undefined
+            && (raw.closedAt < raw.attemptedAt
+                || (raw.openedAt !== undefined && raw.closedAt < raw.openedAt))) {
+            throw new Error('wave9-live-execution-ledger: closedAt precedes the execution lifecycle');
+        }
+        if (Object.keys(openInput).length > 0 && raw.openedAt === undefined) {
+            throw new Error('wave9-live-execution-ledger: fill fields require openedAt');
+        }
+        if (raw.state === 'attempted' && raw.updatedAt !== raw.attemptedAt) {
+            throw new Error('wave9-live-execution-ledger: updatedAt does not match attemptedAt');
+        }
+        if (raw.state === 'open' && raw.updatedAt < raw.openedAt) {
+            throw new Error('wave9-live-execution-ledger: OPEN updatedAt precedes openedAt');
+        }
+        if (raw.state === 'closed' && raw.updatedAt !== raw.closedAt) {
+            throw new Error('wave9-live-execution-ledger: CLOSED updatedAt does not match closedAt');
+        }
+        return {
+            ...attempt,
+            clientOrderId: raw.clientOrderId,
+            state: raw.state,
+            attemptedAt: raw.attemptedAt,
+            updatedAt: raw.updatedAt,
+            ...(raw.openedAt !== undefined ? { openedAt: raw.openedAt } : {}),
+            ...(raw.closedAt !== undefined ? { closedAt: raw.closedAt } : {}),
+            ...openInput,
+        };
+    }
+}

package/wave9/live-position-confirmation.d.ts

@@ -0,0 +1,18 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+export interface Wave9LiveFlatConfirmation {
+    confirmed: boolean;
+    detail: string;
+}
+export interface Wave9LiveFlatConfirmationOptions {
+    attempts?: number;
+    delayMs?: number;
+    requiredFlatSnapshots?: number;
+    minStableMs?: number;
+    now?: () => number;
+}
+/**
+ * Confirm a symbol is absent from a trusted exchange position snapshot.
+ * A close-order response is not sufficient: partial fills, asynchronous
+ * settlement, malformed rows, and failed reads all remain non-terminal.
+ */
+export declare function confirmWave9LivePositionFlat(adapter: IExchangeAdapter, symbol: string, options?: Wave9LiveFlatConfirmationOptions): Promise<Wave9LiveFlatConfirmation>;

package/wave9/live-position-confirmation.js

@@ -0,0 +1,111 @@
+import { formatError } from '../logger.js';
+const DEFAULT_ATTEMPTS = 16;
+const DEFAULT_DELAY_MS = 250;
+const DEFAULT_REQUIRED_FLAT_SNAPSHOTS = 3;
+const DEFAULT_MIN_STABLE_MS = 1_000;
+function canonicalSymbol(value) {
+    return value.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+}
+function wait(delayMs) {
+    return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+/**
+ * Confirm a symbol is absent from a trusted exchange position snapshot.
+ * A close-order response is not sufficient: partial fills, asynchronous
+ * settlement, malformed rows, and failed reads all remain non-terminal.
+ */
+export async function confirmWave9LivePositionFlat(adapter, symbol, options = {}) {
+    const target = canonicalSymbol(symbol);
+    const attempts = options.attempts ?? DEFAULT_ATTEMPTS;
+    const delayMs = options.delayMs ?? DEFAULT_DELAY_MS;
+    const requiredFlatSnapshots = options.requiredFlatSnapshots ?? DEFAULT_REQUIRED_FLAT_SNAPSHOTS;
+    const minStableMs = options.minStableMs ?? DEFAULT_MIN_STABLE_MS;
+    const now = options.now ?? Date.now;
+    if (!Number.isInteger(attempts) || attempts <= 0) {
+        throw new Error('Wave 9 LIVE flat confirmation attempts must be a positive integer');
+    }
+    if (!Number.isFinite(delayMs) || delayMs < 0) {
+        throw new Error('Wave 9 LIVE flat confirmation delay must be finite and non-negative');
+    }
+    if (!Number.isInteger(requiredFlatSnapshots) || requiredFlatSnapshots < 2) {
+        throw new Error('Wave 9 LIVE flat confirmation requires at least two stable snapshots');
+    }
+    if (!Number.isFinite(minStableMs) || minStableMs < 0) {
+        throw new Error('Wave 9 LIVE flat confirmation stable window must be finite and non-negative');
+    }
+    if (attempts < requiredFlatSnapshots) {
+        throw new Error('Wave 9 LIVE flat confirmation attempts cannot be shorter than its stable streak');
+    }
+    let detail = 'no trusted position snapshot was returned';
+    let consecutiveFlatSnapshots = 0;
+    let flatSince;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        let trustedFlat = false;
+        try {
+            const positions = await adapter.getPositionsOrNull(symbol);
+            if (Array.isArray(positions)) {
+                let malformed = false;
+                let residualContracts = 0;
+                for (const position of positions) {
+                    if (!position
+                        || typeof position.symbol !== 'string'
+                        || typeof position.contracts !== 'number'
+                        || !Number.isFinite(position.contracts)) {
+                        malformed = true;
+                        continue;
+                    }
+                    if (canonicalSymbol(position.symbol) === target) {
+                        residualContracts += Math.abs(position.contracts);
+                    }
+                }
+                if (!malformed && residualContracts > 0) {
+                    return {
+                        confirmed: false,
+                        detail: `exchange still reports ${residualContracts} contracts`,
+                    };
+                }
+                if (!malformed && residualContracts === 0) {
+                    const observedAt = now();
+                    if (!Number.isFinite(observedAt)) {
+                        throw new Error('flat confirmation clock returned a non-finite timestamp');
+                    }
+                    if (flatSince !== undefined && observedAt < flatSince) {
+                        throw new Error('flat confirmation clock moved backwards');
+                    }
+                    trustedFlat = true;
+                    if (consecutiveFlatSnapshots === 0)
+                        flatSince = observedAt;
+                    consecutiveFlatSnapshots += 1;
+                    const stableForMs = observedAt - (flatSince ?? observedAt);
+                    detail = `trusted flat streak ${consecutiveFlatSnapshots}/${requiredFlatSnapshots} ` +
+                        `stable for ${stableForMs}/${minStableMs}ms`;
+                    if (consecutiveFlatSnapshots >= requiredFlatSnapshots && stableForMs >= minStableMs) {
+                        return {
+                            confirmed: true,
+                            detail: `trusted exchange position snapshot remained flat across ` +
+                                `${consecutiveFlatSnapshots} reads for ${stableForMs}ms`,
+                        };
+                    }
+                }
+                if (!trustedFlat) {
+                    detail = malformed
+                        ? 'exchange position snapshot contained malformed rows'
+                        : `exchange still reports ${residualContracts} contracts`;
+                }
+            }
+            else {
+                detail = 'exchange position state is unknown';
+            }
+        }
+        catch (err) {
+            detail = `position confirmation failed: ${formatError(err)}`;
+        }
+        if (!trustedFlat) {
+            consecutiveFlatSnapshots = 0;
+            flatSince = undefined;
+        }
+        if (attempt + 1 < attempts)
+            await wait(delayMs);
+    }
+    return { confirmed: false, detail };
+}

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

@@ -0,0 +1,18 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { Wave9LiveExecutionLedger } from './live-execution-ledger.js';
+export interface Wave9LiveResidualProtectionResult {
+    status: 'protected' | 'manual_intervention';
+    detail: string;
+    candidateId: string;
+    symbol: string;
+    stopPrice: number;
+    residualQuantity?: number;
+    stopClientOrderId?: string;
+}
+/**
+ * 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 declare function reprotectWave9LiveResidual(adapter: IExchangeAdapter, executionLedger: Wave9LiveExecutionLedger, candidateId: string, symbol: string): Promise<Wave9LiveResidualProtectionResult>;