@reefclaw/connect 0.1.11 → 0.1.12

package/assets/plugin/live/bracket-ledger.js

@@ -1,267 +0,0 @@
-// 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/assets/plugin/live/bracket-manager.d.ts

@@ -1,82 +0,0 @@
-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;
-}