@reefclaw/openclaw-plugin 0.1.0

package/live/bracket-ledger.js

@@ -0,0 +1,267 @@
+// Bracket ledger — persistent record of all brackets attached to open
+// positions. Local JSON file is authoritative; the intelligence DB mirror
+// (Phase 2) is best-effort async and for disaster recovery.
+//
+// Storage pattern:
+//   - Full JSON rewrite on every mutation (not JSONL append-only like
+//     IntentJournal). The ledger is small (≈ N open positions) and mutates
+//     in place, so rewrite + atomic rename is simpler than replay-on-load.
+//   - Atomic write via temp-file-then-rename. A crash mid-write leaves either
+//     the old file intact or the new file complete, never a torn write.
+//
+// Corruption policy:
+//   - On load, every entry is schema-checked. Unknown/malformed file →
+//     throw, refuse to start. Operator restores from intelligence mirror or
+//     clears and resumes fresh (see BRACKET_ORDERS_DESIGN.md §4 row 14).
+//
+// Keying:
+//   - Primary key is NORMALIZED `symbol` (one-way mode → one bracket per
+//     symbol). All public methods apply `normalizeBracketSymbol` so callers
+//     can pass either `BTC/USDT` (skill/agent form) or `BTC/USDT:USDT`
+//     (CCXT fetchPositions form) and hit the same row.
+//   - Pre-2026-04-21 rows written with a mix of both forms; `loadOrInit`
+//     runs a one-shot dedup migration that collapses doubled rows by
+//     keeping the newer (by `updatedAt`) and discarding the older, then
+//     rewrites the file with normalized keys.
+//   - Lookups by `bracketId` iterate; the live set is small (typically 1–10).
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolvePluginsBaseDir } from '../util/plugin-paths.js';
+import { logger, formatError } from '../logger.js';
+const TAG = 'bracket-ledger';
+const DEFAULT_PLUGIN_ID = 'reefclaw-paper-trading';
+const LEDGER_FILENAME = 'bracket-ledger.json';
+const SCHEMA_VERSION = 1;
+/** Canonical form for a bracket-ledger symbol key.
+ *
+ *  CCXT returns Binance Futures symbols as `BTC/USDT:USDT` (the `:USDT`
+ *  suffix is the settlement asset); the skill + agent's tool args use the
+ *  un-suffixed `BTC/USDT`. Historically we keyed the ledger by whatever the
+ *  caller passed in — which produced doubled rows per symbol and caused the
+ *  2026-04-21 ADA audit-vs-attach deadlock (9 of 11 symbols had both keys;
+ *  see `memory/feedback_symbol_normalize_boundary.md`). This helper picks a
+ *  single canonical form (un-suffixed) and is applied at every public
+ *  BracketLedger entry point.
+ *
+ *  Matches `user-data-stream-controller.ts` and `webapp/src/lib/symbols.ts`
+ *  `normalizeSymbol`, so the bracket path lines up with the WS store + UI. */
+export function normalizeBracketSymbol(s) {
+    return s.replace(/:[A-Z]+$/, '');
+}
+const VALID_STATES = new Set([
+    'pending_entry',
+    'attaching',
+    'active',
+    'partial',
+    'triggered_sl',
+    'triggered_tp',
+    'cancelled',
+    'failed',
+]);
+const TERMINAL_STATES = new Set([
+    'triggered_sl',
+    'triggered_tp',
+    'cancelled',
+    'failed',
+]);
+const defaultNow = () => new Date().toISOString();
+export class BracketLedger {
+    filePath;
+    dir;
+    now;
+    entries = new Map();
+    constructor(pluginId, opts) {
+        const base = resolvePluginsBaseDir(opts?.basePath);
+        this.dir = join(base, pluginId ?? DEFAULT_PLUGIN_ID);
+        this.filePath = join(this.dir, LEDGER_FILENAME);
+        this.now = opts?.now ?? defaultNow;
+        if (!existsSync(this.dir)) {
+            mkdirSync(this.dir, { recursive: true });
+        }
+        this.loadOrInit();
+    }
+    /** Insert or replace the entry for a symbol. Persists synchronously.
+     *  Symbol is normalized; the stored entry carries the canonical form so
+     *  later readers see it regardless of whether the caller passed suffixed
+     *  or un-suffixed input. */
+    upsert(entry) {
+        const ts = this.now();
+        const symbol = normalizeBracketSymbol(entry.symbol);
+        const existing = this.entries.get(symbol);
+        const full = {
+            ...entry,
+            symbol, // always store the canonical form
+            createdAt: existing?.createdAt ?? entry.createdAt ?? ts,
+            updatedAt: ts,
+        };
+        this.entries.set(full.symbol, full);
+        this.persist();
+        return full;
+    }
+    /** Mutate the state of an existing entry. Throws if entry not found. */
+    markState(symbol, nextState, extras) {
+        const key = normalizeBracketSymbol(symbol);
+        const current = this.entries.get(key);
+        if (!current)
+            throw new Error(`No ledger entry for ${symbol}`);
+        const ts = this.now();
+        const nextEntry = {
+            ...current,
+            ...extras,
+            state: nextState,
+            updatedAt: ts,
+            closedAt: TERMINAL_STATES.has(nextState) ? (current.closedAt ?? ts) : current.closedAt,
+        };
+        this.entries.set(key, nextEntry);
+        this.persist();
+        return nextEntry;
+    }
+    getBySymbol(symbol) {
+        return this.entries.get(normalizeBracketSymbol(symbol));
+    }
+    getByBracketId(bracketId) {
+        for (const e of this.entries.values()) {
+            if (e.bracketId === bracketId)
+                return e;
+        }
+        return undefined;
+    }
+    /** All active (non-terminal) entries. Used by reconciler + telemetry. */
+    getActive() {
+        return Array.from(this.entries.values()).filter(e => !TERMINAL_STATES.has(e.state));
+    }
+    /** Every entry in the ledger, including terminal ones (kept for audit). */
+    getAll() {
+        return Array.from(this.entries.values());
+    }
+    /** Remove an entry — typically only called for very old terminal entries
+     *  during periodic cleanup. Does NOT persist unless mutated. */
+    remove(symbol) {
+        const existed = this.entries.delete(normalizeBracketSymbol(symbol));
+        if (existed)
+            this.persist();
+        return existed;
+    }
+    /** Number of entries currently in the ledger. */
+    size() {
+        return this.entries.size;
+    }
+    /** Test seam — full ledger file path. */
+    getFilePath() {
+        return this.filePath;
+    }
+    // ---- Internals ----
+    loadOrInit() {
+        if (!existsSync(this.filePath)) {
+            logger.info(TAG, `No ledger file at ${this.filePath}; starting empty`);
+            return;
+        }
+        let raw;
+        try {
+            raw = readFileSync(this.filePath, 'utf8');
+        }
+        catch (err) {
+            throw new Error(`bracket-ledger: failed to read ${this.filePath}: ${formatError(err)}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new Error(`bracket-ledger: ${this.filePath} is not valid JSON: ${formatError(err)}`);
+        }
+        const file = this.validateFile(parsed);
+        // Symbol-normalization migration (2026-04-21): pre-fix ledgers have
+        // duplicate rows per base symbol (one with `:USDT` suffix, one without)
+        // because registerEntry keyed on whatever the caller passed in. Collapse
+        // them on load: group by normalized symbol, keep the most recent by
+        // updatedAt, discard the older. Also rewrites `entry.symbol` to the
+        // canonical form so subsequent reads see a consistent key. The migration
+        // is idempotent — a second load on an already-normalized file is a no-op.
+        let migrated = 0;
+        const byNormKey = new Map();
+        for (const rawEntry of file.entries) {
+            const normSym = normalizeBracketSymbol(rawEntry.symbol);
+            const entry = rawEntry.symbol === normSym
+                ? rawEntry
+                : (migrated++, { ...rawEntry, symbol: normSym });
+            const prev = byNormKey.get(normSym);
+            if (!prev) {
+                byNormKey.set(normSym, entry);
+                continue;
+            }
+            // Duplicate — keep the newer row. Non-terminal beats terminal at a
+            // tie (if one row is live and one cancelled, live is load-bearing).
+            const prevIsTerminal = TERMINAL_STATES.has(prev.state);
+            const entryIsTerminal = TERMINAL_STATES.has(entry.state);
+            const keepEntry = (!entryIsTerminal && prevIsTerminal) ||
+                (entryIsTerminal === prevIsTerminal && entry.updatedAt > prev.updatedAt);
+            if (keepEntry)
+                byNormKey.set(normSym, entry);
+            migrated++;
+            logger.warn(TAG, `dedup: collapsing duplicate rows for ${normSym} ` +
+                `(kept ${keepEntry ? entry.bracketId : prev.bracketId} state=${(keepEntry ? entry : prev).state}, ` +
+                `discarded ${keepEntry ? prev.bracketId : entry.bracketId} state=${(keepEntry ? prev : entry).state})`);
+        }
+        for (const entry of byNormKey.values()) {
+            this.entries.set(entry.symbol, entry);
+        }
+        if (migrated > 0) {
+            // Persist the migrated form immediately so a crash before the next
+            // mutation doesn't leave the on-disk file with the pre-migration rows.
+            this.persist();
+            logger.info(TAG, `Migrated ${migrated} ledger entries to normalized symbol form; rewrote ${this.filePath}`);
+        }
+        logger.info(TAG, `Loaded ${this.entries.size} entries from ${this.filePath}`);
+    }
+    persist() {
+        const file = {
+            schemaVersion: SCHEMA_VERSION,
+            entries: Array.from(this.entries.values()),
+        };
+        const tempPath = `${this.filePath}.tmp`;
+        // writeFileSync + renameSync gives us an atomic replace on POSIX and
+        // close-enough on Windows (MoveFileEx semantics differ slightly but
+        // there is no cross-platform better option from Node stdlib).
+        writeFileSync(tempPath, JSON.stringify(file, null, 2));
+        renameSync(tempPath, this.filePath);
+    }
+    validateFile(raw) {
+        if (!isRecord(raw))
+            throw new Error('bracket-ledger: file root is not an object');
+        const version = raw.schemaVersion;
+        if (version !== SCHEMA_VERSION) {
+            throw new Error(`bracket-ledger: unsupported schemaVersion ${version} (expected ${SCHEMA_VERSION})`);
+        }
+        if (!Array.isArray(raw.entries))
+            throw new Error('bracket-ledger: entries is not an array');
+        const entries = [];
+        for (const e of raw.entries) {
+            entries.push(this.validateEntry(e));
+        }
+        return { schemaVersion: SCHEMA_VERSION, entries };
+    }
+    validateEntry(raw) {
+        if (!isRecord(raw))
+            throw new Error('bracket-ledger: entry is not an object');
+        const requiredStrings = ['bracketId', 'symbol', 'entryCid', 'state', 'createdAt', 'updatedAt'];
+        for (const k of requiredStrings) {
+            if (typeof raw[k] !== 'string' || raw[k].length === 0) {
+                throw new Error(`bracket-ledger: entry missing/empty string field '${k}'`);
+            }
+        }
+        if (raw.entrySide !== 'buy' && raw.entrySide !== 'sell') {
+            throw new Error(`bracket-ledger: bad entrySide ${String(raw.entrySide)}`);
+        }
+        if (!VALID_STATES.has(raw.state)) {
+            throw new Error(`bracket-ledger: unknown state ${String(raw.state)}`);
+        }
+        // Optional fields are allowed to be undefined/missing; we don't
+        // type-check each one strictly — the runtime TS types give us confidence
+        // for anything written by this process.
+        return raw;
+    }
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

package/live/bracket-manager.d.ts

@@ -0,0 +1,82 @@
+import { EventEmitter } from 'node:events';
+import type { CcxtOrder } from '../types.js';
+import type { BracketId, BracketRequest } from './bracket-types.js';
+import type { BracketLedger } from './bracket-ledger.js';
+import type { BracketLegParams } from './bracket-params.js';
+/** Minimal exchange surface the manager needs. Narrowed so tests can mock
+ *  cleanly without constructing a full BinancePrivateApi. */
+export interface BracketApi {
+    /** Submit a single bracket leg (STOP_MARKET or TAKE_PROFIT_MARKET). */
+    submitBracketLeg(leg: BracketLegParams): Promise<CcxtOrder>;
+    /** Cancel an order by its clientOrderId (idempotent — "already cancelled" is success). */
+    cancelOrderByClientId(clientOrderId: string, symbol: string): Promise<void>;
+    /** Disable Binance's per-symbol countdownCancelAll dead-man's-switch
+     *  (countdownTime=0). ROOT-CAUSE FIX 2026-05-16: an externally-armed
+     *  countdown was purging every bracket ~25s after placement. Called
+     *  before every attach so protection is never placed under an active
+     *  kill-switch. Optional so paper/sim/test mocks need not implement it;
+     *  best-effort (never throws into the attach path). */
+    disableCountdownCancelAll?(symbol: string): Promise<void>;
+}
+export interface BracketManagerOpts {
+    maxAttempts?: number;
+    retryBackoffMs?: (attempt: number) => number;
+    slaMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface AttachResult {
+    ok: boolean;
+    latencyMs: number;
+    slCid?: string;
+    tpCid?: string;
+    error?: string;
+    attempts: number;
+}
+export declare class BracketManager extends EventEmitter {
+    private readonly api;
+    private readonly ledger;
+    private readonly maxAttempts;
+    private readonly backoff;
+    private readonly slaMs;
+    private readonly now;
+    private readonly sleep;
+    constructor(api: BracketApi, ledger: BracketLedger, opts?: BracketManagerOpts);
+    /** Called by LiveAdapter after submitting the entry but before fill.
+     *  Creates the ledger row in 'pending_entry' state.
+     *
+     *  Ledger hygiene: if a terminal-state row exists for this symbol (from a
+     *  prior trade cycle that closed, got cancelled, or had its brackets
+     *  stripped), remove it before inserting the new pending_entry. Otherwise
+     *  the stale row's bracketId/slCid/tpCid would survive the upsert and
+     *  mislead later callers — most visibly, `modify_stop` / `modify_target`
+     *  would see `state: 'cancelled'` and refuse to operate even though a fresh
+     *  bracket is now active. */
+    registerEntry(req: BracketRequest, bracketId: BracketId, entryCid: string): void;
+    /** Called by LiveAdapter when the entry fills. Attaches SL + TP to the
+     *  exchange with retries. Idempotent — safe to call exactly once per fill.
+     *
+     *  Intentionally NOT gated by `assertNotShuttingDown`: by the time this
+     *  runs, the entry has already filled and the position is open on Binance.
+     *  Refusing here would leave a naked position — the drain budget is sized
+     *  to cover the 3-attempt retry loop instead. New ENTRIES are gated at
+     *  `LiveAdapter.createOrder`, so once we get here the entry was authorised
+     *  before the shutdown flag was set. */
+    attachBrackets(symbol: string, entryAmount: number): Promise<AttachResult>;
+    /** Move the stop. Cancel-then-resubmit; rolls back to the old stop if the
+     *  new submission fails, so the position is never left unprotected. */
+    modifyStop(symbol: string, newStopPrice: number): Promise<void>;
+    /** Move the take-profit. Same semantics as modifyStop. */
+    modifyTarget(symbol: string, newTargetPrice: number): Promise<void>;
+    /** Cancel both bracket legs and mark the ledger cancelled. Called when
+     *  LiveAdapter closes the position via `close_position` or flatten. Risk-
+     *  reducing — allowed during shutdown, but tracked so the drain awaits it. */
+    cancelBrackets(symbol: string, reason: string): Promise<void>;
+    /** Called by the reconciler / fill poller when one of the bracket legs
+     *  fires on the exchange. Transitions the ledger to the matching triggered
+     *  state and emits. Binance's closePosition:true auto-cancels the sibling. */
+    handleBracketTriggered(symbol: string, triggeredRole: 'sl' | 'tp'): void;
+    private attemptAttach;
+    private cancelPartial;
+    private emitEvent;
+}