openalgo-script 0.4.0 → 0.6.0

package/src/core/backtest/drive.ts

@@ -25,51 +25,195 @@
  * is reported on bar k + 1. A frame answered after the last bar has no boundary
  * left to fold at: it is not delivered, it is not recorded as delivered, and
  * the order it was about is in the ledger at whatever it last said.
+ *
+ * **Two drivers, and the only difference between them is where the frames come
+ * from.** `backtest` runs against the simulated destination, which decides a
+ * fill from the bars and answers frames of its own; `backtestSupplied` is
+ * handed the frames and delivers those. Everything else about the two is one
+ * function below: the same window, the same load, the same refusals, the same
+ * loop and the same record.
  */
 import { reportOf, scheduleFromDeclaration } from '../accounting/index.js';
-import type { ChargeSchedule, RecordedFill } from '../accounting/index.js';
+import type { ChargeSchedule, Contract } from '../accounting/index.js';
 import type { Diagnostic } from '../diagnostics/index.js';
 import type { CompiledProgram } from '../emit/index.js';
 import { load } from '../engine/index.js';
 import type {
-  BarResult,
-  Engine,
+  Drawing,
   EngineHost,
+  Grid,
   Instrument,
   LedgerRow,
-  OrderFrame,
   OrderIntent,
+  RequestProvider,
   RoutedEffect,
+  Value,
 } from '../engine/index.js';
 import { declarationOf } from './declaration.js';
 import type { RunDeclaration } from './declaration.js';
+import { Delivery, framedAs, ordinalsOf } from './deliver.js';
+import type { Destination } from './deliver.js';
 import { marksFor, windowFor } from './range.js';
-import type { ReportWindow } from './range.js';
-import { diagnosticIn, orderIn, recordOf } from './record.js';
-import type {
-  RecordedBar,
-  RecordedDiagnostic,
-  RecordedFrame,
-  RecordedOrder,
-  RunRecord,
-} from './record.js';
+import { orderIn, recordOf } from './record.js';
+import type { RecordedBar, RecordedFrame, RecordedOrder, RunRecord } from './record.js';
 import { Simulator } from './simulate.js';
 import { checkSettings } from './settings.js';
+import { walk } from './walk.js';
+import type { LogLine } from './walk.js';
 import type { BacktestSettings } from './settings.js';
 
 /** What a run came to, or why it could not be carried out at all. */
 export type BacktestResult =
-  | { readonly ok: true; readonly record: RunRecord }
+  | {
+      readonly ok: true;
+      readonly record: RunRecord;
+      readonly rows?: readonly (readonly Value[])[];
+      readonly log?: readonly LogLine[];
+      readonly surface?: Surface;
+    }
   | { readonly ok: false; readonly diagnostic: Diagnostic };
 
+/** The drawing objects and the grids the last bar left, `conformance.md` section 4. */
+export interface Surface {
+  readonly drawings: readonly Drawing[];
+  readonly tables: readonly Grid[];
+}
+
+/**
+ * The facts of `host-interface.md` 4.1 that the contract does not hold.
+ *
+ * The contract already states six of the twelve, the ones the money is priced
+ * under, and a fact stated in two places is a fact that can disagree with
+ * itself: a tick size the engine rounds to and a different one the venue
+ * worsens a fill by is a run under two instruments. So the other six are
+ * stated here and the six the contract holds cannot be, which the compiler
+ * enforces rather than a check at run time.
+ */
+export type InstrumentFacts = Omit<
+  Instrument,
+  'symbol' | 'exchange' | 'tickSize' | 'lotSize' | 'pointValue' | 'currency'
+>;
+
 /** The few choices a driver has that are not settings of the run itself. */
 export interface DriveOptions {
   /** Whether the bars travel in the record. Inline is the conformance form. */
   readonly form?: 'inline' | 'referenced';
+  /**
+   * What the host states about the instrument beside the contract, so the
+   * record it produces is a conformance case.
+   *
+   * A case holds `instrument.json`, which `conformance.md` section 2 says is
+   * the record of `host-interface.md` 4.1, and that page requires one fact of
+   * every host: `hasVolume`, because no derivation recovers it (4.2). The
+   * engine reads the record and does not refuse a run without it, so a caller
+   * that leaves this out gets a record that replays and reruns like any other
+   * and cannot become a case, exactly as one without `sourceText` cannot.
+   *
+   * A session stated without a timezone is refused at load, OS6012, by the
+   * same rule that refuses it for any host.
+   */
+  readonly instrument?: InstrumentFacts;
+  /**
+   * The script's own text, so the record it produces is a conformance case.
+   *
+   * A compiled program identifies its source and cannot reproduce it, and a
+   * case has to hold `script.os`. A caller holding only a program leaves this
+   * out and gets a record that replays and reruns like any other; the one
+   * thing it cannot do is be handed to somebody else's engine as a case.
+   *
+   * It is checked against the program's own source hash, so text from a
+   * different revision than the one that was compiled is refused rather than
+   * written into a case that could never make its own expected output.
+   */
+  readonly sourceText?: string;
+  /**
+   * Whether to hand back every channel's value on every bar that ran, beside
+   * the record rather than inside it.
+   *
+   * A conformance case that asserts `values` compares one value per bar per
+   * plot, and the record holds none of them: it is the reproducible run, and a
+   * curve per plot is bytes it would carry for every run to serve the few cases
+   * that ask. So the rows are asked for, and a run that does not ask pays
+   * nothing. A bar that failed has no row, as in the second engine.
+   */
+  readonly rows?: boolean;
+  /** Whether to hand back every line `print` wrote, beside the record, for the same reason. */
+  readonly log?: boolean;
+  /** Whether to hand back the drawing objects and grids the last bar left, for the same reason. */
+  readonly surface?: boolean;
+  /**
+   * Bars for another instrument, `host-interface.md` 5, for a run whose host
+   * serves them.
+   *
+   * Left out, the run holds the chart's own bars and nothing else: a read of
+   * the chart's instrument at a coarser interval is folded from them, and a
+   * program that reads another instrument declares a capability this host does
+   * not have and is refused at load by name. Given, the host serves duty 3 and
+   * the engine asks it once per read, before bar 0.
+   */
+  readonly requestBars?: RequestProvider;
 }
 
+
 /**
- * One run, from a compiled program to a record of it.
+ * One run against a simulated destination, from a compiled program to a record.
+ *
+ * The frames are the destination's own: it is handed the orders, it reads the
+ * bars, and what it answers is what the engine folds. A run whose frames
+ * somebody else is supplying is `backtestSupplied` below.
+ */
+export function backtest(
+  program: CompiledProgram,
+  bars: readonly RecordedBar[],
+  settings: BacktestSettings,
+  options: DriveOptions = {},
+): BacktestResult {
+  return drive(program, bars, settings, options, (declared, schedule) =>
+    simulated(
+      new Simulator({
+        bars,
+        contract: settings.contract,
+        fill: settings.fill,
+        slippageTicks: schedule.slippageTicks,
+        fillOn: declared.fillOn,
+        qtyType: declared.qtyType,
+      }),
+    ),
+  );
+}
+
+/**
+ * One run over the frames somebody else supplied, which this engine does not
+ * choose and does not add to.
+ *
+ * `conformance.md` section 3 gives a case a `frames.csv` that supplies order
+ * frames the way `bars.csv` supplies bars, so that a case asserts the fold
+ * against input the engine did not choose. Every other argument is `backtest`'s
+ * and means there what it means here. A row is delivered at the boundary it
+ * names and folded before the next bar, and the record carries the rows it was
+ * handed rather than a second spelling of them.
+ *
+ * **Nothing is invented.** No fill is priced off a bar, no order rests and no
+ * schedule is read, so an order the frames say nothing about stays where its
+ * placement left it, which is what a case saying nothing about it means.
+ *
+ * **A record made here is a record of this run and not of a simulated one.**
+ * `rerun` puts a record's program back on a simulated destination, because a
+ * record does not say which of the two answered it, so a rerun of one of these
+ * reproduces it only where that destination would answer these same frames.
+ */
+export function backtestSupplied(
+  program: CompiledProgram,
+  bars: readonly RecordedBar[],
+  settings: BacktestSettings,
+  frames: readonly RecordedFrame[],
+  options: DriveOptions = {},
+): BacktestResult {
+  return drive(program, bars, settings, options, () => new Delivery(frames));
+}
+
+/**
+ * The run both drivers are, and the one place a record is made.
  *
  * A refusal before the first bar comes back as a refusal and not as a record:
  * a program that would not load, a setting that cannot be applied and a window
@@ -77,24 +221,33 @@ export interface DriveOptions {
  * be a document asserting figures nothing computed. A failure during a bar is
  * the other way round: the run happened, it stopped, and the record carries
  * both what it did and the diagnostic that stopped it.
+ *
+ * **The destination is chosen after the program is loaded**, which is why it
+ * arrives as a function of the declaration and the schedule: the bar a market
+ * order is priced at is the declaration's, and the declaration is resolved at
+ * load. The route is wired first and reaches whatever is chosen through the
+ * binding below, which is what lets one host serve both halves.
  */
-export function backtest(
+function drive(
   program: CompiledProgram,
   bars: readonly RecordedBar[],
   settings: BacktestSettings,
-  options: DriveOptions = {},
+  options: DriveOptions,
+  choose: (declared: RunDeclaration, schedule: ChargeSchedule) => Destination,
 ): BacktestResult {
   const framed = windowFor(bars, settings.range);
   if (!framed.ok) return { ok: false, diagnostic: framed.diagnostic };
 
-  // The venue is built after the program is loaded, because the bar a market
-  // order is priced at is the declaration's and the declaration is resolved at
-  // load. The route is wired first and reaches it through this binding, which
-  // is what lets one host serve both halves.
-  let venue: Simulator | undefined;
+  let sending: Destination | undefined;
+  const instrument = instrumentFor(settings.contract, options.instrument ?? {});
   const loaded = load(program, {
     settings: settings.inputs,
-    host: hostFor(settings, (effect, bar) => venue?.route(effect, bar)),
+    host: hostFor(
+      instrument,
+      settings.now,
+      (effect, bar) => sending?.route(effect, bar),
+      options.requestBars,
+    ),
   });
   if (!loaded.ok) return { ok: false, diagnostic: loaded.diagnostic };
 
@@ -104,204 +257,44 @@ export function backtest(
   if (problem !== null) return { ok: false, diagnostic: problem };
 
   const schedule = scheduleFor(settings, declared);
-  venue = new Simulator({
-    bars,
-    contract: settings.contract,
-    fill: settings.fill,
-    slippageTicks: schedule.slippageTicks,
-    fillOn: declared.fillOn,
-    qtyType: declared.qtyType,
-  });
+  const destination = choose(declared, schedule);
+  sending = destination;
 
-  const run = walk(engine, venue, bars, framed.covered);
-  const ordinals = ordinalsOf(venue.intents);
+  const run = walk(engine, destination, bars, framed.covered, options);
+  const ordinals = ordinalsOf(destination.intents);
   const marks = marksFor(bars, framed.covered);
 
   return {
     ok: true,
+    ...(options.rows === true ? { rows: run.rows } : {}),
+    ...(options.log === true ? { log: run.log } : {}),
+    ...(options.surface === true ? { surface: { drawings: engine.drawings(), tables: engine.tables() } } : {}),
     record: recordOf({
       program: engine.program,
+      ...(options.sourceText === undefined ? {} : { sourceText: options.sourceText }),
       settings,
+      instrument,
       bars,
       form: options.form ?? 'inline',
-      frames: run.frames.map((one) => framedAs(one.frame, one.afterBar, ordinals)),
+      // The row where a case supplied one, because that row is the input and a
+      // record of a run over it says what it was given rather than what it
+      // would have written down had it decided the frame itself.
+      frames: run.frames.map((one) => one.row ?? framedAs(one.frame, one.afterBar, ordinals)),
       fills: run.fills,
-      orders: ordersOf(engine.orders(), venue.intents, ordinals),
+      orders: ordersOf(engine.orders(), destination.intents, ordinals),
       diagnostics: run.diagnostics,
       report: reportOf(run.fills, marks, schedule, settings.contract, declared.capital),
     }),
   };
 }
 
-/** A frame, and the boundary it was handed over at. */
-interface Delivered {
-  readonly frame: OrderFrame;
-  readonly afterBar: number;
-}
-
-/** What one walk of the bars produced. */
-interface Walked {
-  readonly fills: readonly RecordedFill[];
-  readonly frames: readonly Delivered[];
-  readonly diagnostics: readonly RecordedDiagnostic[];
-}
-
-/**
- * The bars, in order, with the venue answering between them.
- *
- * The one ordering rule: deliver, then append, then collect what the append
- * reported, then ask the venue what this bar did. A driver that asked the venue
- * before appending would price a fill against a bar the strategy had not seen.
- */
-function walk(
-  engine: Engine,
-  venue: Simulator,
-  bars: readonly RecordedBar[],
-  covered: ReportWindow,
-): Walked {
-  const fills: RecordedFill[] = [];
-  const frames: Delivered[] = [];
-  const diagnostics: RecordedDiagnostic[] = [];
-  const intents = new Map<number, OrderIntent>();
-  const refs = new Map<number, string>();
-  const sizes = new Map<number, number>();
-
-  let pending: readonly Delivered[] = [];
-  let seq = 0;
-
-  for (let index = 0; index < covered.total; index += 1) {
-    const bar = bars[index];
-    if (bar === undefined) continue;
-
-    for (const one of pending) {
-      const ref = one.frame.orderRef;
-      if (typeof ref === 'string') refs.set(one.frame.intentId, ref);
-      engine.deliver(one.frame);
-      frames.push(one);
-    }
-    pending = [];
-
-    const result = engine.append(
-      { time: bar.time, open: bar.open, high: bar.high, low: bar.low, close: bar.close,
-        volume: bar.volume, oi: bar.oi },
-      { isConfirmed: true, isRealtime: false },
-      covered.total,
-    );
-
-    for (const intent of intentsIn(result)) intents.set(intent.intentId, intent);
-    seq = settle(result, index, bar, { intents, refs, sizes }, fills, seq);
-
-    if (result.diagnostic !== undefined) {
-      diagnostics.push(diagnosticIn(result.diagnostic, index));
-      break;
-    }
-
-    pending = venue.framesFor(index).map((frame) => ({ frame, afterBar: index }));
-  }
-
-  return { fills, frames, diagnostics };
-}
-
-/** What the run is holding while it folds one bar's frames into fills. */
-interface Books {
-  readonly intents: ReadonlyMap<number, OrderIntent>;
-  readonly refs: ReadonlyMap<number, string>;
-  readonly sizes: Map<number, number>;
-}
-
-/**
- * The fills one bar's fold settled.
- *
- * **The position sizes either side of step 6 are kept here and not read back
- * from the engine**, because the engine reports a leg's net and a fill settles
- * against one position reference: the two are different numbers whenever a leg
- * holds more than one position, which is every flip. They are folded in the
- * order the frames were folded in, from the same deltas, so they are the same
- * arithmetic the position book did rather than a second reading of its result.
- * When `FrameOutcome` carries them, these two lines come from the engine and
- * this fold keeps only the sequence number.
- *
- * A refused frame settles nothing and is not a fill. Today the fold reports the
- * refusal as a word rather than a code, so nothing here can write it into the
- * record as a diagnostic; that is OS7018 and OS7019, and both are deferred.
- */
-function settle(
-  result: BarResult,
-  index: number,
-  bar: RecordedBar,
-  books: Books,
-  fills: RecordedFill[],
-  from: number,
-): number {
-  let seq = from;
-  for (const outcome of result.frames) {
-    if (outcome.refused !== undefined) continue;
-    if (outcome.delta <= 0 || outcome.price === null) continue;
-    const intent = books.intents.get(outcome.intentId);
-    if (intent === undefined || intent.side === null) continue;
-
-    const before = books.sizes.get(intent.positionRef) ?? 0;
-    const after = before + (intent.side === 'sell' ? -outcome.delta : outcome.delta);
-    books.sizes.set(intent.positionRef, after);
-    seq += 1;
-
-    fills.push({
-      seq,
-      intentId: outcome.intentId,
-      orderRef: books.refs.get(outcome.intentId) ?? '',
-      tag: intent.tag,
-      positionRef: intent.positionRef,
-      side: intent.side,
-      units: outcome.delta,
-      price: outcome.price,
-      // The bar the fold happened at, which is the bar the position exists
-      // from. Where the fill itself traded is the bar before it or this bar's
-      // own open, and neither is a bar the strategy could have acted on it in.
-      barIndex: index,
-      barTime: bar.time,
-      refSizeBefore: before,
-      refSizeAfter: after,
-    });
-  }
-  return seq;
-}
-
-/** Every intent one bar handed over, in the order the bar applied them. */
-function intentsIn(result: BarResult): readonly OrderIntent[] {
-  const out: OrderIntent[] = [];
-  for (const effect of result.effects) for (const intent of effect.intents) out.push(intent);
-  return out;
-}
-
-/**
- * The ordinal of every intent, which is how a case names one.
- *
- * One, two, three in the order the run placed them, because no engine can know
- * the id another minted and a case that named one would only ever be readable
- * by the engine that wrote it.
- */
-function ordinalsOf(intents: readonly OrderIntent[]): ReadonlyMap<number, number> {
-  const out = new Map<number, number>();
-  for (const intent of intents) {
-    if (!out.has(intent.intentId)) out.set(intent.intentId, out.size + 1);
-  }
-  return out;
-}
-
-/** One delivered frame, in the columns a case file prints. */
-function framedAs(
-  frame: OrderFrame,
-  afterBar: number,
-  ordinals: ReadonlyMap<number, number>,
-): RecordedFrame {
+/** The simulated destination, as a destination the loop below can drive. */
+function simulated(venue: Simulator): Destination {
   return {
-    afterBar,
-    intent: ordinals.get(frame.intentId) ?? 0,
-    status: frame.status,
-    filledQty: frame.filledQty,
-    avgFillPrice: frame.avgFillPrice ?? null,
-    orderRef: frame.orderRef ?? null,
-    text: frame.text ?? null,
+    route: (effect, barIndex) => venue.route(effect, barIndex),
+    answers: (barIndex) =>
+      venue.framesFor(barIndex).map((frame) => ({ frame, afterBar: barIndex, row: null })),
+    intents: venue.intents,
   };
 }
 
@@ -336,29 +329,52 @@ function scheduleFor(settings: BacktestSettings, declared: RunDeclaration): Char
   );
 }
 
+/**
+ * The instrument record of `host-interface.md` 4.1 the engine is handed, and
+ * the record carries verbatim.
+ *
+ * Composed once, here, from the contract's six facts and the six stated beside
+ * it, so the engine and the record read one document and there is no second
+ * composition for the two to disagree by. A fact nobody stated is left out
+ * rather than written as undefined: the record travels as JSON, which drops an
+ * undefined member, and a document that changes shape in transit is not the
+ * document the engine read.
+ */
+function instrumentFor(contract: Contract, facts: InstrumentFacts): Instrument {
+  return {
+    ...(contract.symbol === null ? {} : { symbol: contract.symbol }),
+    ...(contract.exchange === null ? {} : { exchange: contract.exchange }),
+    ...(facts.interval === undefined ? {} : { interval: facts.interval }),
+    ...(facts.timezone === undefined ? {} : { timezone: facts.timezone }),
+    ...(contract.tickSize === null ? {} : { tickSize: contract.tickSize }),
+    ...(contract.lotSize === null ? {} : { lotSize: contract.lotSize }),
+    pointValue: contract.pointValue,
+    currency: contract.currency,
+    ...(facts.instrumentType === undefined ? {} : { instrumentType: facts.instrumentType }),
+    ...(facts.hasVolume === undefined ? {} : { hasVolume: facts.hasVolume }),
+    ...(facts.hasOpenInterest === undefined ? {} : { hasOpenInterest: facts.hasOpenInterest }),
+    ...(facts.session === undefined ? {} : { session: facts.session }),
+  };
+}
+
 /**
  * The host a backtest is: an instrument record, a clock and a destination.
  *
- * Duty 3 is not served. A backtest holds the chart's own bars and nothing else,
- * so a program that reads another instrument declares a capability this host
- * does not have and is refused at load, by name, rather than drawing a line
- * with nothing in it.
+ * Duty 3 is served only when the caller supplied bars for it. A backtest with
+ * none holds the chart's own bars and nothing else, so a program that reads
+ * another instrument declares a capability this host does not have and is
+ * refused at load, by name, rather than drawing a line with nothing in it.
  */
 function hostFor(
-  settings: BacktestSettings,
+  instrument: Instrument,
+  now: number | null,
   route: (effect: RoutedEffect, bar: number) => void,
+  requestBars: RequestProvider | undefined,
 ): EngineHost {
-  const instrument: Instrument = {
-    ...(settings.contract.symbol === null ? {} : { symbol: settings.contract.symbol }),
-    ...(settings.contract.exchange === null ? {} : { exchange: settings.contract.exchange }),
-    ...(settings.contract.tickSize === null ? {} : { tickSize: settings.contract.tickSize }),
-    ...(settings.contract.lotSize === null ? {} : { lotSize: settings.contract.lotSize }),
-    pointValue: settings.contract.pointValue,
-    currency: settings.contract.currency,
-  };
   return {
     instrument,
-    ...(settings.now === null ? {} : { now: settings.now }),
+    ...(now === null ? {} : { now }),
     route,
+    ...(requestBars === undefined ? {} : { requestBars }),
   };
 }

package/src/core/backtest/index.ts

@@ -14,18 +14,30 @@
  * worsened by a tick and a fill is charged. The engine never adjusts a price and
  * this module never folds one.
  *
- * `backtest` drives one, `replay` folds a stored one's money again from its own
- * fills, and `rerun` executes a stored one again and is held to producing the
- * same bytes. `recordToJson` and `recordFromJson` are the document itself.
- * `compareRuns` puts two records beside each other and says whether the gap
- * between them clears the noise. `caseFilesFrom` is named by the design and is
- * not here yet: it will return text and write nothing, because core does no
- * I/O, and it needs a channel the record does not carry today. `conformance.md`
- * section 2 requires a case to hold `script.os`, the source text, and a record
- * carries only the source's hash, its line count and its file name.
+ * `backtest` drives one against a simulated destination and `backtestSupplied`
+ * drives one over frames somebody else supplied, which is what `conformance.md`
+ * section 3 asks of an engine running a case. `replay` folds a stored one's
+ * money again from its own fills, and `rerun` executes a stored one again and
+ * is held to producing the same bytes. `recordToJson` and `recordFromJson` are
+ * the document itself. `compareRuns` puts two records beside each other and
+ * says whether the gap between them clears the noise. `caseFilesFrom` turns a
+ * record into the files of a conformance case, returning text and writing
+ * nothing because core does no I/O. It needed three channels the record did not
+ * carry. `conformance.md` section 2 requires a case to hold `script.os`, the
+ * source text, and a record carried only the source's hash, its line count and
+ * its file name: record version 2 carries the text, checked against that hash.
+ * The same section says `instrument.json` is the record of `host-interface.md`
+ * 4.1, and a record carried the money layer's contract, which holds six of its
+ * twelve facts: record version 3 carries the record the engine was handed,
+ * whole. And a case is handed frames, which `stdlib.md` 17.7 folds one ledger
+ * field from an instant of: a record carried a frame without the instant it
+ * arrived at, so a case projected from it asserted a field its own input could
+ * not reproduce. Record version 4 carries a frame's time.
  */
-export { backtest } from './drive.js';
-export type { BacktestResult, DriveOptions } from './drive.js';
+export { backtest, backtestSupplied } from './drive.js';
+export type { BacktestResult, DriveOptions, InstrumentFacts } from './drive.js';
+export type { LogLine } from './walk.js';
+export type { Surface } from './drive.js';
 export { declarationOf } from './declaration.js';
 export type { RunDeclaration } from './declaration.js';
 export { marksFor, windowFor } from './range.js';
@@ -35,8 +47,10 @@ export type { ReplayResult } from './replay.js';
 export { testResting } from './resting.js';
 export type { RestOutcome, RestingOrder } from './resting.js';
 export { Simulator } from './simulate.js';
-export type { SimulatorOptions } from './simulate.js';
+export type { SimulatorOptions, VenueAct, VenueDoes, VenuePolicy } from './simulate.js';
 export { DEFAULT_FILL, EXACT, WHOLE_RANGE, checkSettings, settingsFor } from './settings.js';
+export { caseFilesFrom } from './case.js';
+export type { CaseFiles, CaseIdentity, CaseResult } from './case.js';
 export { RECORD_VERSION, barsHash, recordFromJson, recordOf, recordToJson, runBytes } from './record.js';
 export type { RecordParts } from './record.js';
 export type { BacktestSettings, DateRange, FillPolicy, Tolerance } from './settings.js';