@reefclaw/openclaw-plugin 0.1.0

package/ingest/reconcile-db-vs-exchange.js

@@ -0,0 +1,114 @@
+// DB-authoritative orphan close (Increment 0 of the durable orphan-position fix).
+//
+// The problem the existing backstops can't solve: a position closed on the
+// exchange (bracket SL/TP fill or manual close) while the gateway was DOWN, or
+// whose state-store entry was already wiped, leaves webapp `positions.status`
+// stuck 'open' forever. reconcileStateStoreOnStartup can't help — it iterates
+// only LOCAL state-store entries (a wiped entry is invisible) and passes
+// lastContracts:0 (which trips the fillSize>0 guard, so it never posts a close).
+//
+// This pass is DB-authoritative: it asks the webapp for the open set (keyed by
+// the DB row id, not local state), diffs against the EXCHANGE TRUTH snapshot,
+// and posts a synthetic close for any open DB row whose symbol is absent from
+// the exchange. Keying off the DB row id means a missing webappPositionId /
+// wiped state-store / untracked contracts can't defeat it for the common
+// one-row-per-symbol case.
+//
+// Known limitations (all fail SAFE — only false-negatives, never a wrong close):
+//   - Diff is symbol-membership only. If a symbol has BOTH a genuine orphan and
+//     a freshly re-opened live position (two open rows, same symbol, different
+//     positionOpenAt), the symbol is on the exchange so NEITHER is closed — the
+//     orphan persists until the next boot when that symbol is flat. A later
+//     increment can make this count-aware (close the M−N oldest-by-openedAt when
+//     the DB has M open rows but the exchange has N<M for the symbol).
+//   - First-writer-wins on position_closes UNIQUE(position_id): if a real
+//     close_position's journal POST is still retrying at boot, a synthetic close
+//     can land first and the accurate PnL becomes a no-op. Synthetic rows are
+//     tagged (metadata.synthetic) so a later increment could upgrade them.
+//   - closeAt is stamped at boot, not the real (earlier) exchange close time, so
+//     time-in-position analytics on these rows are approximate. Tagged synthetic.
+//
+// Safety (mandatory): the caller MUST pass a TRUSTED exchange snapshot
+// (getPositionsOrNull() !== null). A failed REST fetch collapses to [] in
+// getPositions(), which would make EVERY open row look orphaned — never run
+// this pass off an untrusted/empty-on-error snapshot.
+//
+// Idempotency: position_closes is UNIQUE(position_id) with onConflictDoNothing,
+// and the parent status flip is idempotent — a real close_position (exact PnL)
+// that lands first always wins the UNIQUE. closeReason='reconciler_observed_flat'
+// + metadata.synthetic=true tags these for KPI exclusion.
+import { logger } from '../logger.js';
+const TAG = 'reconcile-db-vs-exchange';
+/** Canonicalise a symbol to its settle-suffix-free form (BTC/USDT:USDT → BTC/USDT). */
+function canonical(symbol) {
+    return symbol.split(':')[0];
+}
+/**
+ * Close webapp `positions` rows that are status='open' but absent from the
+ * (trusted) exchange snapshot. Returns the number of synthetic closes posted.
+ *
+ * @param exchangeSymbols symbols from a TRUSTED snapshot (getPositionsOrNull()
+ *        !== null). Pass only when the fetch genuinely succeeded.
+ */
+export async function reconcileDbOpenVsExchange(ctx, exchangeSymbols, nowMs = Date.now()) {
+    if (!ctx.decisionsClient || !ctx.userId)
+        return 0;
+    const resp = await ctx.decisionsClient.getOpenPositions(ctx.userId);
+    if (!resp) {
+        // null = fetch failed (network / terminal). NEVER treat as "no open rows"
+        // (null≠empty) — skip; the next boot / periodic sweep retries.
+        logger.warn(TAG, 'DB open-positions fetch returned null — skipping reconcile (will retry)');
+        return 0;
+    }
+    if (resp.positions.length === 0)
+        return 0;
+    const exchangeSet = new Set();
+    for (const s of exchangeSymbols)
+        exchangeSet.add(canonical(s));
+    const orphans = resp.positions.filter((p) => !exchangeSet.has(canonical(p.symbol)));
+    if (orphans.length === 0) {
+        logger.info(TAG, `DB reconcile: all ${resp.positions.length} open row(s) present on exchange`);
+        return 0;
+    }
+    logger.warn(TAG, `DB reconcile: ${orphans.length} open DB row(s) absent from exchange — closing: ${orphans.map((o) => o.symbol).join(', ')}`);
+    let posted = 0;
+    for (const o of orphans) {
+        if (!(o.remainingSize > 0) || !(o.entryPrice > 0)) {
+            logger.warn(TAG, `${o.symbol}: bad size/price from DB (size=${o.remainingSize}, entry=${o.entryPrice}) — skipping close`);
+            continue;
+        }
+        const close = {
+            positionId: o.id,
+            closeAt: nowMs,
+            closeReason: 'reconciler_observed_flat',
+            closeAssessment: {
+                source: 'db_exchange_sweep_boot',
+                synthetic: true,
+                note: 'Position open in DB but absent from the exchange snapshot. It was ' +
+                    'closed on-exchange via a path that bypassed close_position (bracket ' +
+                    'SL/TP fill or manual close). Synthetic close; PnL/R/MFE recomputed ' +
+                    'server-side from the entry + last review.',
+                openedAtMs: o.openedAt,
+            },
+            // Synthetic-but-neutral context. Tagged so KPI aggregation can exclude it.
+            scorecardVerdict: 'unknown',
+            confluenceScore: 0,
+            regime: 'UNKNOWN',
+            regimeConfidence: 0,
+            // The true exit price wasn't captured; use the entry so the server-side
+            // recompute yields ~0 realized PnL (honest "unknown") rather than a
+            // fabricated number. R/MFE/give-back come from the last review row.
+            fillPrice: o.entryPrice,
+            fillSize: o.remainingSize,
+            realizedPnl: 0,
+            realizedR: 0,
+            mfeRAtClose: 0,
+            giveBackPctAtClose: 0,
+            metadata: { synthetic: true, source: 'boot_reconcile' },
+        };
+        ctx.decisionsClient.postClose(ctx.userId, close);
+        posted++;
+        logger.info(TAG, `synthetic close posted ${o.symbol} (positionId=${o.id.slice(0, 8)}…, size=${o.remainingSize})`);
+    }
+    return posted;
+}

package/ingest/reconciler-cleanup.d.ts

@@ -0,0 +1,37 @@
+import type { PositionDecisionsClient } from './position-decisions-client.js';
+import type { PositionStateStore } from '../live/position-state-store.js';
+export interface ReconcilerCleanupContext {
+    decisionsClient?: PositionDecisionsClient;
+    stateStore?: PositionStateStore;
+    userId?: string;
+    /** Last-price fetcher. Plugin-side passes a closure over
+     *  `adapter.getLastPrice`. Tests inject a mock. Returning `null` skips
+     *  the webapp close post (state-store still cleaned). */
+    lastPriceFn?: (symbol: string) => Promise<number | null>;
+}
+export interface CloseObservedArgs {
+    /** Symbol observed flat. Either canonical (`BTC/USDT`) or settle-suffix
+     *  (`BTC/USDT:USDT`) form — state-store normalises internally. */
+    symbol: string;
+    /** Last contracts seen by reconciler before exchange showed flat. Used as
+     *  fillSize on the synthetic close payload. */
+    lastContracts: number;
+    /** Epoch ms — when reconciler observed the close. Defaults to Date.now(). */
+    observedAtMs?: number;
+}
+export declare function onReconcilerObservedClose(ctx: ReconcilerCleanupContext, args: CloseObservedArgs): Promise<void>;
+/** Startup-time reconciliation between state-store and exchange truth.
+ *
+ *  Why this exists: the in-memory reconciler only emits `closed` drifts on
+ *  the exact transition "was on exchange last poll, gone now". State-store
+ *  entries that persist across a close-bypass that happened BEFORE the plugin
+ *  started are invisible to that loop — they sit in `position-state.json`
+ *  forever and the next entry on the same symbol gets mistaken for a scale-in.
+ *
+ *  This pass runs once at boot, after the live adapter is initialised:
+ *  for every state-store entry, if the symbol isn't on the current exchange
+ *  snapshot, fire the same cleanup as the runtime hook would.
+ *
+ *  Returns the count of entries cleaned (for log + telemetry).
+ */
+export declare function reconcileStateStoreOnStartup(ctx: ReconcilerCleanupContext, exchangeSymbols: Iterable<string>): Promise<number>;

package/ingest/reconciler-cleanup.js

@@ -0,0 +1,147 @@
+// Reconciler-driven cleanup for the close-bypass-leaks-state class-of-bug.
+//
+// Background: when a position closes via any path other than close_position()
+// — i.e., bracket SL/TP fill, opposite-side market order, or external close on
+// the exchange UI — onClosePositionFilled never runs. Two pieces of state leak:
+//
+//   1. webapp `positions.status` stays 'open' indefinitely (until a manual
+//      `scripts/reconcile-open-positions.py` sweep).
+//   2. `position-state.json` keeps the entry with its stale `webappPositionId`.
+//      The next entry on the same symbol is then mistaken for a scale-in and
+//      reviews silently drop because the cached id no longer maps to a live
+//      DB row.
+//
+// All three close-bypass paths converge on the same observable: the next
+// reconciler tick (60 s cadence) sees the symbol gone from `getPositions()`
+// and emits a `drift_detected` event with `type='closed'`. We hook there.
+//
+// Two-phase cleanup:
+//   Phase 1 — synthetic close to webapp (best-effort): if the state-store
+//             entry has a `webappPositionId` and we can fetch a last price,
+//             POST `/api/internal/position-closes` with a stub close payload
+//             tagged `closeReason='reconciler_observed_flat'`. Webapp
+//             recomputes realized PnL/R/MFE server-side from positionEntries +
+//             last review (the same path the close auto-capture uses).
+//   Phase 2 — state-store cleanup (unconditional): drop the entry. This is
+//             the more important half — it prevents the next entry on the
+//             same symbol from being mistaken for a scale-in.
+//
+// Idempotency:
+//   - webapp endpoint dedups via UNIQUE on position_id (onConflictDoNothing).
+//   - state-store remove is a no-op if the entry is already gone.
+// Re-firing on subsequent reconciler ticks is safe.
+//
+// Failure mode tradeoff: when no last-price is reachable, we skip the webapp
+// post but still clean state-store. The DB row stays 'open' until manual
+// reconcile (existing operator workflow). State-store cleanup alone closes
+// the next-entry-mistaken-for-scale-in failure mode, which is the harder one
+// to recover from.
+import { logger } from '../logger.js';
+const TAG = 'reconciler-cleanup';
+export async function onReconcilerObservedClose(ctx, args) {
+    if (!ctx.stateStore)
+        return;
+    const entry = ctx.stateStore.get(args.symbol);
+    if (!entry) {
+        // Already clean. Could happen if close_position fired between the WS
+        // close fill and this reconciler tick — onClosePositionFilled removed the
+        // entry first. Silent no-op.
+        return;
+    }
+    const webappPositionId = entry.webappPositionId;
+    const observedAtMs = args.observedAtMs ?? Date.now();
+    if (webappPositionId && ctx.decisionsClient && ctx.userId) {
+        let lastPrice = null;
+        if (ctx.lastPriceFn) {
+            try {
+                lastPrice = await ctx.lastPriceFn(args.symbol);
+            }
+            catch (err) {
+                logger.warn(TAG, `lastPriceFn(${args.symbol}) threw: ${err instanceof Error ? err.message : String(err)} — synthetic close will be skipped`);
+            }
+        }
+        const fillSize = Math.abs(args.lastContracts);
+        if (lastPrice !== null && lastPrice > 0 && fillSize > 0) {
+            const close = {
+                positionId: webappPositionId,
+                closeAt: observedAtMs,
+                closeReason: 'reconciler_observed_flat',
+                closeAssessment: {
+                    note: 'Position observed flat on exchange via reconciler. Close path ' +
+                        'bypassed close_position (likely bracket SL/TP fill, opposite-side ' +
+                        'market order, or external close). Synthetic close row.',
+                    observedAtMs,
+                    lastContracts: args.lastContracts,
+                },
+                scorecardVerdict: 'NO_GO',
+                confluenceScore: 0,
+                regime: 'unknown',
+                regimeConfidence: 0.5,
+                fillPrice: lastPrice,
+                fillSize,
+                // Webapp recomputes these server-side from positionEntries + last
+                // review when all four arrive as zero (same code path the close
+                // auto-capture uses).
+                realizedPnl: 0,
+                realizedR: 0,
+                mfeRAtClose: 0,
+                giveBackPctAtClose: 0,
+            };
+            ctx.decisionsClient.postClose(ctx.userId, close);
+            logger.info(TAG, `synthetic close posted ${args.symbol} ` +
+                `(positionId=${webappPositionId.slice(0, 8)}…, ` +
+                `price=${lastPrice}, size=${fillSize})`);
+        }
+        else {
+            logger.warn(TAG, `${args.symbol}: cannot post synthetic close ` +
+                `(lastPrice=${lastPrice ?? 'null'}, size=${fillSize}); ` +
+                `state-store entry will still be cleaned. DB row may stay ` +
+                `status='open' until reconcile-open-positions.py runs.`);
+        }
+    }
+    else if (!webappPositionId) {
+        logger.info(TAG, `${args.symbol}: orphan entry (no webappPositionId, parent row never created) — cleaning state-store only`);
+    }
+    ctx.stateStore.remove(args.symbol);
+}
+/** Startup-time reconciliation between state-store and exchange truth.
+ *
+ *  Why this exists: the in-memory reconciler only emits `closed` drifts on
+ *  the exact transition "was on exchange last poll, gone now". State-store
+ *  entries that persist across a close-bypass that happened BEFORE the plugin
+ *  started are invisible to that loop — they sit in `position-state.json`
+ *  forever and the next entry on the same symbol gets mistaken for a scale-in.
+ *
+ *  This pass runs once at boot, after the live adapter is initialised:
+ *  for every state-store entry, if the symbol isn't on the current exchange
+ *  snapshot, fire the same cleanup as the runtime hook would.
+ *
+ *  Returns the count of entries cleaned (for log + telemetry).
+ */
+export async function reconcileStateStoreOnStartup(ctx, exchangeSymbols) {
+    if (!ctx.stateStore)
+        return 0;
+    // Normalise the exchange symbol list — state-store stores canonical form.
+    const exchangeSet = new Set();
+    for (const sym of exchangeSymbols) {
+        exchangeSet.add(sym.split(':')[0]);
+    }
+    const stale = ctx.stateStore.getAll().filter((e) => !exchangeSet.has(e.symbol));
+    if (stale.length === 0) {
+        logger.info(TAG, `startup reconcile: state-store clean (${ctx.stateStore.size()} entries match exchange)`);
+        return 0;
+    }
+    logger.warn(TAG, `startup reconcile: ${stale.length} stale state-store entr${stale.length === 1 ? 'y' : 'ies'} ` +
+        `not on exchange — cleaning: ${stale.map((e) => e.symbol).join(', ')}`);
+    for (const entry of stale) {
+        await onReconcilerObservedClose(ctx, {
+            symbol: entry.symbol,
+            // We don't know the closing size — pass 0 so the synthetic close
+            // post is skipped (size validation in cleanup). State-store entry
+            // is still removed. Operator runs reconcile-open-positions.py to
+            // close any matching DB rows.
+            lastContracts: 0,
+        });
+    }
+    return stale.length;
+}

package/ingest/rest-gap-filler.d.ts

@@ -0,0 +1,191 @@
+import type { BinancePrivateApi } from '../ccxt/binance-private.js';
+import type { UserDataStream } from '../live/user-data-stream.js';
+import type { LiveStateStore } from '../live/live-state-store.js';
+import type { TradeStoreClient } from './trade-store-client.js';
+import { TouchedSymbolsStore } from './touched-symbols-store.js';
+export interface RestGapFillerOptions {
+    api: BinancePrivateApi;
+    stream: UserDataStream;
+    store: LiveStateStore;
+    client: TradeStoreClient;
+    userId: string;
+    /** Defaults to 'binance_futures'. */
+    exchange?: string;
+    /** How far BEFORE the disconnect to start the backfill window. A 10s
+     *  buffer compensates for clock skew between the client and exchange
+     *  and for any in-flight frames we may have already processed.
+     *  Dedupe at the webapp prevents duplicate rows. */
+    safetyBufferMs?: number;
+    /** Hard floor on the backfill window. A long outage shouldn't trigger
+     *  a fetchMyTrades that walks back days. Binance returns up to 1000
+     *  trades per symbol per call; past that you need multiple paginated
+     *  calls. Default 1h. If a real outage exceeds this, operator runs the
+     *  Phase 2 continuous reconciler separately. */
+    maxWindowMs?: number;
+    /** Limit on trades per symbol per call. Binance cap is 1000. */
+    perSymbolLimit?: number;
+    /** Run a one-shot deep backfill on start() that recovers fills which landed
+     *  while the plugin was DOWN — the reconnect path (handleResyncRequired) only
+     *  covers gaps while the plugin is RUNNING, so a position's closing trade that
+     *  fills during downtime is never re-pushed by the WS and accumulates silently
+     *  across restarts. Defaults to OFF; activate via env `RC_GAPFILL_STARTUP=on`. */
+    startupDeepFill?: boolean;
+    /** How far back the startup deep-fill looks. Default 7 days (env
+     *  `RC_GAPFILL_STARTUP_LOOKBACK_MS`). Sized to cover realistic inter-restart
+     *  downtime; a longer outage is a one-off the operator backfills manually. */
+    startupLookbackMs?: number;
+    /** Delay between paced Binance calls in the deep-fill (per page + per symbol),
+     *  to stay clear of the per-IP weight ceiling. Default 250ms
+     *  (env `RC_GAPFILL_PACE_MS`). */
+    deepFillPaceMs?: number;
+    /** Safety cap on paginated pages per 7-day window in the deep-fill — bounds
+     *  the worst case if a symbol churned a huge number of fills. Default 25. */
+    maxPagesPerWindow?: number;
+    /** Persistent symbol store. Defaults to a file-backed implementation
+     *  under ~/.reefclaw/touched-symbols-<userId>.json. Tests inject a
+     *  store pointed at a tmpdir path or a stub. Pass `null` to disable
+     *  persistence entirely (in-memory only). */
+    touchedSymbolsStore?: TouchedSymbolsStore | null;
+    /** For unit tests — injected clock. */
+    now?: () => number;
+}
+export interface RestGapFillerHealth {
+    reconnectEvents: number;
+    gapFillRuns: number;
+    symbolsQueried: number;
+    tradesBackfilled: number;
+    errorCount: number;
+}
+export declare class RestGapFiller {
+    private readonly api;
+    private readonly stream;
+    private readonly store;
+    private readonly client;
+    private readonly userId;
+    private readonly exchange;
+    private readonly safetyBufferMs;
+    private readonly maxWindowMs;
+    private readonly perSymbolLimit;
+    private readonly startupDeepFill;
+    private readonly startupLookbackMs;
+    private readonly deepFillPaceMs;
+    private readonly maxPagesPerWindow;
+    private readonly now;
+    /** Every symbol we've seen via WS orderUpdate, a position snapshot, or
+     *  the persistent disk store. Never shrinks — a symbol's closing trade
+     *  may still be pending delivery when its position hits zero, and a
+     *  symbol traded in a previous session is still a candidate for fills
+     *  the WS missed during a plugin restart. */
+    private readonly knownSymbols;
+    /** Optional file-backed persistence so the symbol universe survives
+     *  plugin restarts. Null in tests that want pure in-memory behaviour. */
+    private readonly touchedStore;
+    /** Timestamp of the last observed disconnect. Bootstrapped to null so
+     *  the initial window (before the first disconnect) contributes no
+     *  backfill — no blind window existed before the stream was ever up. */
+    private lastDisconnectAt;
+    private started;
+    private readonly onResyncRequired;
+    private readonly onDisconnected;
+    private readonly onOrderUpdate;
+    private reconnectEvents;
+    private gapFillRuns;
+    private symbolsQueried;
+    private tradesBackfilled;
+    private errorCount;
+    constructor(opts: RestGapFillerOptions);
+    start(): void;
+    stop(): void;
+    getHealth(): RestGapFillerHealth;
+    /** Testing hook — lets unit tests trigger a gap-fill pass with a known
+     *  time window instead of replaying stream events. */
+    runGapFill(since: number): Promise<void>;
+    /** One-shot startup deep-fill — the recurrence fix.
+     *
+     *  The reconnect gap-fill (handleResyncRequired) only covers blind windows
+     *  while the plugin is RUNNING and caps its lookback at maxWindowMs (1h). A
+     *  fill that lands while the plugin is DOWN — most damagingly a position's
+     *  closing trade — is never re-pushed by the event-driven WS and was never
+     *  gap-filled, so it silently never reaches the `trades` ledger. Over many
+     *  restarts these missing closes accumulate and make the journal's net-PnL
+     *  (derived from the ledger) wrong. This pass queries userTrades for every
+     *  known symbol over a configurable lookback so downtime closes land on the
+     *  next start. Paginated + 7-day-window-chunked (Binance caps userTrades at
+     *  1000 rows / 7-day span per call) and paced to stay clear of the per-IP
+     *  weight ceiling. Idempotent at the webapp (ON CONFLICT DO NOTHING), so
+     *  re-querying already-recorded fills is a harmless no-op. */
+    runStartupDeepFill(sinceFloor: number): Promise<void>;
+    /** Deep-fill a single symbol over [sinceFloor, now], chunked into ≤7-day
+     *  windows (Binance's per-call span cap). Within a window the FIRST page is
+     *  time-bounded (startTime/endTime); FULL pages continue via Binance's
+     *  `fromId = lastTradeId + 1` (doc-verified: fromId pages ascending by
+     *  trade id and CANNOT be combined with startTime/endTime), stopping when
+     *  a page runs past the window end, comes back short, or hits the page
+     *  cap. Paging by id — not by `lastTime + 1` — is what keeps
+     *  same-millisecond trades on a full-page boundary from being skipped.
+     *
+     *  Every fetch goes through the ban-gated `api.fetchMyTradesOrNull`
+     *  wrapper — we deliberately do NOT use CCXT's built-in `{ paginate: true }`,
+     *  which re-enters CCXT directly and would bypass the process-wide IP-ban
+     *  gate. A `null` read (paced / banned / garbled) is a FAILED read, not an
+     *  empty window: we abort THIS symbol by throwing (caller logs + counts the
+     *  error and continues other symbols) instead of advancing the cursor —
+     *  error-as-empty silently truncated the backfill exactly when Binance was
+     *  shedding us. Returns the number of fills posted. */
+    private deepFillSymbol;
+    /** Epoch-ms timestamp of a CCXT trade — unified `timestamp` first, raw
+     *  Binance `info.time` as fallback. 0 when neither is present. */
+    private tradeTime;
+    /** Numeric Binance trade id of a CCXT trade — unified `id` first, raw
+     *  `info.id` fallback. Null when not a finite number (`fromId` is a LONG
+     *  on the Binance side, so a non-numeric id cannot seed pagination). */
+    private tradeId;
+    /** Cooperative delay used to pace deep-fill Binance calls. Resolves
+     *  immediately for a non-positive duration (e.g. tests pass 0). */
+    private sleep;
+    private handleResyncRequired;
+    private handleDisconnected;
+    private seedKnownSymbolsFromStore;
+    /** Merge the on-disk symbol history into the in-memory set. Best-effort —
+     *  load() returns an empty Set on any error so a corrupt cache file is a
+     *  silent regression to "session-only" behaviour, never a startup blocker. */
+    private hydrateKnownSymbolsFromDisk;
+    /** Discovery via /fapi/v1/income. Catches symbols traded during a blind
+     *  window (plugin downtime, mid-session WS outage) that aren't represented
+     *  in the persisted touched cache or the current open-position seed —
+     *  i.e. brand-new symbols that opened AND closed entirely during the gap.
+     *
+     *  `since` defaults to the maxWindow lookback (used by start()'s one-shot
+     *  pass). On every resync, handleResyncRequired passes the reconnect's
+     *  computed `since` so the discovery window precisely matches the
+     *  fetchMyTrades window — a single REST call recovers every symbol that
+     *  could have had activity in the gap.
+     *
+     *  Best-effort: any error logs and returns; gap-fill still runs against
+     *  whatever knownSymbols already contains. */
+    private discoverSymbolsFromIncome;
+    /** Convert raw CCXT trade objects to FillEvents and post each to the
+     *  webapp ingest endpoint. Returns the count successfully posted
+     *  (posted means handed to the HTTP client; upsert dedup happens in
+     *  the webapp). Silent on empty input. */
+    private postTrades;
+    /** Map a CCXT trade (Binance /fapi/v1/userTrades) to our FillEvent shape.
+     *  Returns null on malformed input — tradeId + orderId + price + qty are
+     *  all required columns on the trades table.
+     *
+     *  Binance raw field names (NOT CCXT-unified) per the docs — we read these
+     *  via `t.info.*` as the second-choice source after CCXT's unified fields:
+     *    id, orderId, symbol, side, positionSide, price, qty, quoteQty,
+     *    commission, commissionAsset, time, buyer, maker, realizedPnl.
+     *  Spec: https://developers.binance.com/docs/derivatives/usds-margined-futures/trade/rest-api/Account-Trade-List
+     *
+     *  Fields NOT returned by userTrades (document-verified):
+     *   - `reduceOnly` — lives on order endpoints, not trades. Gap-filled rows
+     *     get reduceOnly=undefined; the primary WS path (source='ws') always
+     *     has it. Since dedup preserves the first-writer row, trades delivered
+     *     by WS retain reduceOnly; only genuinely-missed-by-WS trades that the
+     *     gap-filler rescues will have this field blank. Acceptable gap.
+     *   - `clientOrderId` — same: lives on the order, not the trade. We infer
+     *     from the ledger by crosswalking `orderId` if consumers need it. */
+    private tradeToFillEvent;
+}