openalgo-script 0.2.0 → 0.5.0

package/src/core/backtest/resting.ts

@@ -0,0 +1,125 @@
+/**
+ * One resting order against one bar: did it trade, and at what price.
+ *
+ * **A bar is four prices and no path.** Whether the high came before the low is
+ * not in the data, so every rule here is one that does not need to know, and
+ * the places where knowing would matter are decided against the strategy rather
+ * than guessed in its favour. That is the whole discipline of this file: a
+ * backtest that is generous about fills is a backtest that reports money the
+ * market never offered.
+ *
+ * Three rules, each with the case it exists for:
+ *
+ * - **Touched is not traded through.** A limit resting exactly at the low of a
+ *   bar may or may not have been filled: the print happened, somebody was
+ *   filled at that price, and whether it was this order depends on a queue no
+ *   bar records. The default is that it was not (`limitNeedsThrough`), and a
+ *   host that has decided otherwise for its own market says so in the policy.
+ * - **A gap fills at the open, not at the level.** A stop triggered by a bar
+ *   that opened beyond it was not filled at its trigger, and a backtest that
+ *   says it was is reporting the one price that was never available. The open
+ *   is the first price there was.
+ * - **A limit fills at its own price or better, and never worse.** Where the
+ *   bar opened already through a limit, the open is the better price and the
+ *   fill is there; a limit is never worsened by slippage, because a limit that
+ *   is worsened is not a limit.
+ *
+ * A stop limit is both, in one bar and in that order: the trigger has to be
+ * reached and the limit has to be traded through, and where only the trigger is
+ * reached the order becomes a resting limit and waits.
+ */
+import type { OrderSide, OrderType } from '../engine/index.js';
+import type { FillPolicy } from './settings.js';
+import type { RecordedBar } from './record.js';
+
+/** A resting order, as the venue holds one. */
+export interface RestingOrder {
+  readonly side: OrderSide;
+  readonly type: OrderType;
+  /** The price a limit may not be worse than, absent on a plain stop. */
+  readonly limit: number | null;
+  /** The price a stop is triggered at, absent on a plain limit. */
+  readonly trigger: number | null;
+}
+
+/** What one bar did to one resting order. */
+export type RestOutcome =
+  | { readonly filled: false; readonly triggered: boolean }
+  | {
+      readonly filled: true;
+      readonly price: number;
+      /** Whether the price is the bar's open, which is a gap through the level. */
+      readonly atOpen: boolean;
+      /** Whether slippage applies, which a limit never takes. */
+      readonly slips: boolean;
+    };
+
+const NOTHING: RestOutcome = { filled: false, triggered: false };
+
+/**
+ * One order against one bar.
+ *
+ * A bar missing any of the four prices decides nothing: an incomplete bar is
+ * not evidence that a level was reached and it is not evidence that it was not.
+ */
+export function testResting(
+  order: RestingOrder,
+  bar: RecordedBar,
+  policy: FillPolicy,
+): RestOutcome {
+  const open = bar.open;
+  const high = bar.high;
+  const low = bar.low;
+  if (open === null || high === null || low === null || bar.close === null) return NOTHING;
+
+  if (order.type === 'limit') return limitAgainst(order, open, high, low, policy);
+
+  const trigger = order.trigger;
+  if (trigger === null) return NOTHING;
+  const reached = order.side === 'buy' ? high >= trigger : low <= trigger;
+  if (!reached) return NOTHING;
+
+  if (order.type === 'stop') {
+    const gapped = order.side === 'buy' ? open >= trigger : open <= trigger;
+    const price = gapped && policy.stopFillsAtOpenOnGap ? open : trigger;
+    return { filled: true, price, atOpen: gapped && policy.stopFillsAtOpenOnGap, slips: true };
+  }
+
+  // A stop limit that triggered is a limit for the rest of this bar. Where the
+  // limit is not traded through it keeps resting, and the caller is told the
+  // trigger was reached so that the order rests as a limit from here on.
+  const asLimit = limitAgainst(order, open, high, low, policy);
+  return asLimit.filled ? asLimit : { filled: false, triggered: true };
+}
+
+/**
+ * A limit against one bar.
+ *
+ * `limitNeedsThrough` is the difference between a strict comparison and a loose
+ * one, and it is the only knob in this file that changes a fill into no fill
+ * rather than one price into another.
+ */
+function limitAgainst(
+  order: RestingOrder,
+  open: number,
+  high: number,
+  low: number,
+  policy: FillPolicy,
+): RestOutcome {
+  const limit = order.limit;
+  if (limit === null) return NOTHING;
+
+  if (order.side === 'buy') {
+    const traded = policy.limitNeedsThrough ? low < limit : low <= limit;
+    if (!traded) return NOTHING;
+    // The open already below the limit is the better price, and it is the first
+    // price the bar had.
+    const gapped = open < limit;
+    return { filled: true, price: gapped ? open : limit, atOpen: gapped, slips: false };
+  }
+
+  const traded = policy.limitNeedsThrough ? high > limit : high >= limit;
+  if (!traded) return NOTHING;
+  const gapped = open > limit;
+  return { filled: true, price: gapped ? open : limit, atOpen: gapped, slips: false };
+}

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;
+}