openalgo-script 0.1.0-alpha.1 → 0.4.0

package/src/core/backtest/settings.ts

@@ -0,0 +1,280 @@
+/**
+ * What the host chose, which is the half of a run that is not the program.
+ *
+ * **The dividing rule, and everything in this module follows from it: the
+ * record stores what the host chose, and what the program states is stored
+ * once, as the program.** So there is no capital here, no slippage and no
+ * commission: the declaration states those and the declaration is in the
+ * record. A charge schedule the host supplied is here because the host supplied
+ * it; a schedule derived from the declaration is derived again on replay.
+ *
+ * **The fill policy carries its own version** precisely so that a record made
+ * before the policy changed replays as it ran, rather than being quietly re-run
+ * under today's rules and reported as the same study. A policy that could not
+ * say which revision it was would make every stored run a claim about whichever
+ * engine happened to read it last.
+ *
+ * `fillOn` is deliberately not here: it is the declaration's, and the
+ * declaration is the program.
+ *
+ * Two refusals live in this module when the behaviour lands. A setting the run
+ * cannot be carried out under is OS6021, and a supplied schedule beside a
+ * declared commission that is not the default is OS6023, because two cost
+ * models stated at once is a number nobody can explain afterwards.
+ */
+import { scheduleFromDeclaration, scheduleProblem } from '../accounting/index.js';
+import type { ChargeSchedule, Contract } from '../accounting/index.js';
+import { diagnosticFor } from '../diagnostics/index.js';
+import type { Diagnostic } from '../diagnostics/index.js';
+import type { Value } from '../engine/index.js';
+import type { RunDeclaration } from './declaration.js';
+
+/**
+ * Where a refusal about a setting points.
+ *
+ * Nowhere in the script. A run setting is what the host stated before the first
+ * bar, and a caret under a line of the strategy would blame the one party that
+ * did not choose it. The money layer states the same position for the same
+ * reason.
+ */
+const NO_POSITION: Diagnostic['span'] = { offset: 0, length: 0, line: 0, column: 0 };
+
+/** The window of the supplied bars a report is about. */
+export interface DateRange {
+  /** Inclusive, UTC ms; null means the first bar supplied. */
+  readonly from: number | null;
+  /** Inclusive; null means the last. */
+  readonly to: number | null;
+}
+
+/** How a resting order is decided against a bar, and who holds a level. */
+export interface FillPolicy {
+  /** A limit fills only when the bar traded through it. */
+  readonly limitNeedsThrough: boolean;
+  readonly stopFillsAtOpenOnGap: boolean;
+  /** Who holds a bracket's levels; 'destination' until 17.9 exists. */
+  readonly levels: 'destination' | 'engine';
+  /** This policy's own revision, so an old record replays as it ran. */
+  readonly version: number;
+}
+
+/**
+ * How closely two numbers have to agree, and why they are allowed not to.
+ *
+ * Exact by default. A bound that is not zero without a reason beside it is
+ * refused, because a tolerance with no reason is a failed comparison somebody
+ * turned off. The reason a tolerance exists at all is a second implementation,
+ * never this one's own re-run: a rerun of the same record on this engine is
+ * bit-identical or it is a defect.
+ */
+export interface Tolerance {
+  readonly abs: number;
+  readonly rel: number;
+  /** Required whenever either bound is non-zero. */
+  readonly reason: string | null;
+}
+
+/** Everything the host decided about one run. */
+export interface BacktestSettings {
+  readonly range: DateRange;
+  readonly contract: Contract;
+  /** Null derives one from the declaration. */
+  readonly costs: ChargeSchedule | null;
+  readonly fill: FillPolicy;
+  readonly inputs: Readonly<Record<string, Value>>;
+  readonly now: number | null;
+  readonly tolerance: Tolerance;
+}
+
+/**
+ * How a resting order is decided when the host states nothing.
+ *
+ * Conservative on both counts, because a backtest that is wrong is wrong in the
+ * strategy's favour by default: a limit is only filled where the bar traded
+ * through it, so an order resting exactly at the extreme of a bar is not
+ * credited with a fill nobody can prove happened, and a stop that gapped is
+ * filled at the open rather than at its trigger, which is the price a trader
+ * would actually have been given.
+ *
+ * `levels` is `destination` because there is nowhere else for it to be: a
+ * bracket reaches a destination as a protective instruction attached to a tag
+ * and the engine holds no level of its own. The other spelling exists so that a
+ * record made today says which of the two it ran under.
+ *
+ * `version` is this policy's own revision. It travels in the record so that a
+ * run stored before the rules changed replays as it ran rather than being
+ * quietly re-decided under today's.
+ */
+export const DEFAULT_FILL: FillPolicy = {
+  limitNeedsThrough: true,
+  stopFillsAtOpenOnGap: true,
+  levels: 'destination',
+  version: 1,
+};
+
+/** Exact, which is what a comparison is until somebody writes down why it is not. */
+export const EXACT: Tolerance = { abs: 0, rel: 0, reason: null };
+
+/** The whole window of whatever bars were supplied. */
+export const WHOLE_RANGE: DateRange = { from: null, to: null };
+
+/**
+ * The settings a run takes when the host states only the contract.
+ *
+ * Every default here is the absence of a choice rather than a choice made on
+ * the host's behalf: the whole of the bars supplied, no schedule, exact
+ * comparison, no inputs overridden and no clock. A host that wants any of it
+ * different says so, and what it said is what the record stores.
+ *
+ * **The contract is the first argument and cannot be in the second.** The
+ * second was `Partial<BacktestSettings>`, which names a `contract` field that
+ * this function then ignored in favour of the positional one: a caller passing
+ * a contract there silently got the other, and a test written that way passed
+ * while proving nothing. Excluding the field makes it a compiler error at the
+ * call rather than a wrong answer at the end of a run.
+ */
+export function settingsFor(
+  contract: Contract,
+  chosen: Omit<Partial<BacktestSettings>, 'contract'> = {},
+): BacktestSettings {
+  return {
+    range: chosen.range ?? WHOLE_RANGE,
+    contract,
+    costs: chosen.costs ?? null,
+    fill: chosen.fill ?? DEFAULT_FILL,
+    inputs: chosen.inputs ?? {},
+    now: chosen.now ?? null,
+    tolerance: chosen.tolerance ?? EXACT,
+  };
+}
+
+/**
+ * What a run cannot be carried out under, before its first bar.
+ *
+ * Four questions, and every one of them is a figure nobody could explain
+ * afterwards rather than a tidiness rule:
+ *
+ * - **Two cost models at once**, OS6023. A supplied schedule and a declared
+ *   commission describe the same money. Applied together they charge it twice
+ *   and applied one at a time they charge whichever an engine preferred, which
+ *   is a rule nobody wrote down.
+ * - **A schedule that cannot be evaluated**, OS6021, which `scheduleProblem`
+ *   decides, because the schedule is the money layer's and the rule for it is
+ *   written once, there. **Whichever schedule the run will be charged under**,
+ *   which is the declaration's own when the host supplied none: asking only
+ *   about a supplied one left every refusal in the money layer unreachable on
+ *   the path almost every run takes.
+ * - **A quantity in a unit this destination cannot fill**, OS6021. A backtest
+ *   fills in units and works out no running equity, so a quantity in cash or in
+ *   a percentage of equity is one it cannot convert, and a lot needs a lot size
+ *   the instrument may not state.
+ * - **A tolerance with a bound and no reason**, OS6021. A comparison allowed to
+ *   pass by a margin nobody justified is a failed comparison somebody switched
+ *   off, and the reason a tolerance exists at all is a second implementation:
+ *   a rerun of one record on this engine is bit-identical or it is a defect.
+ *
+ * Nothing has been computed when this is asked, so a refusal costs one run
+ * rather than a report a reader has to be told to distrust.
+ */
+export function checkSettings(
+  settings: BacktestSettings,
+  declared: RunDeclaration,
+): Diagnostic | null {
+  if (settings.costs !== null && declared.isStrategy && declared.commission !== 0) {
+    return diagnosticFor('OS6023', NO_POSITION, {
+      commission: declared.commission,
+      commissionType: declared.commissionType,
+    });
+  }
+
+  // Whichever schedule the run will actually be charged under, which is the
+  // declaration's own when the host supplied none. Guarding this on
+  // `settings.costs !== null` left every refusal in the money layer unreachable
+  // on the default path: a declared commission of -5 was charged as a credit
+  // and turned a loss into a gain, with nothing raised anywhere.
+  const schedule = settings.costs ?? scheduleForDeclaration(declared, settings.contract);
+  if (schedule !== null) {
+    const problem = scheduleProblem(schedule, settings.contract);
+    if (problem !== null) return problem;
+  }
+
+  const sizing = sizingProblem(declared, settings.contract);
+  if (sizing !== null) return sizing;
+
+  return toleranceProblem(settings.tolerance);
+}
+
+/** The schedule a run with no host schedule is charged under, or none. */
+function scheduleForDeclaration(
+  declared: RunDeclaration,
+  contract: Contract,
+): ChargeSchedule | null {
+  if (!declared.isStrategy) return null;
+  return scheduleFromDeclaration(
+    declared.commission,
+    declared.commissionType,
+    declared.slippage,
+    contract.currency,
+    contract.digits,
+  );
+}
+
+/**
+ * Whether this destination can fill the unit the strategy sizes in.
+ *
+ * **A quantity is stated in the declaration's own unit and the destination is
+ * the party that converts it** (`host-interface.md` 7.1). This one filled every
+ * order at the number the script wrote, whatever unit it was written in, so a
+ * strategy sizing in lots on a lot of sixty five traded one sixty fifth of what
+ * it asked for and every money figure in the record was out by that factor,
+ * with nothing refused and nothing said. A record like that is worse than a
+ * refused run twice over: somebody trades on the number, and a second engine is
+ * handed it as a conformance case and taught the wrong quantity.
+ *
+ * So: units and lots are converted, and the two that need a running equity this
+ * destination does not hold are refused by name. A refusal costs one run. The
+ * alternative cost a whole report that looked right.
+ */
+function sizingProblem(declared: RunDeclaration, contract: Contract): Diagnostic | null {
+  if (!declared.isStrategy) return null;
+  if (declared.qtyType === 'units' || declared.qtyType === '') return null;
+  if (declared.qtyType === 'lots') {
+    if (contract.lotSize !== null && contract.lotSize > 0) return null;
+    return diagnosticFor('OS6021', NO_POSITION, {
+      setting: 'A quantity stated in lots',
+      problem:
+        'this instrument states no lot size, so there is nothing to convert a lot into',
+    });
+  }
+  return diagnosticFor('OS6021', NO_POSITION, {
+    setting: 'A quantity stated in ' + declared.qtyType,
+    problem:
+      'a backtest fills in units and works out no running equity to size against, so it ' +
+      'cannot convert one. State the quantity in units or in lots',
+  });
+}
+
+/**
+ * A bound, and the reason it is there.
+ *
+ * Both bounds are checked rather than the first one found, because a tolerance
+ * carrying two bounds and one reason is two allowances and one justification.
+ */
+function toleranceProblem(tolerance: Tolerance): Diagnostic | null {
+  const stated = tolerance.reason !== null && tolerance.reason.trim() !== '';
+  const bounded = tolerance.abs !== 0 || tolerance.rel !== 0;
+  if (bounded && !stated) {
+    return diagnosticFor('OS6021', NO_POSITION, {
+      setting: 'The comparison tolerance',
+      problem: 'a bound of ' + String(tolerance.abs) + ' absolute and ' + String(tolerance.rel) +
+        ' relative is stated with no reason beside it',
+    });
+  }
+  if (tolerance.abs < 0 || tolerance.rel < 0) {
+    return diagnosticFor('OS6021', NO_POSITION, {
+      setting: 'The comparison tolerance',
+      problem: 'a bound below zero admits nothing and refuses what is exact',
+    });
+  }
+  return null;
+}

package/src/core/backtest/simulate.ts

@@ -0,0 +1,304 @@
+/**
+ * The destination a backtest runs against: intents in, frames out.
+ *
+ * **This is a host, not part of the engine**, and the division is the one thing
+ * to keep straight while reading it. `stdlib.md` 17.1 puts slippage and
+ * commission on the destination: the engine folds the price it is told and
+ * never adjusts one, so the price worsening below is a venue giving a worse
+ * fill, which is what a venue does, and not an engine moving a number, which is
+ * what the invariant forbids. Everything here could be a broker.
+ *
+ * **A frame is cumulative and reaches the engine between bars.** Every frame
+ * restates the whole life of one order from its beginning, so a repeat costs
+ * nothing, and none of them is handed over during an execution: they are
+ * answered here and collected at the boundary, which is where
+ * `host-interface.md` 7.4 puts the intake.
+ *
+ * **When a fill is known is not when it happened.** A market order decided at
+ * the close of a bar and filled at the next bar's open is known at that open,
+ * so its frame is delivered before that bar executes and the strategy holds the
+ * position for the whole of it. An order that rested and traded somewhere
+ * inside a bar is only known to have traded once that bar is complete, so its
+ * frame is delivered before the bar after it. Both are the truthful reading of
+ * what a venue could have told anybody at the time, and the difference between
+ * them is why they are not folded together.
+ *
+ * **A bracket is answered with nothing at all**, exactly as a venue with no
+ * order to report would answer. A bracket reaches a destination as a protective
+ * instruction attached to a tag and the engine appends no row for it, so there
+ * is nothing for a frame to be about: a fill reported against one would name an
+ * intent no row holds and the fold would refuse it. The row a bracket wants is
+ * decision 55 and it is not in this release, so a stop cannot fill here and a
+ * page that says it can is ahead of the engine.
+ */
+import type { Contract } from '../accounting/index.js';
+import type { OrderFrame, OrderIntent, OrderSide, RoutedEffect } from '../engine/index.js';
+import type { RecordedBar } from './record.js';
+import { testResting } from './resting.js';
+import type { RestingOrder } from './resting.js';
+import type { FillPolicy } from './settings.js';
+
+/** What the venue prices against and how it decides a fill. */
+export interface SimulatorOptions {
+  readonly bars: readonly RecordedBar[];
+  readonly contract: Contract;
+  readonly fill: FillPolicy;
+  /** Adverse always, in ticks, applied to a market fill and to a stop. */
+  readonly slippageTicks: number;
+  /** The declaration's own fill rule: where a market order is priced. */
+  readonly fillOn: string;
+  /**
+   * The unit the declaration's quantity is stated in, `language.md` 13.3.
+   *
+   * Here because converting it is the destination's job and a fill is counted
+   * in units. Only the units this destination can arrive at reach it: the rest
+   * are refused before the first bar by `checkSettings`.
+   */
+  readonly qtyType: string;
+}
+
+/** One order this venue holds, and what it has said about it. */
+interface Order {
+  readonly intent: OrderIntent;
+  readonly ref: string;
+  readonly placedOn: number;
+  /** Absent on a market order, which rests on nothing. */
+  readonly rest: RestingOrder | null;
+  filledQty: number;
+  live: boolean;
+  /** Whether a stop limit has reached its trigger and is now a limit. */
+  triggered: boolean;
+}
+
+/** `language.md` 13.3: a market order priced at the close of its own bar. */
+const AT_CLOSE = 'close';
+
+/**
+ * A venue, for one run.
+ *
+ * It holds the orders it was handed and nothing else: no position, no money and
+ * no view of what the strategy is doing, because a destination has none of
+ * those about somebody else's strategy.
+ */
+export class Simulator {
+  private readonly options: SimulatorOptions;
+  private readonly orders: Order[] = [];
+  /** The intents handed over, in the order they were, whatever became of them. */
+  readonly intents: OrderIntent[] = [];
+  /** Brackets, held so that a run can say how many it was handed and answered. */
+  readonly brackets: OrderIntent[] = [];
+  private queued: Order[] = [];
+  private answered: OrderFrame[] = [];
+  private refs = 0;
+  private seq = 0;
+
+  constructor(options: SimulatorOptions) {
+    this.options = options;
+  }
+
+  /** Step 9: what the strategy decided reaches the venue. */
+  route(effect: RoutedEffect, barIndex: number): void {
+    for (const intent of effect.intents) {
+      this.intents.push(intent);
+      if (intent.kind === 'bracket') {
+        this.brackets.push(intent);
+        continue;
+      }
+      if (intent.kind === 'cancel') {
+        this.withdraw(intent, barIndex);
+        continue;
+      }
+      this.accept(intent, barIndex);
+    }
+  }
+
+  /**
+   * The frames a boundary hands over: everything this venue can say now.
+   *
+   * The orders that were already resting are decided against this bar first and
+   * the orders this bar sent are answered after, which is the order the venue
+   * learned of them in.
+   */
+  framesFor(barIndex: number): readonly OrderFrame[] {
+    const bar = this.options.bars[barIndex];
+    if (bar !== undefined) {
+      for (const order of this.orders) {
+        if (!order.live || order.rest === null || order.placedOn >= barIndex) continue;
+        this.decide(order, bar, barIndex);
+      }
+    }
+
+    const sent = this.queued;
+    this.queued = [];
+    for (const order of sent) this.open(order, barIndex);
+
+    const out = this.answered;
+    this.answered = [];
+    return out;
+  }
+
+  /** How many orders this venue is still holding, which a run reports. */
+  get working(): number {
+    return this.orders.filter((order) => order.live).length;
+  }
+
+  /** An order the strategy sent, which this venue now holds. */
+  private accept(intent: OrderIntent, barIndex: number): void {
+    this.refs += 1;
+    const order: Order = {
+      intent,
+      ref: refOf(this.refs),
+      placedOn: barIndex,
+      rest: restingFor(intent),
+      filledQty: 0,
+      live: true,
+      triggered: false,
+    };
+    this.orders.push(order);
+    this.queued.push(order);
+  }
+
+  /**
+   * A cancellation, which is about the orders a tag names and not about itself.
+   *
+   * Every live order carrying the tag is withdrawn and answered, which is what
+   * releases the position they were claiming, and the cancellation is then
+   * answered as an order of its own, because the engine appended a row for it
+   * and a row nothing ever answers stays at `placed` for the life of the run.
+   */
+  private withdraw(intent: OrderIntent, barIndex: number): void {
+    for (const order of this.orders) {
+      if (!order.live || order.intent.tag !== intent.tag) continue;
+      order.live = false;
+      this.say(order.intent, order.ref, 'cancelled', order.filledQty, null, barIndex);
+    }
+    // The cancellation is confirmed after what it withdrew, which is the order
+    // a venue does it in: the request is answered once it has been carried out.
+    this.refs += 1;
+    this.say(intent, refOf(this.refs), 'cancelled', 0, null, barIndex);
+  }
+
+  /**
+   * The first thing a venue says about an order it has taken.
+   *
+   * A working frame before any fill, because 7.4 asks for a frame on every
+   * change of status and a script waiting for a working order to clear waits
+   * blind without one. A market order is then filled in the same breath where
+   * the declaration prices it at this bar's close, and at the next bar's open
+   * where it does not.
+   */
+  private open(order: Order, barIndex: number): void {
+    this.say(order.intent, order.ref, 'working', 0, null, barIndex);
+    if (order.rest !== null) return;
+
+    const atClose = this.options.fillOn === AT_CLOSE;
+    const bar = this.options.bars[atClose ? barIndex : barIndex + 1];
+    const price = atClose ? (bar?.close ?? null) : (bar?.open ?? null);
+    // A market order sent on the last bar of a run and priced at the next open
+    // has no next open. It stays working and is reported as an order the run
+    // ended holding, which is what it is.
+    if (price === null) return;
+    this.complete(order, this.worsen(price, order.intent.side), barIndex);
+  }
+
+  /** One resting order against one bar. */
+  private decide(order: Order, bar: RecordedBar, barIndex: number): void {
+    const rest = order.rest;
+    if (rest === null) return;
+    const outcome = testResting(order.triggered ? asLimit(rest) : rest, bar, this.options.fill);
+    if (!outcome.filled) {
+      if (outcome.triggered) order.triggered = true;
+      return;
+    }
+    const price = outcome.slips ? this.worsen(outcome.price, order.intent.side) : outcome.price;
+    this.complete(order, price, barIndex);
+  }
+
+  /**
+   * The whole of an order, filled at one price.
+   *
+   * **The quantity is converted into units here, because that is what a fill
+   * is counted in and what every money figure is folded over.** A quantity
+   * travels in the declaration's own unit (`host-interface.md` 7.1) and the
+   * destination is the party that converts it. This filled the number verbatim,
+   * so a strategy sizing in lots on a lot of sixty five traded one sixty fifth
+   * of what it asked for and the whole report was out by that factor. The units
+   * this destination cannot arrive at are refused before the first bar rather
+   * than guessed at here, so by this point the unit is one of two.
+   */
+  private complete(order: Order, price: number, barIndex: number): void {
+    const stated = order.intent.qty ?? 0;
+    const lot = this.options.contract.lotSize;
+    const qty =
+      this.options.qtyType === 'lots' && lot !== null && lot > 0 ? stated * lot : stated;
+    order.filledQty = qty;
+    order.live = false;
+    this.say(order.intent, order.ref, 'filled', qty, price, barIndex);
+  }
+
+  /**
+   * A price worsened by the slippage the run was carried out under.
+   *
+   * **Adverse always: a buy pays more and a sell receives less.** The sign is
+   * taken as written rather than as a magnitude, because a slippage below zero
+   * is refused before the first bar and taking its magnitude here would be this
+   * function quietly covering for a hole in that refusal. It went uncovered for
+   * a while: `scheduleProblem` has always refused a negative rate, and
+   * `checkSettings` asked it only about a schedule the host supplied, so a
+   * declaration stating a slippage of minus one improved both sides of every
+   * fill and the backtest paid the strategy to trade.
+   *
+   * A slippage in ticks with no tick size to measure a tick in charges nothing.
+   * The comment here once said that was refused before the first bar and it was
+   * not; it still is not, because an instrument with no tick is a fact a host
+   * may legitimately not hold, and a run that charges no slippage is a study
+   * before slippage rather than a wrong answer. What has changed is that this
+   * says so instead of claiming a refusal that never existed.
+   */
+  private worsen(price: number, side: OrderSide | null): number {
+    const tick = this.options.contract.tickSize;
+    if (tick === null || this.options.slippageTicks === 0) return price;
+    const move = this.options.slippageTicks * tick;
+    return side === 'sell' ? price - move : price + move;
+  }
+
+  /** One frame, cumulative, in the order this venue spoke. */
+  private say(
+    intent: OrderIntent,
+    ref: string,
+    status: string,
+    filledQty: number,
+    avgFillPrice: number | null,
+    barIndex: number,
+  ): void {
+    this.seq += 1;
+    this.answered.push({
+      intentId: intent.intentId,
+      status,
+      filledQty,
+      avgFillPrice,
+      orderRef: ref,
+      sentInstrument: intent.instrument,
+      sentProduct: intent.product,
+      time: this.options.bars[barIndex]?.time ?? null,
+      text: '',
+      seq: this.seq,
+    });
+  }
+}
+
+/** This venue's own reference for an order, which the engine records and never parses. */
+function refOf(count: number): string {
+  return 'ORD-' + String(count);
+}
+
+/** The resting order an intent is, or nothing where it is a market order. */
+function restingFor(intent: OrderIntent): RestingOrder | null {
+  if (intent.type === null || intent.type === 'market' || intent.side === null) return null;
+  return { side: intent.side, type: intent.type, limit: intent.limit, trigger: intent.trigger };
+}
+
+/** A stop limit that has triggered, which is a limit from that moment on. */
+function asLimit(rest: RestingOrder): RestingOrder {
+  return { side: rest.side, type: 'limit', limit: rest.limit, trigger: null };
+}