openalgo-script 0.2.0 → 0.4.0

package/src/core/backtest/record.ts

@@ -0,0 +1,341 @@
+/**
+ * The run record: a whole run as a plain JSON document.
+ *
+ * **The record is the conformance case.** That is the one decision this module
+ * exists to hold, and everything in it follows from it: no object reference, no
+ * function, no dependence on this implementation's internals, and nothing that
+ * only this engine can read. A record carries the script revision, the compiled
+ * program, the bars, the settings the host chose, the frames the destination
+ * answered in delivery order, the fills the engine folded in fold order, the
+ * ledger the run ended with, the diagnostics and the report.
+ *
+ * **The bars are inline or referenced, and both carry the same hash.** Inline is
+ * the conformance form, because a case has to hold every byte of its own input.
+ * Referenced is the operational form, because the smallest deployment has a one
+ * megabyte request body and nothing that grows with history may travel in one.
+ * A replay whose bars do not hash to the record's hash is OS6022 rather than a
+ * silently different study.
+ *
+ * **The frames name an intent by ordinal and never by an engine's own id**,
+ * because a case cannot know what id another engine minted. The same reason the
+ * ledger rows here are flat words rather than this engine's own types.
+ *
+ * The record is written through the existing canonical encoding, so there is one
+ * canonical writer in the repository and key order and number form are fixed for
+ * everybody.
+ */
+import type { RecordedFill, Report } from '../accounting/index.js';
+import type { Diagnostic } from '../diagnostics/index.js';
+import { canonicalise, programHash, sha256 } from '../emit/index.js';
+import type { CompiledProgram, SourceStamp } from '../emit/index.js';
+import type { LedgerRow } from '../engine/index.js';
+import { VERSION } from '../version/index.js';
+import type { BacktestSettings } from './settings.js';
+
+/** One bar as a record holds it. */
+export interface RecordedBar {
+  readonly time: number | null;
+  readonly open: number | null;
+  readonly high: number | null;
+  readonly low: number | null;
+  readonly close: number | null;
+  readonly volume: number | null;
+  readonly oi: number | null;
+}
+
+/**
+ * The bars, held or pointed at.
+ *
+ * Both forms carry the same hash, computed the same way over the canonical
+ * tuple of each bar, so a referenced record can be turned into an inline one by
+ * whoever holds the bars and the result is the same case.
+ */
+export type BarsInRecord =
+  | {
+      readonly form: 'inline';
+      readonly hash: string;
+      readonly count: number;
+      readonly rows: readonly RecordedBar[];
+    }
+  | {
+      readonly form: 'referenced';
+      readonly hash: string;
+      readonly count: number;
+      readonly firstTime: number | null;
+      readonly lastTime: number | null;
+    };
+
+/** The columns of `conformance.md`'s frames.csv, in its order and with its names. */
+export interface RecordedFrame {
+  readonly afterBar: number;
+  /** An ordinal, 1-based, never an engine's own id. */
+  readonly intent: number;
+  readonly status: string;
+  readonly filledQty: number;
+  readonly avgFillPrice: number | null;
+  readonly orderRef: string | null;
+  readonly text: string | null;
+}
+
+/** A ledger row of `stdlib.md` 17.7, flattened: the `orders` channel of expected.json. */
+export interface RecordedOrder {
+  readonly intent: number;
+  readonly orderRef: string;
+  readonly tag: string;
+  readonly leg: string;
+  readonly positionRef: number;
+  readonly symbol: string | null;
+  readonly exchange: string | null;
+  readonly product: string;
+  readonly side: string;
+  readonly qty: number | null;
+  readonly qtyType: string;
+  readonly type: string | null;
+  readonly price: number | null;
+  readonly trigger: number | null;
+  readonly status: string;
+  readonly filledQty: number;
+  readonly avgFillPrice: number | null;
+  readonly rejection: string | null;
+  readonly placedAt: number | null;
+  readonly updatedAt: number | null;
+  readonly units: number | null;
+}
+
+/** A diagnostic as a record holds it: the code, the span and the bar. */
+export interface RecordedDiagnostic {
+  readonly code: string;
+  readonly line: number;
+  readonly column: number;
+  readonly severity: string;
+  readonly barIndex: number | null;
+}
+
+/** One run, whole, and readable by an engine that is not this one. */
+export interface RunRecord {
+  readonly recordVersion: number;
+  readonly engine: { readonly name: string; readonly version: string };
+  readonly languageVersion: string;
+  /** Already plain data. */
+  readonly program: CompiledProgram;
+  readonly programHash: string;
+  /** Hash, lines, file: the script revision. */
+  readonly source: SourceStamp;
+  readonly settings: BacktestSettings;
+  readonly bars: BarsInRecord;
+  /** What the destination answered, in delivery order. */
+  readonly frames: readonly RecordedFrame[];
+  /** What the engine folded, in fold order. */
+  readonly fills: readonly RecordedFill[];
+  /** The ledger at the end, oldest first. */
+  readonly orders: readonly RecordedOrder[];
+  readonly diagnostics: readonly RecordedDiagnostic[];
+  readonly report: Report;
+}
+
+/**
+ * The revision of this document's own shape.
+ *
+ * A reader is handed a record and has to know what it is looking at before it
+ * reads a field, so the number is first in the document and is written by this
+ * file alone. It moves when a channel is added or a meaning changes, never when
+ * a figure in a report does.
+ */
+export const RECORD_VERSION = 1;
+
+/** What this engine calls itself in a record it wrote. */
+const ENGINE_NAME = 'openscript';
+
+/** The parts a run hands over, each already in the shape the record holds. */
+export interface RecordParts {
+  readonly program: CompiledProgram;
+  readonly settings: BacktestSettings;
+  readonly bars: readonly RecordedBar[];
+  /**
+   * Whether the bars travel in the record or are pointed at.
+   *
+   * Inline is the conformance form, because a case holds every byte of its own
+   * input. Referenced is the operational form, because nothing that grows with
+   * history may travel in a request body. Both carry the same hash over the
+   * same canonical tuples, so one becomes the other without becoming a
+   * different case.
+   */
+  readonly form: 'inline' | 'referenced';
+  readonly frames: readonly RecordedFrame[];
+  readonly fills: readonly RecordedFill[];
+  readonly orders: readonly RecordedOrder[];
+  readonly diagnostics: readonly RecordedDiagnostic[];
+  readonly report: Report;
+}
+
+/**
+ * One run, as the document another engine is handed.
+ *
+ * Nothing is computed here. Every channel arrives folded, because what a record
+ * says has to be what the run did rather than what a second fold of the same
+ * inputs came to: a record that recomputed its own report would agree with
+ * itself whatever the engine had actually done.
+ */
+export function recordOf(parts: RecordParts): RunRecord {
+  return {
+    recordVersion: RECORD_VERSION,
+    engine: { name: ENGINE_NAME, version: VERSION },
+    languageVersion: String(parts.program.openscript.language),
+    program: parts.program,
+    programHash: programHash(parts.program),
+    source: parts.program.source,
+    settings: parts.settings,
+    bars: barsIn(parts.bars, parts.form),
+    frames: parts.frames,
+    fills: parts.fills,
+    orders: parts.orders,
+    diagnostics: parts.diagnostics,
+    report: parts.report,
+  };
+}
+
+/**
+ * The bars, held or pointed at, and the same hash either way.
+ *
+ * The referenced form keeps the first and last times so that a reader can say
+ * which bars are wanted without holding them, and the count so that a set of
+ * the wrong length is known to be wrong before it is hashed.
+ */
+export function barsIn(bars: readonly RecordedBar[], form: 'inline' | 'referenced'): BarsInRecord {
+  const hash = barsHash(bars);
+  if (form === 'inline') {
+    return { form: 'inline', hash, count: bars.length, rows: bars };
+  }
+  return {
+    form: 'referenced',
+    hash,
+    count: bars.length,
+    firstTime: bars[0]?.time ?? null,
+    lastTime: bars[bars.length - 1]?.time ?? null,
+  };
+}
+
+/**
+ * The hash a record names its bars by.
+ *
+ * Over the canonical tuple of each bar, in the order they were supplied, and
+ * through the canonical encoding the compiled program is hashed with, so there
+ * is one canonical writer in the repository rather than two that agree until
+ * one of them is changed. A tuple rather than an object, because the field
+ * order is then the specification's and not a sort's.
+ */
+export function barsHash(bars: readonly RecordedBar[]): string {
+  const tuples = bars.map((bar) => [
+    bar.time,
+    bar.open,
+    bar.high,
+    bar.low,
+    bar.close,
+    bar.volume,
+    bar.oi,
+  ]);
+  return 'sha256:' + sha256(canonicalise(tuples));
+}
+
+/**
+ * The record as the bytes another engine reads.
+ *
+ * Through the canonical encoding, so key order is fixed, every number is in the
+ * shortest decimal form that reads back as itself, and two runs of the same
+ * record produce the same bytes on every machine. That is what makes the
+ * reproducibility test a byte comparison rather than a tour of the fields.
+ */
+export function recordToJson(record: RunRecord): string {
+  return canonicalise(record);
+}
+
+/**
+ * The run, without who produced it.
+ *
+ * **`engine` is provenance, and provenance is not part of the run.** The claim
+ * a rerun makes is that the run is a function of the record, and that claim has
+ * to survive the engine it runs on being upgraded: a record stored under
+ * `0.3.0` and rerun under `0.4.0` produces the same trades, the same fills and
+ * the same money, and a document carrying the version stamp inside the bytes
+ * being compared says it does not.
+ *
+ * It was compared as whole bytes until the first version bump would have broken
+ * it, which is a test that passes for exactly as long as nothing changes and
+ * then fails for the one reason that is not a defect. So the stamp stays in the
+ * record, because knowing which engine wrote a run is worth keeping, and the
+ * comparison is made over everything else.
+ */
+export function runBytes(record: RunRecord): string {
+  const { engine: _engine, ...run } = record;
+  return canonicalise(run);
+}
+
+/**
+ * A record read back from those bytes.
+ *
+ * A parse and not a validation: what comes back is the document as it was
+ * written, and a document this engine did not write is the caller's to trust or
+ * not. The one thing asserted is the revision, because reading a later
+ * revision's fields under this one's rules is how a record silently becomes a
+ * different run.
+ */
+export function recordFromJson(text: string): RunRecord | null {
+  const parsed: unknown = JSON.parse(text);
+  if (parsed === null || typeof parsed !== 'object') return null;
+  const record = parsed as RunRecord;
+  return record.recordVersion === RECORD_VERSION ? record : null;
+}
+
+/**
+ * One ledger row, flattened into the words a case file prints.
+ *
+ * The engine's own types do not cross: a second engine has its own, and a
+ * channel written in this one's would be a case only this one could read. The
+ * intent is an ordinal for the same reason, because no engine can know what id
+ * another minted.
+ *
+ * `qtyType` comes from the intent rather than from the row, because the unit a
+ * quantity is counted in is per order and not per leg: an order the engine
+ * sized itself is in units whatever the declaration counts in, and a row that
+ * printed the declaration's unit for it would state a quantity in a unit it was
+ * never measured in.
+ */
+export function orderIn(row: LedgerRow, intent: number, qtyType: string): RecordedOrder {
+  return {
+    intent,
+    orderRef: row.orderRef,
+    tag: row.tag,
+    leg: row.leg,
+    positionRef: row.positionRef,
+    symbol: row.instrument.symbol,
+    exchange: row.instrument.exchange,
+    product: row.product,
+    side: row.side,
+    qty: row.qty,
+    qtyType,
+    type: row.type,
+    price: row.price,
+    trigger: row.trigger,
+    status: row.status,
+    filledQty: row.filledQty,
+    avgFillPrice: row.avgFillPrice,
+    rejection: row.rejection === '' ? null : row.rejection,
+    placedAt: row.placedAt,
+    updatedAt: row.updatedAt,
+    units: row.units,
+  };
+}
+
+/** One diagnostic, as a record holds it: the code, the span and the bar. */
+export function diagnosticIn(
+  diagnostic: Diagnostic,
+  barIndex: number | null,
+): RecordedDiagnostic {
+  return {
+    code: diagnostic.code,
+    line: diagnostic.span.line,
+    column: diagnostic.span.column,
+    severity: diagnostic.severity,
+    barIndex,
+  };
+}

package/src/core/backtest/replay.ts

@@ -0,0 +1,158 @@
+/**
+ * A stored run, reported again and run again.
+ *
+ * Two questions, and they are different questions, which is why they are two
+ * calls:
+ *
+ * - **`replay` asks whether the report is a function of the fills.** It folds
+ *   the money again from the record's own fills and its own bar closes, with no
+ *   bar executed and no order placed, and what comes back has to equal the
+ *   report the record carries. If it does not, the report was reading something
+ *   the engine happened to be holding rather than what the run settled, and
+ *   nobody could reproduce it from the document.
+ * - **`rerun` asks whether the engine still does what it did.** It executes the
+ *   record's program over the record's bars under the record's settings, and
+ *   the two records are compared as bytes. A rerun of one record on this engine
+ *   is bit-identical or it is a defect: the tolerance on the record is for a
+ *   second implementation and is never this one's excuse.
+ *
+ * **The bars are proved before either is attempted.** A record names the bars it
+ * was made from by a hash, and bars are revised: a feed corrects a print, a
+ * session is extended, a split is applied to history. A replay over revised bars
+ * reporting the original figures is the most convincing wrong answer this system
+ * can produce, so a set that does not hash to the record's is OS6022.
+ *
+ * **One engine call is made, and nothing is executed by it.** A declaration
+ * field may be written by an `input()`, and what an input resolved to is the
+ * engine's rule; asking it here rather than resolving a second time is what
+ * keeps the replayed capital and commission the ones the run used. No bar is
+ * appended, so no value is computed and no order is placed: the load is a
+ * question about the program, not a run of it.
+ */
+import { reportOf, scheduleFromDeclaration } from '../accounting/index.js';
+import type { ChargeSchedule, Report } from '../accounting/index.js';
+import { diagnosticFor } from '../diagnostics/index.js';
+import type { Diagnostic } from '../diagnostics/index.js';
+import { load } from '../engine/index.js';
+import { backtest } from './drive.js';
+import type { BacktestResult } from './drive.js';
+import { declarationOf } from './declaration.js';
+import type { RunDeclaration } from './declaration.js';
+import { marksFor, windowFor } from './range.js';
+import { barsHash } from './record.js';
+import type { RecordedBar, RunRecord } from './record.js';
+
+/** The report a record folds to, or why it could not be folded. */
+export type ReplayResult =
+  | { readonly ok: true; readonly report: Report }
+  | { readonly ok: false; readonly diagnostic: Diagnostic };
+
+/**
+ * The record's own report, computed again from its own fills.
+ *
+ * The bars are the record's where it carries them and the caller's where it
+ * points at them, and either way they are hashed against what the record names
+ * before a figure is computed from them.
+ */
+export function replay(record: RunRecord, bars: readonly RecordedBar[] | null = null): ReplayResult {
+  const held = barsOf(record, bars);
+  if (!held.ok) return { ok: false, diagnostic: held.diagnostic };
+
+  const framed = windowFor(held.bars, record.settings.range);
+  if (!framed.ok) return { ok: false, diagnostic: framed.diagnostic };
+
+  const declared = declarationIn(record);
+  if (!declared.ok) return { ok: false, diagnostic: declared.diagnostic };
+
+  return {
+    ok: true,
+    report: reportOf(
+      record.fills,
+      marksFor(held.bars, framed.covered),
+      scheduleIn(record, declared.declaration),
+      record.settings.contract,
+      declared.declaration.capital,
+    ),
+  };
+}
+
+/**
+ * The same run, executed again.
+ *
+ * Everything the run depended on is in the record: the program, the bars, the
+ * settings and the inputs. So a rerun takes no argument the record does not
+ * already hold, except the bars a referenced record points at rather than
+ * carries, and the record it produces is comparable with the original field for
+ * field and byte for byte.
+ */
+export function rerun(record: RunRecord, bars: readonly RecordedBar[] | null = null): BacktestResult {
+  const held = barsOf(record, bars);
+  if (!held.ok) return { ok: false, diagnostic: held.diagnostic };
+  return backtest(record.program, held.bars, record.settings, { form: record.bars.form });
+}
+
+type BarsResult =
+  | { readonly ok: true; readonly bars: readonly RecordedBar[] }
+  | { readonly ok: false; readonly diagnostic: Diagnostic };
+
+/**
+ * The bars a record was made from, proved to be those bars.
+ *
+ * A record carrying its own bars is still checked against any that are supplied
+ * beside them, because supplying a different set is exactly the mistake worth
+ * catching: the caller believes they are replaying this run and they are
+ * studying another one.
+ */
+export function barsOf(record: RunRecord, supplied: readonly RecordedBar[] | null): BarsResult {
+  if (supplied !== null) {
+    const hash = barsHash(supplied);
+    if (hash !== record.bars.hash) return { ok: false, diagnostic: mismatch(hash, record) };
+    return { ok: true, bars: supplied };
+  }
+  if (record.bars.form === 'inline') return { ok: true, bars: record.bars.rows };
+  // A referenced record points at bars it does not hold, so there is nothing to
+  // replay until whoever holds them supplies them. It is the same refusal as a
+  // wrong set, because the question it answers is the same one: are these the
+  // bars the record was made from.
+  return { ok: false, diagnostic: mismatch('no bars supplied', record) };
+}
+
+function mismatch(found: string, record: RunRecord): Diagnostic {
+  return diagnosticFor('OS6022', NO_POSITION, { found, expected: record.bars.hash });
+}
+
+type DeclarationResult =
+  | { readonly ok: true; readonly declaration: RunDeclaration }
+  | { readonly ok: false; readonly diagnostic: Diagnostic };
+
+/**
+ * What the record's own program declares, after the record's own inputs.
+ *
+ * The destination handed to the load is one that answers nothing, because
+ * nothing is placed: a strategy declares the orders capability and a host that
+ * did not offer it would be refused at load for a reason that has nothing to do
+ * with the record.
+ */
+function declarationIn(record: RunRecord): DeclarationResult {
+  const loaded = load(record.program, {
+    settings: record.settings.inputs,
+    host: { route: () => undefined },
+  });
+  if (!loaded.ok) return { ok: false, diagnostic: loaded.diagnostic };
+  return { ok: true, declaration: declarationOf(loaded.engine.program, loaded.inputs) };
+}
+
+/** The cost model the record was carried out under, derived where it was derived. */
+function scheduleIn(record: RunRecord, declared: RunDeclaration): ChargeSchedule {
+  if (record.settings.costs !== null) return record.settings.costs;
+  return scheduleFromDeclaration(
+    declared.commission,
+    declared.commissionType,
+    declared.slippage,
+    record.settings.contract.currency,
+    record.settings.contract.digits,
+  );
+}
+
+/** Where a refusal about a record points: nowhere in anybody's script. */
+const NO_POSITION: Diagnostic['span'] = { offset: 0, length: 0, line: 0, column: 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 };
+}