@hoox-sh/pynets 0.1.0

package/src/runtime/strategy.ts

@@ -0,0 +1,1105 @@
+/**
+ * Copyright (C) 2024-2026 jango_blockchained
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * Strategy event bus plus a tiny market-fill + pending limit/stop model
+ * (not a full broker). entry/close/exit stay event-only. fillEntry/fillClose
+ * update a single signed position and fills. processPending is called once
+ * per bar BEFORE the script body. Optional commission, slippage, pyramiding.
+ * Non-finite qty/price is a no-op (never corrupts position).
+ * fillEntry from flat / reverse leftover opens a trade; flatten moves it to closed.
+ */
+
+export type StrategyDirection = "long" | "short";
+
+export interface BrokerSettings {
+  commission?: number; // fraction of notional, default 0 (0.001 = 0.1%)
+  slippage?: number; // price units added against the trade, default 0
+  pyramiding?: number; // max same-direction adds; 0 = no extra adds; omitted = unlimited
+}
+
+export interface StrategyEvent {
+  type: "entry" | "close" | "exit" | "cancel" | "close_all" | "cancel_all" | "fill";
+  id: string;
+  direction?: StrategyDirection;
+  qty?: number | null;
+  bar: number;
+}
+
+export interface Position {
+  qty: number; // signed: >0 long, <0 short
+  avgPrice: number | null;
+}
+
+export interface Fill {
+  bar: number;
+  id: string;
+  side: "buy" | "sell";
+  qty: number;
+  price: number;
+}
+
+export type OcaType = "none" | "cancel" | "reduce";
+export type AllowEntryIn = "all" | "long" | "short";
+
+export interface PendingOrder {
+  id: string;
+  direction: StrategyDirection;
+  qty: number;
+  limit: number | null;
+  stop: number | null;
+  bar: number;
+  oca_name?: string | null;
+  oca_type?: OcaType;
+}
+
+export interface PlaceEntryOpts {
+  limit?: number | null;
+  stop?: number | null;
+  /** Market fill price when both limit and stop are unset. */
+  price?: number;
+  comment?: string;
+  time?: number;
+  oca_name?: string | null;
+  oca_type?: string | null;
+}
+
+/** One open or closed strategy trade (qty is absolute). */
+export interface Trade {
+  id: string;
+  direction: StrategyDirection;
+  qty: number;
+  entryBar: number;
+  entryPrice: number;
+  entryTime?: number;
+  exitBar?: number;
+  exitPrice?: number;
+  profit?: number;
+  commission: number;
+  comment?: string;
+  max_runup?: number;
+  max_drawdown?: number;
+}
+
+export interface BarOhlc {
+  open?: number;
+  high?: number;
+  low?: number;
+  close?: number;
+}
+
+/** Snapshot of book-level performance scalars (for RuntimeResult). */
+export interface StrategySummary {
+  netprofit: number;
+  netprofitPercent: number;
+  openprofit: number;
+  equity: number;
+  wintrades: number;
+  losstrades: number;
+  eventrades: number;
+  closedtrades: number;
+  opentrades: number;
+  grossprofit: number;
+  grossloss: number;
+  avgTrade: number;
+  avgWinningTrade: number;
+  avgLosingTrade: number;
+  percentProfitable: number;
+  profitFactor: number;
+  maxDrawdown: number;
+  maxDrawdownPercent: number;
+  maxRunup: number;
+  maxRunupPercent: number;
+  initialCapital: number;
+}
+
+function isFiniteNumber(v: unknown): v is number {
+  return typeof v === "number" && Number.isFinite(v);
+}
+
+function optLevel(v: number | null | undefined): number | null {
+  return isFiniteNumber(v) ? v : null;
+}
+
+/** Raw trigger price (slippage applied later via recordFill). */
+function triggerPrice(order: PendingOrder, open: number, high: number, low: number): number | null {
+  const lim = order.limit;
+  const stop = order.stop;
+  const d = order.direction;
+  if (lim != null && stop != null) {
+    // Stop-limit: stop must trigger and limit must still be available.
+    if (d === "long" && high >= stop && low <= lim) return lim;
+    if (d === "short" && low <= stop && high >= lim) return lim;
+    return null;
+  }
+  if (lim != null) {
+    if (d === "long" && low <= lim) return Math.min(lim, open);
+    if (d === "short" && high >= lim) return Math.max(lim, open);
+    return null;
+  }
+  if (stop != null) {
+    if (d === "long" && high >= stop) return Math.max(stop, open);
+    if (d === "short" && low <= stop) return Math.min(stop, open);
+    return null;
+  }
+  return null;
+}
+
+function finiteOr(v: unknown, fallback: number): number {
+  return isFiniteNumber(v) ? v : fallback;
+}
+
+/** Omitted / non-finite → unlimited (`undefined`). Else max(0, trunc). */
+function normalizePyramiding(v: unknown): number | undefined {
+  if (v == null || !isFiniteNumber(v)) return undefined;
+  return Math.max(0, Math.trunc(v));
+}
+
+/** 1 / "long" / *long* → long; -1 / "short" / *short* → short. */
+function mapDirection(direction: unknown): StrategyDirection {
+  if (direction === 1 || direction === "1") return "long";
+  if (direction === -1 || direction === "-1") return "short";
+  const s = String(direction ?? "").toLowerCase();
+  if (s.includes("long")) return "long";
+  if (s.includes("short")) return "short";
+  return "long";
+}
+
+/** Calendar-day bucket: ms epoch, seconds epoch, or raw (Python `_day_bucket`). */
+function dayBucket(ts: number): number {
+  const t = Math.trunc(ts);
+  if (t > 10_000_000_000) return Math.trunc(t / 86_400_000);
+  if (t > 10_000_000) return Math.trunc(t / 86_400);
+  return t;
+}
+
+/** `strategy.oca.cancel` / `oca.cancel` / `cancel` → cancel (else reduce / none). */
+function normalizeOcaType(raw: unknown): OcaType {
+  const s = String(raw ?? "none").trim().toLowerCase();
+  if (s === "cancel" || s === "oca.cancel" || s === "strategy.oca.cancel") return "cancel";
+  if (s === "reduce" || s === "oca.reduce" || s === "strategy.oca.reduce") return "reduce";
+  return "none";
+}
+
+export class StrategyBook {
+  readonly events: StrategyEvent[] = [];
+  readonly position: Position = { qty: 0, avgPrice: null };
+  readonly fills: Fill[] = [];
+  readonly pending: PendingOrder[] = [];
+  readonly openTrades: Trade[] = [];
+  readonly closedTrades: Trade[] = [];
+  commissionPaid = 0;
+  realizedPnl = 0;
+  closedCount = 0;
+  wintrades = 0;
+  losstrades = 0;
+  eventrades = 0;
+  grossprofit = 0;
+  /** Positive magnitude of losing-trade profits. */
+  grossloss = 0;
+  initialCapital = 1_000_000;
+
+  /** strategy.risk.allow_entry_in — `all` | `long` | `short`. */
+  allow_entry_in: AllowEntryIn = "all";
+  max_position_size_percent?: number;
+  max_drawdown_risk?: number;
+  max_drawdown_risk_percent?: number;
+  max_cons_loss_days?: number;
+  /** Intraday loss halt as % of initial capital; `Infinity` = unset. */
+  max_intraday_loss = Number.POSITIVE_INFINITY;
+  max_intraday_filled_orders?: number;
+  entries_blocked = false;
+  consecutive_loss_days = 0;
+
+  get opentrades(): number {
+    return this.openTrades.length;
+  }
+
+  get closedtrades(): number {
+    return this.closedTrades.length;
+  }
+
+  private commission: number;
+  private slippage: number;
+  private pyramiding: number | undefined;
+  private sameDirAdds = 0;
+  private lastTradeDay: number | null = null;
+  private dayPnl = 0;
+  private fillsDay: number | null = null;
+  private dayFilledOrders = 0;
+  private equityPeak: number;
+  private equityTrough: number;
+  private maxDrawdownAbs = 0;
+  private maxDdPercent = 0;
+  private maxRunupAbs = 0;
+  private maxRuPercent = 0;
+  private maxHeldAll = 0;
+  private maxHeldLong = 0;
+  private maxHeldShort = 0;
+
+  constructor(settings?: BrokerSettings) {
+    this.commission = finiteOr(settings?.commission, 0);
+    this.slippage = finiteOr(settings?.slippage, 0);
+    this.pyramiding = normalizePyramiding(settings?.pyramiding);
+    this.equityPeak = this.initialCapital;
+    this.equityTrough = this.initialCapital;
+  }
+
+  /** Mark-to-market equity: initial + realized − commission + open PnL. */
+  equity(mark: number): number {
+    this.ensureSanePosition();
+    const q = this.position.qty;
+    const avg = this.position.avgPrice;
+    const realized = isFiniteNumber(this.realizedPnl) ? this.realizedPnl : 0;
+    const paid = isFiniteNumber(this.commissionPaid) ? this.commissionPaid : 0;
+    const open =
+      q === 0 || !isFiniteNumber(avg) || !isFiniteNumber(mark) ? 0 : q * (mark - avg);
+    const eq = this.initialCapital + realized - paid + open;
+    this.trackEquityCurve(eq);
+    return eq;
+  }
+
+  closedTrade(i: number): Trade | null {
+    return this.pickTrade(this.closedTrades, i);
+  }
+
+  openTrade(i: number): Trade | null {
+    return this.pickTrade(this.openTrades, i);
+  }
+
+  closedEntryBar(i: number): number | null {
+    return this.closedTrade(i)?.entryBar ?? null;
+  }
+
+  closedEntryPrice(i: number): number | null {
+    return this.closedTrade(i)?.entryPrice ?? null;
+  }
+
+  closedExitBar(i: number): number | null {
+    return this.closedTrade(i)?.exitBar ?? null;
+  }
+
+  closedExitPrice(i: number): number | null {
+    return this.closedTrade(i)?.exitPrice ?? null;
+  }
+
+  closedProfit(i: number): number | null {
+    const t = this.closedTrade(i);
+    return t != null && t.profit !== undefined ? t.profit : null;
+  }
+
+  closedSize(i: number): number | null {
+    return this.closedTrade(i)?.qty ?? null;
+  }
+
+  closedId(i: number): string | null {
+    return this.closedTrade(i)?.id ?? null;
+  }
+
+  closedCommission(i: number): number | null {
+    return this.closedTrade(i)?.commission ?? null;
+  }
+
+  openEntryBar(i: number): number | null {
+    return this.openTrade(i)?.entryBar ?? null;
+  }
+
+  openEntryPrice(i: number): number | null {
+    return this.openTrade(i)?.entryPrice ?? null;
+  }
+
+  openSize(i: number): number | null {
+    return this.openTrade(i)?.qty ?? null;
+  }
+
+  openId(i: number): string | null {
+    return this.openTrade(i)?.id ?? null;
+  }
+
+  openProfit(i: number, markPrice: number): number | null {
+    const t = this.openTrade(i);
+    if (t == null || !isFiniteNumber(markPrice)) return null;
+    return this.markProfit(t, markPrice);
+  }
+
+  avgTrade(): number {
+    const n = this.closedTrades.length;
+    return n === 0 ? 0 : (this.grossprofit - this.grossloss) / n;
+  }
+
+  avgWinningTrade(): number {
+    return this.wintrades === 0 ? 0 : this.grossprofit / this.wintrades;
+  }
+
+  avgLosingTrade(): number {
+    return this.losstrades === 0 ? 0 : this.grossloss / this.losstrades;
+  }
+
+  /** Realized net profit (closed-trade price PnL). */
+  netprofit(): number {
+    return isFiniteNumber(this.realizedPnl) ? this.realizedPnl : 0;
+  }
+
+  /** `100 * netprofit / initialCapital`; 0 if capital ≤ 0. */
+  netprofitPercent(_mark?: number): number {
+    return this.pctOfInitial(this.netprofit());
+  }
+
+  /** Signed open PnL at `mark`; 0 if flat or mark is non-finite. */
+  openprofit(mark: number): number {
+    this.ensureSanePosition();
+    const q = this.position.qty;
+    const avg = this.position.avgPrice;
+    if (q === 0 || !isFiniteNumber(avg) || !isFiniteNumber(mark)) return 0;
+    return q * (mark - avg);
+  }
+
+  /** `100 * openprofit / initialCapital`; 0 if capital ≤ 0. */
+  openprofitPercent(mark: number): number {
+    return this.pctOfInitial(this.openprofit(mark));
+  }
+
+  grossprofitPercent(): number {
+    return this.pctOfInitial(this.grossprofit);
+  }
+
+  grosslossPercent(): number {
+    return this.pctOfInitial(this.grossloss);
+  }
+
+  avgTradePercent(): number {
+    return this.pctOfInitial(this.avgTrade());
+  }
+
+  avgWinningTradePercent(): number {
+    return this.pctOfInitial(this.avgWinningTrade());
+  }
+
+  avgLosingTradePercent(): number {
+    return this.pctOfInitial(this.avgLosingTrade());
+  }
+
+  /** Book-level peak-to-trough equity drop (positive magnitude). */
+  maxDrawdown(): number {
+    return this.maxDrawdownAbs;
+  }
+
+  maxDrawdownPercent(): number {
+    return this.maxDdPercent;
+  }
+
+  /** Book-level trough-to-peak equity rise. */
+  maxRunup(): number {
+    return this.maxRunupAbs;
+  }
+
+  maxRunupPercent(): number {
+    return this.maxRuPercent;
+  }
+
+  /** `100 * wintrades / closedtrades`; 0 if none closed. */
+  percentProfitable(): number {
+    const n = this.closedTrades.length;
+    return n === 0 ? 0 : (100 * this.wintrades) / n;
+  }
+
+  /**
+   * `grossprofit / grossloss`. 0 if both 0; 999.99 if profit and no loss
+   * (Python backtest caps Inf).
+   */
+  profitFactor(): number {
+    const gp = this.grossprofit;
+    const gl = this.grossloss;
+    if (!isFiniteNumber(gp) || !isFiniteNumber(gl)) return 0;
+    if (gl > 0) return gp / gl;
+    return gp > 0 ? 999.99 : 0;
+  }
+
+  maxContractsHeldAll(): number {
+    return this.maxHeldAll;
+  }
+
+  maxContractsHeldLong(): number {
+    return this.maxHeldLong;
+  }
+
+  maxContractsHeldShort(): number {
+    return this.maxHeldShort;
+  }
+
+  summary(mark: number): StrategySummary {
+    return {
+      netprofit: this.netprofit(),
+      netprofitPercent: this.netprofitPercent(mark),
+      openprofit: this.openprofit(mark),
+      equity: this.equity(mark),
+      wintrades: this.wintrades,
+      losstrades: this.losstrades,
+      eventrades: this.eventrades,
+      closedtrades: this.closedtrades,
+      opentrades: this.opentrades,
+      grossprofit: this.grossprofit,
+      grossloss: this.grossloss,
+      avgTrade: this.avgTrade(),
+      avgWinningTrade: this.avgWinningTrade(),
+      avgLosingTrade: this.avgLosingTrade(),
+      percentProfitable: this.percentProfitable(),
+      profitFactor: this.profitFactor(),
+      maxDrawdown: this.maxDrawdown(),
+      maxDrawdownPercent: this.maxDrawdownPercent(),
+      maxRunup: this.maxRunup(),
+      maxRunupPercent: this.maxRunupPercent(),
+      initialCapital: this.initialCapital,
+    };
+  }
+
+  /** Update per-open-trade max_runup / max_drawdown vs mark (high/low if finite, else close). */
+  markOpenTrades(high: number, low: number, close: number): void {
+    if (this.openTrades.length === 0) return;
+    for (const t of this.openTrades) {
+      const fav = t.direction === "long"
+        ? (isFiniteNumber(high) ? high : close)
+        : (isFiniteNumber(low) ? low : close);
+      const adv = t.direction === "long"
+        ? (isFiniteNumber(low) ? low : close)
+        : (isFiniteNumber(high) ? high : close);
+      if (isFiniteNumber(fav)) {
+        const runup = this.markProfit(t, fav);
+        if (runup > 0) t.max_runup = Math.max(t.max_runup ?? 0, runup);
+      }
+      if (isFiniteNumber(adv)) {
+        const dd = this.markProfit(t, adv);
+        if (dd < 0) t.max_drawdown = Math.max(t.max_drawdown ?? 0, -dd);
+      }
+    }
+  }
+
+  configure(settings: BrokerSettings): void {
+    if (isFiniteNumber(settings.commission)) this.commission = settings.commission;
+    if (isFiniteNumber(settings.slippage)) this.slippage = settings.slippage;
+    if (settings.pyramiding !== undefined) {
+      const pyr = normalizePyramiding(settings.pyramiding);
+      if (pyr !== undefined || settings.pyramiding == null) this.pyramiding = pyr;
+    }
+  }
+
+  /** `strategy.risk.allow_entry_in(value)` — `all` | `long` | `short`. */
+  riskAllowEntryIn(value: unknown = "all"): void {
+    const s = String(value ?? "all").replace(/strategy\./gi, "").trim().toLowerCase();
+    this.allow_entry_in = s === "long" || s === "short" || s === "all" ? s : "all";
+  }
+
+  /** `strategy.risk.max_position_size(percent)` — cap entry notional vs equity. */
+  riskMaxPositionSize(percent: unknown): void {
+    if (percent == null || !isFiniteNumber(percent) || percent <= 0) return;
+    this.max_position_size_percent = percent;
+  }
+
+  /**
+   * `strategy.risk.max_drawdown(value, type)` — absolute or % of peak equity.
+   * Percent types: `percent` / `percentage` / `percent_of_equity` / `%`.
+   */
+  riskMaxDrawdown(value: unknown, type: unknown = "absolute"): void {
+    if (value == null || !isFiniteNumber(value) || value < 0) return;
+    const rt = String(type ?? "absolute").replace(/strategy\./gi, "").trim().toLowerCase();
+    if (rt === "percent" || rt === "percentage" || rt === "percent_of_equity" || rt === "%") {
+      this.max_drawdown_risk_percent = value;
+    } else {
+      this.max_drawdown_risk = value;
+    }
+  }
+
+  /** `strategy.risk.max_cons_loss_days(days)` — halt after N finalized loss days. */
+  riskMaxConsLossDays(days: unknown): void {
+    if (days == null || !isFiniteNumber(days)) return;
+    const d = Math.trunc(days);
+    if (d < 0) return;
+    this.max_cons_loss_days = d;
+  }
+
+  /** `strategy.risk.max_intraday_loss(percent)` — halt on day loss % of capital. */
+  riskMaxIntradayLoss(percent: unknown): void {
+    if (percent == null || !isFiniteNumber(percent) || percent < 0) return;
+    this.max_intraday_loss = percent;
+  }
+
+  /** `strategy.risk.max_intraday_filled_orders(max)` — cap fills per day bucket. */
+  riskMaxIntradayFilledOrders(max: unknown): void {
+    if (max == null || !isFiniteNumber(max)) return;
+    const n = Math.trunc(max);
+    if (n < 0) return;
+    this.max_intraday_filled_orders = n;
+  }
+
+  /**
+   * Track consecutive calendar-day losses (Python `note_closed_trade_day`).
+   * A day's PnL is finalized when a close lands on a later day bucket.
+   */
+  noteClosedTradeDay(exitTime: number, profit: number): void {
+    if (!isFiniteNumber(exitTime) || !isFiniteNumber(profit)) return;
+    const day = dayBucket(exitTime);
+    if (this.lastTradeDay == null || day !== this.lastTradeDay) {
+      if (this.lastTradeDay != null) {
+        if (this.dayPnl < 0) this.consecutive_loss_days += 1;
+        else if (this.dayPnl > 0) this.consecutive_loss_days = 0;
+      }
+      this.lastTradeDay = day;
+      this.dayPnl = 0;
+    }
+    this.dayPnl += profit;
+    if (this.max_cons_loss_days != null && this.consecutive_loss_days >= this.max_cons_loss_days) {
+      this.entries_blocked = true;
+    }
+    if (
+      Number.isFinite(this.max_intraday_loss) &&
+      this.max_intraday_loss < Number.POSITIVE_INFINITY &&
+      this.initialCapital > 0 &&
+      this.dayPnl < 0
+    ) {
+      const lossPct = 100 * -this.dayPnl / this.initialCapital;
+      if (lossPct >= this.max_intraday_loss) this.entries_blocked = true;
+    }
+  }
+
+  entry(
+    bar: number,
+    id: string,
+    direction: StrategyDirection | number | string,
+    qty?: number | null,
+  ): void {
+    const event: StrategyEvent = {
+      type: "entry",
+      id: String(id ?? ""),
+      direction: mapDirection(direction),
+      bar: isFiniteNumber(bar) ? bar : 0,
+    };
+    if (qty !== undefined) event.qty = qty;
+    this.events.push(event);
+  }
+
+  close(bar: number, id: string): void {
+    this.events.push({
+      type: "close",
+      id: String(id ?? ""),
+      bar: isFiniteNumber(bar) ? bar : 0,
+    });
+  }
+
+  exit(bar: number, id: string): void {
+    this.events.push({
+      type: "exit",
+      id: String(id ?? ""),
+      bar: isFiniteNumber(bar) ? bar : 0,
+    });
+  }
+
+  cancel(bar: number, id: string): void {
+    this.dropPending(String(id ?? ""));
+    this.events.push({
+      type: "cancel",
+      id: String(id ?? ""),
+      bar: isFiniteNumber(bar) ? bar : 0,
+    });
+  }
+
+  /**
+   * Always emit `close_all`. When `mark` is finite and a position is open,
+   * flatten at that price first (fills + realized PnL) without a `close` event.
+   * Also drops the pending book.
+   */
+  closeAll(bar: number, mark?: number): void {
+    const b = isFiniteNumber(bar) ? bar : 0;
+    this.dropPending();
+    if (isFiniteNumber(mark) && this.position.qty !== 0) {
+      this.flattenAt(b, "close_all", mark);
+    }
+    this.events.push({ type: "close_all", id: "", bar: b });
+  }
+
+  cancelAll(bar: number): void {
+    this.dropPending();
+    this.events.push({
+      type: "cancel_all",
+      id: "",
+      bar: isFiniteNumber(bar) ? bar : 0,
+    });
+  }
+
+  /**
+   * Place an entry. No limit/stop → market via fillEntry (needs `opts.price`).
+   * Otherwise records a pending order. Always emits an `entry` event
+   * (market path emits it through fillEntry).
+   */
+  placeEntry(
+    bar: number,
+    id: string,
+    direction: StrategyDirection | number | string,
+    qty: number,
+    opts?: PlaceEntryOpts,
+  ): void {
+    const limit = optLevel(opts?.limit);
+    const stop = optLevel(opts?.stop);
+    if (limit == null && stop == null) {
+      if (isFiniteNumber(opts?.price)) {
+        const dir = mapDirection(direction);
+        const t = isFiniteNumber(opts?.time) ? opts.time : bar;
+        this.updateEquityExtremes(opts.price);
+        if (!this.riskAllowsEntry(dir, t)) return;
+        this.fillEntry(bar, id, direction, qty, opts.price, opts);
+      } else this.entry(bar, id, direction, qty);
+      return;
+    }
+    const dir = mapDirection(direction);
+    const absQty = isFiniteNumber(qty) ? Math.abs(qty) : Number.NaN;
+    const b = isFiniteNumber(bar) ? bar : 0;
+    const oid = String(id ?? "");
+    this.entry(b, oid, dir, isFiniteNumber(absQty) ? absQty : qty);
+    if (!isFiniteNumber(absQty) || absQty === 0) return;
+    const pending: PendingOrder = { id: oid, direction: dir, qty: absQty, limit, stop, bar: b };
+    const ocaName = opts?.oca_name == null || opts.oca_name === "" ? undefined : String(opts.oca_name);
+    const ocaType = normalizeOcaType(opts?.oca_type);
+    if (ocaName !== undefined) pending.oca_name = ocaName;
+    if (ocaType !== "none") pending.oca_type = ocaType;
+    this.upsertPending(pending);
+  }
+
+  /** Alias of {@link placeEntry} (`strategy.order`). */
+  order(
+    bar: number,
+    id: string,
+    direction: StrategyDirection | number | string,
+    qty: number,
+    opts?: PlaceEntryOpts,
+  ): void {
+    this.placeEntry(bar, id, direction, qty, opts);
+  }
+
+  /**
+   * Fill pending limit/stop/stop-limit orders against this bar's OHLC.
+   * Hosts call this once per bar BEFORE the script body (Python interpret).
+   * Returns ids that filled this bar.
+   */
+  processPending(bar: number, ohlc: BarOhlc): string[] {
+    if (this.pending.length === 0 || ohlc == null) return [];
+    const hasAny =
+      isFiniteNumber(ohlc.open) ||
+      isFiniteNumber(ohlc.high) ||
+      isFiniteNumber(ohlc.low) ||
+      isFiniteNumber(ohlc.close);
+    if (!hasAny) return [];
+    const b = isFiniteNumber(bar) ? bar : 0;
+    const close = isFiniteNumber(ohlc.close)
+      ? ohlc.close
+      : isFiniteNumber(ohlc.open)
+        ? ohlc.open
+        : (isFiniteNumber(ohlc.high) ? ohlc.high : ohlc.low as number);
+    const open = isFiniteNumber(ohlc.open) ? ohlc.open : close;
+    const high = isFiniteNumber(ohlc.high) ? ohlc.high : Math.max(open, close);
+    const low = isFiniteNumber(ohlc.low) ? ohlc.low : Math.min(open, close);
+    const filled: string[] = [];
+    for (const order of this.pending.slice()) {
+      if (!this.pending.some((p) => p.id === order.id)) continue;
+      const px = triggerPrice(order, open, high, low);
+      if (px == null) continue;
+      this.dropPending(order.id);
+      const applied = this.applyEntryFill(b, order.id, order.direction, order.qty, px, false);
+      if (applied) {
+        const q = Math.abs(this.fills.at(-1)?.qty ?? order.qty);
+        this.ocaAfterFill(order, q, b);
+        this.events.push({
+          type: "fill",
+          id: order.id,
+          direction: order.direction,
+          qty: q,
+          bar: b,
+        });
+        filled.push(order.id);
+      }
+    }
+    return filled;
+  }
+
+  /** Market entry at `price`. Flat/same-dir adds qty; opposite closes then reverses. */
+  fillEntry(
+    bar: number,
+    id: string,
+    direction: StrategyDirection | number | string,
+    qty: number,
+    price: number,
+    opts?: Pick<PlaceEntryOpts, "comment" | "time">,
+  ): void {
+    this.applyEntryFill(bar, id, direction, qty, price, true, opts);
+  }
+
+  /** Flatten at `price` and record a close event. */
+  fillClose(bar: number, id: string, price: number, opts?: Pick<PlaceEntryOpts, "time">): void {
+    this.ensureSanePosition();
+    const b = isFiniteNumber(bar) ? bar : 0;
+    const oid = String(id ?? "");
+    if (this.position.qty !== 0) {
+      if (!isFiniteNumber(price)) return;
+      this.flattenAt(b, oid, price, opts?.time);
+    }
+    this.close(b, oid);
+  }
+
+  private applyEntryFill(
+    bar: number,
+    id: string,
+    direction: StrategyDirection | number | string,
+    qty: number,
+    price: number,
+    emitEntry: boolean,
+    opts?: Pick<PlaceEntryOpts, "comment" | "time">,
+  ): boolean {
+    this.ensureSanePosition();
+    if (!isFiniteNumber(qty) || qty === 0 || !isFiniteNumber(price)) return false;
+    const absQty = Math.abs(qty);
+    if (!isFiniteNumber(absQty) || absQty === 0) return false;
+    const dir = mapDirection(direction);
+    const b = isFiniteNumber(bar) ? bar : 0;
+    const oid = String(id ?? "");
+    const t = isFiniteNumber(opts?.time) ? opts.time : b;
+    this.updateEquityExtremes(price);
+    if (!this.riskAllowsEntry(dir, t)) return false;
+    const capped = this.capQtyByMaxPosition(absQty, price);
+    if (!isFiniteNumber(capped) || capped <= 0) return false;
+    const signed = dir === "long" ? capped : -capped;
+
+    if (this.position.qty !== 0 && Math.sign(this.position.qty) !== Math.sign(signed)) {
+      if (!this.flattenAt(b, oid, price, opts?.time)) return false;
+      this.close(b, oid);
+    } else if (
+      this.position.qty !== 0 &&
+      this.pyramiding !== undefined &&
+      this.sameDirAdds >= this.pyramiding
+    ) {
+      return false;
+    }
+
+    // After a reverse flatten the book is flat — this is a fresh first entry.
+    if (this.position.qty !== 0) this.sameDirAdds++;
+    else this.sameDirAdds = 0;
+    this.addPosition(b, oid, signed, price, opts);
+    this.noteFilledOrder(t);
+    this.updateEquityExtremes(price);
+    if (emitEntry) this.entry(b, oid, dir, capped);
+    return true;
+  }
+
+  private upsertPending(order: PendingOrder): void {
+    const i = this.pending.findIndex((p) => p.id === order.id);
+    if (i >= 0) this.pending[i] = order;
+    else this.pending.push(order);
+  }
+
+  private dropPending(id?: string): void {
+    if (id === undefined) {
+      this.pending.length = 0;
+      return;
+    }
+    for (let i = this.pending.length - 1; i >= 0; i--) {
+      if (this.pending[i]!.id === id) this.pending.splice(i, 1);
+    }
+  }
+
+  private addPosition(
+    bar: number,
+    id: string,
+    signedQty: number,
+    price: number,
+    opts?: Pick<PlaceEntryOpts, "comment" | "time">,
+  ): void {
+    if (!isFiniteNumber(signedQty) || signedQty === 0 || !isFiniteNumber(price)) return;
+    const oldQty = this.position.qty;
+    const oldAbs = Math.abs(oldQty);
+    const addAbs = Math.abs(signedQty);
+    const side = signedQty > 0 ? "buy" : "sell";
+    const px = this.recordFill(bar, id, side, addAbs, price);
+    if (!isFiniteNumber(px)) return;
+    const fee = this.fillFee(addAbs, px);
+    const oldAvg = this.position.avgPrice;
+    this.position.avgPrice =
+      oldAbs === 0 || !isFiniteNumber(oldAvg)
+        ? px
+        : (oldAvg * oldAbs + px * addAbs) / (oldAbs + addAbs);
+    const nextQty = oldQty + signedQty;
+    // Guard against −0 and any non-finite leftover from a bad add.
+    this.position.qty = isFiniteNumber(nextQty) && nextQty !== 0 ? nextQty : 0;
+    if (this.position.qty === 0) {
+      this.position.avgPrice = null;
+      return;
+    }
+    const dir: StrategyDirection = this.position.qty > 0 ? "long" : "short";
+    this.notePositionSize();
+    const comment = opts?.comment != null ? String(opts.comment) : undefined;
+    const entryTime = isFiniteNumber(opts?.time) ? opts.time : undefined;
+    if (oldAbs === 0 || this.openTrades.length === 0) {
+      this.openTrades.length = 0;
+      const trade: Trade = {
+        id,
+        direction: dir,
+        qty: Math.abs(this.position.qty),
+        entryBar: bar,
+        entryPrice: this.position.avgPrice ?? px,
+        commission: fee,
+      };
+      if (entryTime !== undefined) trade.entryTime = entryTime;
+      if (comment !== undefined) trade.comment = comment;
+      this.openTrades.push(trade);
+      return;
+    }
+    const t = this.openTrades[0]!;
+    t.qty = Math.abs(this.position.qty);
+    t.entryPrice = this.position.avgPrice ?? px;
+    t.commission += fee;
+  }
+
+  /**
+   * Flatten the open position at `price`. Returns false when there is nothing
+   * to close or the fill cannot be recorded without corrupting state.
+   */
+  private flattenAt(bar: number, id: string, price: number, exitTime?: number): boolean {
+    const q = this.position.qty;
+    if (q === 0 || !isFiniteNumber(q) || !isFiniteNumber(price)) return false;
+    const side = q > 0 ? "sell" : "buy";
+    const absQ = Math.abs(q);
+    const px = this.recordFill(bar, id, side, absQ, price);
+    if (!isFiniteNumber(px)) return false;
+    const avg = this.position.avgPrice;
+    const basis = isFiniteNumber(avg) ? avg : px;
+    const pnl = q * (px - basis);
+    if (isFiniteNumber(pnl)) this.realizedPnl += pnl;
+    const t = isFiniteNumber(exitTime) ? exitTime : bar;
+    this.closeOpenTrades(bar, id, px, absQ, q > 0 ? "long" : "short", basis, t);
+    this.position.qty = 0;
+    this.position.avgPrice = null;
+    this.sameDirAdds = 0;
+    this.closedCount += 1;
+    this.noteFilledOrder(t);
+    this.updateEquityExtremes(px);
+    return true;
+  }
+
+  private ensureSanePosition(): void {
+    const q = this.position.qty;
+    const avg = this.position.avgPrice;
+    if (!isFiniteNumber(q) || (q !== 0 && !isFiniteNumber(avg))) {
+      this.position.qty = 0;
+      this.position.avgPrice = null;
+      this.sameDirAdds = 0;
+      this.openTrades.length = 0;
+    }
+  }
+
+  private closeOpenTrades(
+    bar: number,
+    id: string,
+    exitPrice: number,
+    absQ: number,
+    direction: StrategyDirection,
+    basis: number,
+    exitTime?: number,
+  ): void {
+    if (this.openTrades.length === 0 && absQ > 0) {
+      this.openTrades.push({
+        id,
+        direction,
+        qty: absQ,
+        entryBar: bar,
+        entryPrice: basis,
+        commission: 0,
+      });
+    }
+    const totalQty = this.openTrades.reduce((s, t) => s + t.qty, 0);
+    const exitFeeTotal = this.fillFee(absQ, exitPrice);
+    for (const ot of this.openTrades) {
+      const share = totalQty > 0 ? ot.qty / totalQty : 1;
+      const exitComm = exitFeeTotal * share;
+      const profit = this.markProfit(ot, exitPrice) - exitComm;
+      const closed: Trade = {
+        id: ot.id,
+        direction: ot.direction,
+        qty: ot.qty,
+        entryBar: ot.entryBar,
+        entryPrice: ot.entryPrice,
+        exitBar: bar,
+        exitPrice,
+        profit,
+        commission: ot.commission + exitComm,
+      };
+      if (ot.entryTime !== undefined) closed.entryTime = ot.entryTime;
+      if (ot.comment !== undefined) closed.comment = ot.comment;
+      if (ot.max_runup !== undefined) closed.max_runup = ot.max_runup;
+      if (ot.max_drawdown !== undefined) closed.max_drawdown = ot.max_drawdown;
+      this.closedTrades.push(closed);
+      this.noteClosedProfit(profit);
+      this.noteClosedTradeDay(isFiniteNumber(exitTime) ? exitTime : bar, profit);
+    }
+    this.openTrades.length = 0;
+  }
+
+  private noteClosedProfit(profit: number): void {
+    if (!isFiniteNumber(profit)) return;
+    if (profit > 0) {
+      this.grossprofit += profit;
+      this.wintrades += 1;
+    } else if (profit < 0) {
+      this.grossloss += -profit;
+      this.losstrades += 1;
+    } else {
+      this.eventrades += 1;
+    }
+  }
+
+  private markProfit(t: Trade, mark: number): number {
+    const signed = t.direction === "long" ? 1 : -1;
+    return signed * (mark - t.entryPrice) * t.qty - t.commission;
+  }
+
+  private fillFee(qty: number, price: number): number {
+    const rate = isFiniteNumber(this.commission) ? this.commission : 0;
+    const fee = Math.abs(qty) * Math.abs(price) * rate;
+    return isFiniteNumber(fee) ? fee : 0;
+  }
+
+  private pickTrade(list: Trade[], i: unknown): Trade | null {
+    if (!isFiniteNumber(i) || !Number.isInteger(i) || i < 0 || i >= list.length) return null;
+    return list[i] ?? null;
+  }
+
+  private riskAllowsEntry(direction: StrategyDirection, time: number): boolean {
+    const allow = (this.allow_entry_in || "all").toLowerCase().replace(/strategy\./g, "");
+    if (allow === "long" && direction !== "long") return false;
+    if (allow === "short" && direction !== "short") return false;
+    if (this.entries_blocked) return false;
+    if (this.max_drawdown_risk != null && this.maxDrawdownAbs >= this.max_drawdown_risk) {
+      this.entries_blocked = true;
+      return false;
+    }
+    if (
+      this.max_drawdown_risk_percent != null &&
+      this.maxDdPercent >= this.max_drawdown_risk_percent
+    ) {
+      this.entries_blocked = true;
+      return false;
+    }
+    if (this.max_cons_loss_days != null && this.consecutive_loss_days >= this.max_cons_loss_days) {
+      this.entries_blocked = true;
+      return false;
+    }
+    if (
+      Number.isFinite(this.max_intraday_loss) &&
+      this.max_intraday_loss < Number.POSITIVE_INFINITY &&
+      this.initialCapital > 0 &&
+      this.dayPnl < 0
+    ) {
+      const lossPct = 100 * -this.dayPnl / this.initialCapital;
+      if (lossPct >= this.max_intraday_loss) {
+        this.entries_blocked = true;
+        return false;
+      }
+    }
+    if (this.max_intraday_filled_orders != null) {
+      this.rollFillDay(time);
+      if (this.dayFilledOrders >= this.max_intraday_filled_orders) return false;
+    }
+    return true;
+  }
+
+  private capQtyByMaxPosition(qty: number, fillPrice: number): number {
+    const pct = this.max_position_size_percent;
+    if (pct == null || pct <= 0 || !isFiniteNumber(fillPrice) || fillPrice <= 0) return qty;
+    const eq = this.equity(fillPrice);
+    const maxQty = (eq * (pct / 100)) / fillPrice;
+    if (!isFiniteNumber(maxQty) || maxQty < 0) return 0;
+    return Math.min(qty, maxQty);
+  }
+
+  private updateEquityExtremes(mark: number): void {
+    this.equity(mark);
+  }
+
+  /** Peak/trough and max drawdown / runup from an equity sample (Python `_track_equity_curve`). */
+  private trackEquityCurve(eq: number): void {
+    if (!isFiniteNumber(eq)) return;
+    if (eq > this.equityPeak) this.equityPeak = eq;
+    if (eq < this.equityTrough) this.equityTrough = eq;
+    const dd = this.equityPeak - eq;
+    if (dd > this.maxDrawdownAbs) {
+      this.maxDrawdownAbs = dd;
+      if (this.equityPeak > 0) this.maxDdPercent = (100 * dd) / this.equityPeak;
+    }
+    const ru = eq - this.equityTrough;
+    if (ru > this.maxRunupAbs) {
+      this.maxRunupAbs = ru;
+      if (this.equityTrough > 0) this.maxRuPercent = (100 * ru) / this.equityTrough;
+    }
+  }
+
+  /** `100 * amount / initialCapital`; 0 if capital ≤ 0 (Python `_pct_of_initial`). */
+  private pctOfInitial(amount: number): number {
+    const cap = this.initialCapital;
+    if (!isFiniteNumber(cap) || cap <= 0 || !isFiniteNumber(amount)) return 0;
+    return (100 * amount) / cap;
+  }
+
+  /** Update max contracts held after a fill (Python `note_position_size`). */
+  private notePositionSize(): void {
+    const size = Math.abs(this.position.qty);
+    if (!isFiniteNumber(size) || size === 0) return;
+    if (size > this.maxHeldAll) this.maxHeldAll = size;
+    if (this.position.qty > 0 && size > this.maxHeldLong) this.maxHeldLong = size;
+    if (this.position.qty < 0 && size > this.maxHeldShort) this.maxHeldShort = size;
+  }
+
+  private rollFillDay(ts: number): void {
+    const day = dayBucket(isFiniteNumber(ts) ? ts : 0);
+    if (this.fillsDay == null || day !== this.fillsDay) {
+      this.fillsDay = day;
+      this.dayFilledOrders = 0;
+    }
+  }
+
+  private noteFilledOrder(ts: number): void {
+    this.rollFillDay(ts);
+    this.dayFilledOrders += 1;
+  }
+
+  private ocaAfterFill(filled: PendingOrder, fillQty: number, bar: number): void {
+    const name = filled.oca_name;
+    const otype = filled.oca_type ?? "none";
+    if (!name || otype === "none") return;
+    for (const other of this.pending.slice()) {
+      if (other.id === filled.id || other.oca_name !== name) continue;
+      if (otype === "cancel") {
+        this.dropPending(other.id);
+        this.events.push({ type: "cancel", id: other.id, bar });
+      } else if (otype === "reduce") {
+        other.qty = Math.max(0, other.qty - fillQty);
+        if (other.qty <= 1e-12) {
+          this.dropPending(other.id);
+          this.events.push({ type: "cancel", id: other.id, bar });
+        }
+      }
+    }
+  }
+
+  /** Long/buy pays +slip; short/sell receives −slip. Records actual fill price. */
+  private recordFill(
+    bar: number,
+    id: string,
+    side: "buy" | "sell",
+    qty: number,
+    price: number,
+  ): number {
+    const slip = isFiniteNumber(this.slippage) ? this.slippage : 0;
+    const px = side === "buy" ? price + slip : price - slip;
+    if (!isFiniteNumber(px) || !isFiniteNumber(qty) || qty === 0) return Number.NaN;
+    this.fills.push({ bar, id, side, qty, price: px });
+    const rate = isFiniteNumber(this.commission) ? this.commission : 0;
+    const fee = Math.abs(qty) * Math.abs(px) * rate;
+    if (isFiniteNumber(fee)) this.commissionPaid += fee;
+    return px;
+  }
+}