openalgo-script 0.4.0 → 0.6.0

package/src/core/backtest/record.ts

@@ -26,9 +26,9 @@
  */
 import type { RecordedFill, Report } from '../accounting/index.js';
 import type { Diagnostic } from '../diagnostics/index.js';
-import { canonicalise, programHash, sha256 } from '../emit/index.js';
+import { canonicalNumber, canonicalise, programHash, sha256, sourceHash } from '../emit/index.js';
 import type { CompiledProgram, SourceStamp } from '../emit/index.js';
-import type { LedgerRow } from '../engine/index.js';
+import type { Instrument, LedgerRow } from '../engine/index.js';
 import { VERSION } from '../version/index.js';
 import type { BacktestSettings } from './settings.js';
 
@@ -75,6 +75,20 @@ export interface RecordedFrame {
   readonly avgFillPrice: number | null;
   readonly orderRef: string | null;
   readonly text: string | null;
+  /**
+   * The destination's own instant for this frame, or null where it stated none.
+   *
+   * **One field of the ledger is folded from it.** `host-interface.md` 7.2
+   * gives a frame a `time` and `stdlib.md` 17.7 moves `updatedAt` to it, so a
+   * record that dropped it wrote a ledger no engine reading the case back could
+   * fold to: handed frames with no instant, that engine leaves every
+   * `updatedAt` at `placedAt`, and the two disagree on exactly the rows whose
+   * destination answered later than the bar that placed the order.
+   *
+   * Absent rather than substituted, because 7.2 lets a destination state none
+   * and a row whose frame stated none keeps the instant it had.
+   */
+  readonly time: number | null;
 }
 
 /** A ledger row of `stdlib.md` 17.7, flattened: the `orders` channel of expected.json. */
@@ -121,7 +135,43 @@ export interface RunRecord {
   readonly programHash: string;
   /** Hash, lines, file: the script revision. */
   readonly source: SourceStamp;
+  /**
+   * The source text itself, or null on a record written before version 2.
+   *
+   * **A record is the conformance case, and a case has to hold `script.os`.**
+   * `source` above identifies the script and cannot reproduce it: a hash is a
+   * fingerprint, so it settles whether two files are the same and yields
+   * neither of them. Without the text a stored record could be replayed months
+   * later and still not be handed to anybody else to run, which is the whole
+   * claim the suite exists to test.
+   *
+   * It lives here and not on the compiled program on purpose. A program is
+   * executable data that no engine needs the source to run, and it is the
+   * versioned artefact adopters depend on; putting the text there would send a
+   * script everywhere its program travels and widen the format every engine
+   * has to read. The record is the thing that wants to be self-contained.
+   */
+  readonly sourceText: string | null;
   readonly settings: BacktestSettings;
+  /**
+   * The instrument record of `host-interface.md` 4.1, as the engine was handed
+   * it, or null on a record written before version 3.
+   *
+   * **A case holds `instrument.json`, and `conformance.md` section 2 says that
+   * file is this record.** The contract in `settings` is the money layer's
+   * snapshot of the same instrument and holds six of the twelve facts; the
+   * ones a script reads and the money never does, the interval, the timezone,
+   * the session and the volume flag, were handed to the engine and written
+   * down nowhere. A case harvested from such a record either omitted a fact
+   * the page requires or stated one the run never had, and either way the
+   * second engine ran a different study than the one the expected output
+   * came from.
+   *
+   * It is the whole record and not the six facts beside the contract, because
+   * what is recorded is what the engine read at load, verbatim, and a reader
+   * should not have to compose it.
+   */
+  readonly instrument: Instrument | null;
   readonly bars: BarsInRecord;
   /** What the destination answered, in delivery order. */
   readonly frames: readonly RecordedFrame[];
@@ -141,7 +191,22 @@ export interface RunRecord {
  * 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;
+export const RECORD_VERSION = 4;
+
+/**
+ * The revision each later channel arrived in.
+ *
+ * A record written before a channel existed reads with that channel absent,
+ * and this table is what `recordFromJson` reads it from: one row per channel
+ * added since version 1, so the rule for an old record is stated once and
+ * grows by a line when the next channel does.
+ *
+ * `frameTime` is a field of a row rather than a channel of the document, and it
+ * is a row here for the same reason the other two are: what a reader has to
+ * know is which revision it arrived in. Where the absence is written differs,
+ * and that is the reader's business below, not this table's.
+ */
+const ADDED_IN = { sourceText: 2, instrument: 3, frameTime: 4 } as const;
 
 /** What this engine calls itself in a record it wrote. */
 const ENGINE_NAME = 'openscript';
@@ -149,7 +214,18 @@ const ENGINE_NAME = 'openscript';
 /** The parts a run hands over, each already in the shape the record holds. */
 export interface RecordParts {
   readonly program: CompiledProgram;
+  /**
+   * The script's own text, so the record can become a conformance case.
+   *
+   * Optional because a caller that has only a compiled program cannot invent
+   * it, and a run is still worth recording without it. `caseFilesFrom` is the
+   * one thing that then cannot be served, and it says so rather than writing a
+   * case with a hole in it.
+   */
+  readonly sourceText?: string;
   readonly settings: BacktestSettings;
+  /** The instrument record the engine was handed, `host-interface.md` 4.1. */
+  readonly instrument: Instrument;
   readonly bars: readonly RecordedBar[];
   /**
    * Whether the bars travel in the record or are pointed at.
@@ -180,11 +256,13 @@ export function recordOf(parts: RecordParts): RunRecord {
   return {
     recordVersion: RECORD_VERSION,
     engine: { name: ENGINE_NAME, version: VERSION },
-    languageVersion: String(parts.program.openscript.language),
+    languageVersion: canonicalNumber(parts.program.openscript.language),
     program: parts.program,
     programHash: programHash(parts.program),
     source: parts.program.source,
+    sourceText: textFor(parts),
     settings: parts.settings,
+    instrument: parts.instrument,
     bars: barsIn(parts.bars, parts.form),
     frames: parts.frames,
     fills: parts.fills,
@@ -194,6 +272,26 @@ export function recordOf(parts: RecordParts): RunRecord {
   };
 }
 
+/**
+ * The source text, checked against the hash the program already carries.
+ *
+ * A check rather than a promise, and it costs one hash of a few kilobytes. The
+ * failure it exists for is quiet: a caller that passes the text of a different
+ * revision than the one it compiled produces a case whose script does not make
+ * its own expected output, and the engine being tested gets the blame for a
+ * disagreement that was in the case all along.
+ */
+function textFor(parts: RecordParts): string | null {
+  const text = parts.sourceText;
+  if (text === undefined) return null;
+  if (sourceHash(text) !== parts.program.source.hash) {
+    throw new Error(
+      'openscript: the source text does not hash to the source hash the program carries',
+    );
+  }
+  return text;
+}
+
 /**
  * The bars, held or pointed at, and the same hash either way.
  *
@@ -283,7 +381,38 @@ 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;
+  const version = record.recordVersion;
+  if (typeof version !== 'number' || version < 1 || version > RECORD_VERSION) return null;
+  // An earlier revision is readable and a later one is not, and the asymmetry
+  // is the point. A later revision may mean something by a field this one
+  // thinks it knows, which is how a record silently becomes a different run. An
+  // earlier one only ever has fewer: every channel it carries means here what
+  // it meant there, and the ones added since are absent rather than wrong. So a
+  // run stored months ago still reads, which is the whole of what it was stored
+  // for, and a channel it never carried reads as absent.
+  if (version === RECORD_VERSION) return record;
+  return {
+    ...record,
+    sourceText: version >= ADDED_IN.sourceText ? record.sourceText : null,
+    instrument: version >= ADDED_IN.instrument ? record.instrument : null,
+    frames: version >= ADDED_IN.frameTime ? record.frames : timeless(record.frames),
+  };
+}
+
+/**
+ * The frames of a record written before a frame carried an instant.
+ *
+ * The absence is written on every frame rather than on the record, because the
+ * channel is a field of a row: a reader that left the field undefined would
+ * hand the case projection an undefined where the column's absent spelling
+ * belongs, and the file would read `undefined` back to the next engine. The
+ * frames are left as they are when they are not an array, because this is a
+ * parse and not a validation and a document this engine did not write is the
+ * caller's to trust or not.
+ */
+function timeless(frames: readonly RecordedFrame[]): readonly RecordedFrame[] {
+  if (!Array.isArray(frames)) return frames;
+  return frames.map((frame) => ({ ...frame, time: null }));
 }
 
 /**

package/src/core/backtest/replay.ts

@@ -88,7 +88,17 @@ export function replay(record: RunRecord, bars: readonly RecordedBar[] | null =
 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 });
+  // Everything the run depended on, and that includes the two channels that
+  // arrived after the sentence above was written. The instrument record is what
+  // the engine read at load, so a rerun handed the contract alone runs under
+  // different session facts and does not reproduce the bytes; the text is what
+  // makes the rerun's record harvestable, and dropping it would turn a record
+  // that could become a case into one that cannot, by being rerun.
+  return backtest(record.program, held.bars, record.settings, {
+    form: record.bars.form,
+    ...(record.instrument === null ? {} : { instrument: record.instrument }),
+    ...(record.sourceText === null ? {} : { sourceText: record.sourceText }),
+  });
 }
 
 type BarsResult =

package/src/core/backtest/simulate.ts

@@ -30,6 +30,21 @@
  * 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.
+ *
+ * **A destination that behaves badly does it on a schedule, stated before the
+ * run and never by chance.** Every case harvested before this one ran against a
+ * venue that filled every order whole and on time, so two engines were proved
+ * to agree about the half of a day that costs nobody anything. The other half
+ * is a partial fill, an order arriving in pieces, a rejection, a cancellation,
+ * an expiry and a fill that turns up after the order has ended, and
+ * `SimulatorOptions.fill` carries the schedule saying which order each of those
+ * happens to and at which boundary. There is no random number here and there
+ * will not be one: `stdlib.md` 8.2 keeps a script that answers differently on a
+ * second run out of a conformance suite, and a venue rolling a die would make
+ * every case it wrote unreproducible in the same breath. **An order the
+ * schedule names is answered by the schedule and by nothing else**, so a run
+ * stating none is the run the cases before this one were harvested from, to the
+ * bit, which is what lets this exist at all.
  */
 import type { Contract } from '../accounting/index.js';
 import type { OrderFrame, OrderIntent, OrderSide, RoutedEffect } from '../engine/index.js';
@@ -38,11 +53,70 @@ import { testResting } from './resting.js';
 import type { RestingOrder } from './resting.js';
 import type { FillPolicy } from './settings.js';
 
+/**
+ * What this destination does to one order, at one boundary.
+ *
+ * Four words reaching every status of `stdlib.md` 17.7 a host may send. `fill`
+ * carries the cumulative quantity, so one word covers the acknowledgement
+ * before anything has traded, a fill of part of the order and a fill of the
+ * whole of it: `working` and `filled` are that quantity read against the
+ * order's own rather than two instructions. The other three are the three ways
+ * an order ends carrying less than it asked for, and an engine never handed
+ * one has never been asked what it does with the quantity still working.
+ */
+export type VenueDoes = 'fill' | 'reject' | 'cancel' | 'expire';
+
+/** One act of the schedule: what the destination does, to which order, when. */
+export interface VenueAct {
+  /**
+   * The nth order this destination took, counting from one.
+   *
+   * Orders and not intents: a bracket is never taken and a cancellation is
+   * answered without being held, so neither is counted and neither can be named
+   * here. An ordinal for the reason `conformance.md` section 3 gives a case's
+   * own frames: nobody writing a schedule knows the id an engine will mint.
+   */
+  readonly order: number;
+  /**
+   * Boundaries after the one the order arrived at, `0` being that boundary.
+   *
+   * Counted from the order rather than stated as a bar index, because the bar
+   * a strategy decides an order on moves the moment anything else about the run
+   * does, and a schedule in bar indices is one nobody can read back.
+   */
+  readonly afterBars: number;
+  readonly does: VenueDoes;
+  /**
+   * The cumulative quantity a fill reports, in units, or absent for all of it.
+   *
+   * Cumulative because a frame is (`stdlib.md` 17.8): `0` is the
+   * acknowledgement a venue sends before anything has traded, a number below
+   * the order's own is a partial fill, and one at or above it completes the
+   * order. A quantity below what this venue has already reported is a stale
+   * frame, which a venue really sends and the fold has to swallow, so it is
+   * stated here rather than refused.
+   */
+  readonly units?: number | null;
+  /** The destination's own text, which the ledger records against the row. */
+  readonly text?: string;
+}
+
+/**
+ * The fill policy, and what this destination does to the orders it names.
+ *
+ * The schedule sits on the policy because it is the same kind of fact: how this
+ * destination decides a fill, chosen before the first bar and carried in the
+ * record beside the policy's own version, so a stored run replays as it ran.
+ */
+export interface VenuePolicy extends FillPolicy {
+  readonly schedule?: readonly VenueAct[];
+}
+
 /** What the venue prices against and how it decides a fill. */
 export interface SimulatorOptions {
   readonly bars: readonly RecordedBar[];
   readonly contract: Contract;
-  readonly fill: FillPolicy;
+  readonly fill: VenuePolicy;
   /** 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. */
@@ -64,7 +138,11 @@ interface Order {
   readonly placedOn: number;
   /** Absent on a market order, which rests on nothing. */
   readonly rest: RestingOrder | null;
+  /** The acts the schedule states about this order, in the order they were stated. */
+  readonly acts: readonly VenueAct[];
   filledQty: number;
+  /** This venue's average over `filledQty`, absent while nothing has filled. */
+  avgPrice: number | null;
   live: boolean;
   /** Whether a stop limit has reached its trigger and is now a limit. */
   triggered: boolean;
@@ -73,6 +151,20 @@ interface Order {
 /** `language.md` 13.3: a market order priced at the close of its own bar. */
 const AT_CLOSE = 'close';
 
+/**
+ * The word this venue reports each ending under.
+ *
+ * A destination with words of its own maps them onto the vocabulary in its
+ * adapter, which is where `stdlib.md` 17.7 puts the mapping because a status
+ * vocabulary differs per destination. This is this one's, and the whole of what
+ * a schedule's verb means.
+ */
+const ENDED: Readonly<Record<Exclude<VenueDoes, 'fill'>, string>> = {
+  reject: 'rejected',
+  cancel: 'cancelled',
+  expire: 'expired',
+};
+
 /**
  * A venue, for one run.
  *
@@ -123,6 +215,13 @@ export class Simulator {
     const bar = this.options.bars[barIndex];
     if (bar !== undefined) {
       for (const order of this.orders) {
+        // An order the schedule names is answered by the schedule, whether or
+        // not it is still live: a fill after a cancellation is the one thing
+        // this exists for and the order is dead by then.
+        if (order.acts.length > 0) {
+          if (order.placedOn < barIndex) this.perform(order, bar, barIndex);
+          continue;
+        }
         if (!order.live || order.rest === null || order.placedOn >= barIndex) continue;
         this.decide(order, bar, barIndex);
       }
@@ -145,12 +244,17 @@ export class Simulator {
   /** An order the strategy sent, which this venue now holds. */
   private accept(intent: OrderIntent, barIndex: number): void {
     this.refs += 1;
+    // The ordinal of this order among the orders taken, which is what an act
+    // names. Read before the order joins them, so the first is one.
+    const ordinal = this.orders.length + 1;
     const order: Order = {
       intent,
       ref: refOf(this.refs),
       placedOn: barIndex,
       rest: restingFor(intent),
+      acts: (this.options.fill.schedule ?? []).filter((act) => act.order === ordinal),
       filledQty: 0,
+      avgPrice: null,
       live: true,
       triggered: false,
     };
@@ -188,6 +292,15 @@ export class Simulator {
    * where it does not.
    */
   private open(order: Order, barIndex: number): void {
+    // A scheduled order is answered by its schedule from its first breath. The
+    // acknowledgement below is a thing this venue chooses to say, so a schedule
+    // that wants one states it, and one that wants the destination to sit on an
+    // order and say nothing gets that instead.
+    if (order.acts.length > 0) {
+      const bar = this.options.bars[barIndex];
+      if (bar !== undefined) this.perform(order, bar, barIndex);
+      return;
+    }
     this.say(order.intent, order.ref, 'working', 0, null, barIndex);
     if (order.rest !== null) return;
 
@@ -227,15 +340,96 @@ export class Simulator {
    * 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;
+    const qty = this.unitsOf(order.intent);
     order.filledQty = qty;
+    order.avgPrice = price;
     order.live = false;
     this.say(order.intent, order.ref, 'filled', qty, price, barIndex);
   }
 
+  /**
+   * The acts due at this boundary, in the order the schedule stated them.
+   *
+   * Due is counted from the bar that sent the order, so an act names a moment
+   * in the life of its own order rather than a bar of the run. Two acts due
+   * together are answered as written, which is how a schedule states a
+   * cancellation and the fill that raced it.
+   *
+   * Liveness is not consulted. An order that has ended can still be spoken
+   * about, because the frame that arrives after it ended is the whole reason
+   * this is here: `stdlib.md` 17.8's fill after a terminal status, which a
+   * venue sends whenever a cancel races a fill and which an engine refusing it
+   * loses, leaving a position the strategy cannot see.
+   */
+  private perform(order: Order, bar: RecordedBar, barIndex: number): void {
+    for (const act of order.acts) {
+      if (order.placedOn + act.afterBars !== barIndex) continue;
+      if (act.does === 'fill') {
+        this.report(order, act, bar, barIndex);
+        continue;
+      }
+      // The order ends, reporting what it filled before it ended, because a
+      // frame is cumulative: `stdlib.md` 17.8 has the row keeping the terminal
+      // word and the quantity recording what traded, both true at once.
+      order.live = false;
+      const ended = ENDED[act.does];
+      const price = order.filledQty > 0 ? order.avgPrice : null;
+      this.say(order.intent, order.ref, ended, order.filledQty, price, barIndex, act.text ?? '');
+    }
+  }
+
+  /**
+   * A fill the schedule stated, at this bar's close and worsened like any other.
+   *
+   * **The average is this venue's own, over the cumulative quantity**, the
+   * figure `stdlib.md` 17.8 step 3 says the row takes whole. A venue reporting
+   * the last piece's price and calling it an average hands the engine a number
+   * that is not one, and the engine may not work its own out from two of them,
+   * so the lie settles into the ledger and into every trade folded from it.
+   *
+   * A stated quantity at or below what this venue has already reported adds
+   * nothing and moves nothing: that is a repeated or a stale frame, which a real
+   * destination sends and the fold has to swallow. It carries the average this
+   * venue holds now rather than then, because it keeps no history of its own
+   * averages and the fold ignores the price of a frame adding no quantity. A
+   * bar with no close prices nothing, so an act due at one says nothing rather
+   * than raising a quantity with no price against it, which step 3 refuses.
+   */
+  private report(order: Order, act: VenueAct, bar: RecordedBar, barIndex: number): void {
+    const whole = this.unitsOf(order.intent);
+    const stated = act.units ?? whole;
+    const delta = stated - order.filledQty;
+    if (delta > 0) {
+      if (bar.close === null) return;
+      // Written in this order and left in it: the source order of a sum is
+      // what decides its last bit, and a case harvested from this venue is
+      // asserted to the bit.
+      const price = this.worsen(bar.close, order.intent.side);
+      order.avgPrice = ((order.avgPrice ?? 0) * order.filledQty + price * delta) / stated;
+      order.filledQty = stated;
+      if (order.filledQty >= whole) order.live = false;
+    }
+    // `working` is live and not completely filled, `filled` is the whole
+    // quantity: 17.7's two words read off the quantity rather than stated
+    // twice by a schedule that could disagree with the number beside them.
+    const status = order.filledQty >= whole ? 'filled' : 'working';
+    const price = stated > 0 ? order.avgPrice : null;
+    this.say(order.intent, order.ref, status, stated, price, barIndex, act.text ?? '');
+  }
+
+  /**
+   * The order's quantity in units, which is what a fill is counted in.
+   *
+   * The conversion `complete` did inline, wanted in two places the moment a
+   * schedule can fill an order in pieces: the whole a piece is measured
+   * against has to be the number the fill path would have reported.
+   */
+  private unitsOf(intent: OrderIntent): number {
+    const stated = intent.qty ?? 0;
+    const lot = this.options.contract.lotSize;
+    return this.options.qtyType === 'lots' && lot !== null && lot > 0 ? stated * lot : stated;
+  }
+
   /**
    * A price worsened by the slippage the run was carried out under.
    *
@@ -270,6 +464,7 @@ export class Simulator {
     filledQty: number,
     avgFillPrice: number | null,
     barIndex: number,
+    text = '',
   ): void {
     this.seq += 1;
     this.answered.push({
@@ -281,7 +476,7 @@ export class Simulator {
       sentInstrument: intent.instrument,
       sentProduct: intent.product,
       time: this.options.bars[barIndex]?.time ?? null,
-      text: '',
+      text,
       seq: this.seq,
     });
   }