openalgo-script 0.4.0 → 0.6.0

package/src/adapters/charts/driving.ts

@@ -0,0 +1,109 @@
+/**
+ * Walking the bars, for a study and for a strategy.
+ *
+ * Split from `run.ts` because they are two things. That file decides what an
+ * engine is loaded with: the host record, the clock, the settings, the venue.
+ * This one decides how the bars are then handed over, and the two differ by
+ * exactly one thing, whether frames have to reach the engine between them.
+ */
+
+import type { CompiledProgram } from '../../core/emit/index.js';
+import type { Engine } from '../../core/engine/index.js';
+import { hostBar, stateFor } from './bars.js';
+import type { ChartBar, ChartCalcContext, ChartSettings } from './contract.js';
+import { stopped } from './errors.js';
+import { signatureOf } from './settings.js';
+import { answersFor } from './venue.js';
+import type { HeldVenue } from './venue.js';
+
+/**
+ * A run in hand, held between a chart's recomputes.
+ *
+ * The signature and the bar times are what a tail run is checked against before
+ * it is trusted: splicing a tail onto a history that has changed underneath it
+ * draws a wrong study that looks entirely plausible.
+ */
+export interface Held {
+  readonly engine: Engine;
+  readonly signature: string;
+  count: number;
+  firstTime: number;
+  lastTime: number;
+  /**
+   * The destination this run's orders go to, for a strategy.
+   *
+   * Held with the engine because the two are one run: the venue holds the
+   * orders that have not filled yet, and an engine continued onto a new bar
+   * against a fresh venue would have its working orders silently forgotten.
+   */
+  readonly venue: HeldVenue | null;
+}
+
+/** A study: every bar in one hand-over, which is what `run` is for. */
+export function runWhole(
+  engine: Engine,
+  bars: readonly ChartBar[],
+  ctx: ChartCalcContext | undefined,
+  program: CompiledProgram,
+  settings: ChartSettings,
+): Held {
+  const result = engine.run(
+    bars.map(hostBar),
+    bars.map((_, index) => stateFor(index, bars, ctx)),
+  );
+  if (result.diagnostic !== undefined) throw stopped(result.diagnostic);
+  return heldFrom(engine, null, bars, program, settings);
+}
+
+/**
+ * A strategy: one bar at a time, with the venue answering between them.
+ *
+ * The order is deliver, execute, then ask. A driver that asked the venue before
+ * executing would price a fill against a bar the strategy had not seen yet, and
+ * one that delivered after executing would let a script read a position its own
+ * order on this bar had just created.
+ *
+ * `supplied` is the whole count rather than the index reached, so `bar.isLast`
+ * means the same on this path as on the one above it: a strategy written to act
+ * on the final bar acts on the final bar, not on every bar in turn.
+ */
+export function walkWith(
+  engine: Engine,
+  held: HeldVenue,
+  bars: readonly ChartBar[],
+  ctx: ChartCalcContext | undefined,
+  program: CompiledProgram,
+  settings: ChartSettings,
+): Held {
+  for (let index = 0; index < bars.length; index += 1) {
+    const bar = bars[index];
+    if (bar === undefined) continue;
+
+    for (const frame of held.pending) engine.deliver(frame);
+    held.pending = [];
+
+    const result = engine.append(hostBar(bar), stateFor(index, bars, ctx), bars.length);
+    if (result.diagnostic !== undefined) throw stopped(result.diagnostic);
+
+    answersFor(held, index);
+  }
+  return heldFrom(engine, held, bars, program, settings);
+}
+
+function heldFrom(
+  engine: Engine,
+  venue: HeldVenue | null,
+  bars: readonly ChartBar[],
+  program: CompiledProgram,
+  settings: ChartSettings,
+): Held {
+  return {
+    engine,
+    venue,
+    signature: signatureOf(program, settings),
+    count: bars.length,
+    firstTime: bars[0]?.time ?? 0,
+    lastTime: bars[bars.length - 1]?.time ?? 0,
+  };
+}
+

package/src/adapters/charts/run.ts

@@ -39,8 +39,14 @@ import type { SourceFile } from '../../core/index.js';
 import { hostBar, hostNow, stateFor } from './bars.js';
 import type { ChartBar, ChartCalcContext, ChartSettings, ChartStore } from './contract.js';
 import { refused, stopped } from './errors.js';
+import { undrawable } from './undrawable.js';
 import { stationIn, stationOf } from './requests.js';
 import { engineSettings, signatureOf } from './settings.js';
+import { answersFor, needsVenue, routeInto, venueFor } from './venue.js';
+import type { HeldVenue } from './venue.js';
+import { runWhole, walkWith } from './driving.js';
+import type { Held } from './driving.js';
+import type { Simulator } from '../../core/backtest/index.js';
 
 /** What a host tells the adapter that neither the chart nor the program says. */
 export interface ChartAdapterOptions {
@@ -116,6 +122,26 @@ export interface ChartAdapterOptions {
    * (`stdlib.md` 17.1), never handed over by the chart.
    */
   readonly orders?: EffectRoute;
+  /**
+   * Run a strategy against a simulated destination where the host gives none.
+   *
+   * **Off by default, because the refusal it replaces is useful.** A strategy
+   * with nowhere to send an order is refused at load with OS6006 naming the
+   * capability, which is exactly what a host that meant to wire a destination
+   * and forgot needs to be told. A chart that quietly filled one in for them
+   * would draw a convincing strategy that routed nothing.
+   *
+   * **On, it is the venue a backtest uses.** A chart drawing a strategy then
+   * fills the same orders at the same prices as the report of the same script,
+   * so the marks on the price and the trades in the report are one answer
+   * rather than two. This is what a host turns on to draw a strategy the way it
+   * draws a study: the plots, the legend row and the settings all follow from
+   * the program running at all.
+   *
+   * It does not place an order anywhere. A host that wants that supplies
+   * `orders`, which wins over this.
+   */
+  readonly simulateOrders?: boolean;
   readonly limits?: Partial<EngineLimits>;
   readonly clock?: Clock;
   /**
@@ -130,14 +156,6 @@ export interface ChartAdapterOptions {
 }
 
 /** The engine one chart instance is holding, between recomputes. */
-interface Held {
-  readonly engine: Engine;
-  readonly signature: string;
-  count: number;
-  firstTime: number;
-  lastTime: number;
-}
-
 /** The store key. Namespaced, because the store belongs to the host as well. */
 const HELD = 'openscript';
 
@@ -168,20 +186,20 @@ export function fullRun(
   options: ChartAdapterOptions,
 ): RunOutput {
   const station = stationIn(store);
-  const engine = start(program, settings, ctx, options, station.provider(bars));
-  const result = engine.run(
-    bars.map(hostBar),
-    bars.map((_, index) => stateFor(index, bars, ctx)),
-  );
-  if (result.diagnostic !== undefined) throw stopped(result.diagnostic);
+  const started = start(program, settings, ctx, options, station.provider(bars), bars);
+  const engine = started.engine;
 
-  const held: Held = {
-    engine,
-    signature: signatureOf(program, settings),
-    count: bars.length,
-    firstTime: bars[0]?.time ?? 0,
-    lastTime: bars[bars.length - 1]?.time ?? 0,
-  };
+  // **A strategy is walked bar by bar and a study is handed the lot.** The
+  // difference is the venue: its frames reach the engine between bars, which is
+  // the only place they can, so a strategy's position is right on the bar after
+  // the one it traded on. `run()` has no gap to put them in.
+  //
+  // It is also the loop the backtest uses, which is the point: a chart drawing a
+  // strategy and a report of the same strategy walk the same bars in the same
+  // order against the same venue, so they cannot disagree about what filled.
+  const held: Held = started.venue === null
+    ? runWhole(engine, bars, ctx, program, settings)
+    : walkWith(engine, started.venue, bars, ctx, program, settings);
   store[HELD] = held;
   station.settle();
   return outputOf(program, engine);
@@ -218,11 +236,29 @@ export function tailRun(
     const bar = bars[index];
     if (bar === undefined) return null;
     const state = stateFor(index, bars, ctx);
+
+    // The venue's answers about the bar before this one, delivered before this
+    // one runs, exactly as the full walk does. A tail that skipped this would
+    // draw the first bars of a strategy correctly and then quietly stop folding
+    // its fills the moment the chart went live, which is the half of the run
+    // nobody re-checks.
+    //
+    // Only when the bar is new. Re-executing the bar that moved must not
+    // deliver again: a frame is cumulative and folding one twice is harmless,
+    // but the bar's own orders have been rolled back and answering them a
+    // second time would fill an order the engine no longer knows it sent.
+    if (held.venue !== null && index !== from) {
+      for (const frame of held.venue.pending) held.engine.deliver(frame);
+      held.venue.pending = [];
+    }
+
     const result =
       index === from
         ? held.engine.update(hostBar(bar), state)
         : held.engine.append(hostBar(bar), state);
     if (result.diagnostic !== undefined) throw stopped(result.diagnostic);
+
+    if (held.venue !== null) answersFor(held.venue, index);
   }
 
   held.count = bars.length;
@@ -257,23 +293,70 @@ function outputOf(program: CompiledProgram, engine: Engine): RunOutput {
   return { columns, tables: engine.tables(), drawings: engine.drawings() };
 }
 
+/** A loaded engine, and the destination its orders go to where it has one. */
+interface Started {
+  readonly engine: Engine;
+  readonly venue: HeldVenue | null;
+}
+
+/**
+ * Load the program, and give a strategy somewhere for its orders to go.
+ *
+ * **The venue is built after the load and reached through a holder, because
+ * neither can come first.** The route has to be handed to `load`, since that is
+ * what declares the `orders` capability and a program needing one is otherwise
+ * refused. The venue has to be built after it, because the declaration it reads
+ * may state its fill rule through an `input()`, and inputs are not resolved
+ * until `load` has run. The route is only ever called from inside an execution,
+ * which is after both, so the holder is always filled by the time anything
+ * reaches it.
+ *
+ * **A host that supplied its own route keeps it.** Somewhere real to send an
+ * order is a better destination than a simulated one, and a host that wired one
+ * up meant it.
+ *
+ * **And simulation is asked for rather than assumed.** Without
+ * `simulateOrders` a strategy with nowhere to send an order is still refused at
+ * load, which is the answer a host that meant to wire a destination and forgot
+ * needs to see. Filling in a venue for them would turn that mistake into a
+ * chart that draws convincingly and routes nothing, discovered whenever
+ * somebody next looked for the orders.
+ */
 function start(
   program: CompiledProgram,
   settings: ChartSettings,
   ctx: ChartCalcContext | undefined,
   options: ChartAdapterOptions,
   requests: RequestProvider,
-): Engine {
+  bars: readonly ChartBar[],
+): Started {
+  const holder: { current: Simulator | null } = { current: null };
+  const simulate = options.simulateOrders === true && options.orders === undefined && needsVenue(program);
+  const withRoute: ChartAdapterOptions = simulate
+    ? { ...options, orders: routeInto(holder) }
+    : options;
+
+  // What this chart has no room for is refused before the engine is asked,
+  // because a study drawn without it is a study that looks broken.
+  const narrower = undrawable(program);
+  if (narrower !== undefined) throw refused(narrower);
+
   const loaded = load(program, {
     settings: engineSettings(program, settings),
-    host: hostFor(ctx, options, requests),
+    host: hostFor(ctx, withRoute, requests),
     time: timeFor(options, ctx?.timezone ?? ''),
     ...(options.limits === undefined ? {} : { limits: options.limits }),
     ...(options.source === undefined ? {} : { source: options.source }),
     ...(options.clock === undefined ? {} : { clock: options.clock }),
   });
   if (!loaded.ok) throw refused(loaded.diagnostic);
-  return loaded.engine;
+
+  if (!simulate) return { engine: loaded.engine, venue: null };
+
+  const venue = venueFor(program, bars, loaded.inputs, instrumentFor(ctx, options));
+  if (venue === null) return { engine: loaded.engine, venue: null };
+  holder.current = venue;
+  return { engine: loaded.engine, venue: { venue, pending: [] } };
 }
 
 /**
@@ -286,12 +369,19 @@ function start(
  * the chart's own sentence in `req.error`, instead of being refused at load
  * with OS6006 naming a capability the chart does have.
  */
-function hostFor(
+/**
+ * The instrument record, from what the host stated and what the chart knows.
+ *
+ * Its own function because two callers need it and they must not each build
+ * one: the engine is loaded with this record, and the venue prices fills
+ * against the tick size in it. Two spellings of the same record is how a fill
+ * gets rounded to a tick the strategy was never told about.
+ */
+function instrumentFor(
   ctx: ChartCalcContext | undefined,
   options: ChartAdapterOptions,
-  requests: RequestProvider,
-): EngineHost {
-  const instrument: Instrument = {
+): Instrument {
+  return {
     ...(options.instrument ?? {}),
     ...(ctx?.symbol === undefined ? {} : { symbol: ctx.symbol }),
     ...(ctx?.interval === undefined ? {} : { interval: ctx.interval }),
@@ -302,6 +392,14 @@ function hostFor(
     // the chart it was drawn on.
     ...(ctx === undefined || ctx.timezone === '' ? {} : { timezone: ctx.timezone }),
   };
+}
+
+function hostFor(
+  ctx: ChartCalcContext | undefined,
+  options: ChartAdapterOptions,
+  requests: RequestProvider,
+): EngineHost {
+  const instrument = instrumentFor(ctx, options);
   return {
     instrument,
     requestBars: requests,

package/src/adapters/charts/tables.ts

@@ -28,25 +28,12 @@
  * direction: a cell nothing was written into is blank, never a zero.
  *
  * **A chart pane holds one grid and the language declares as many as it likes.**
- * The descriptor has one `table` hook, so the first declared grid is the one
- * drawn and any after it are not. That is a gap in the chart's own contract
- * rather than a choice worth making here: there is no second hook to write to,
- * and merging two grids into one would put cells somewhere the script never
- * asked for.
- *
- * **What ought to happen is a refusal, and it cannot be written yet.** A study
- * whose second grid never appears is a study with no explanation, so the second
- * `table()` should be refused where it is written, naming the limit. Every
- * diagnostic in this project carries a catalogue code and the catalogue has
- * none for "the chart cannot draw something this study declares"; inventing one
- * here is the one thing that is not allowed, so the gap is reported instead, in
- * `issues/0011-a-second-declared-grid-is-dropped-with-nothing-said.md`, with the
- * sentence it should carry.
- *
- * Until it lands, the drop is at least no longer silent inside this repository:
- * it is recorded in `spec/chart-narrowings.json` with its reason, and
- * `scripts/check-chart-surface.mjs` fails the build if this adapter ever drops
- * anything else a compiled program declares without recording it there.
+ * The descriptor has one `table` hook, and merging two grids into it would put
+ * cells somewhere the script never asked for. So a program declaring a second
+ * grid never reaches this file: `undrawable.ts` refuses it before any bar runs,
+ * with OS6024, and this reads the one grid a program that runs can have.
+ * `spec/chart-narrowings.json` records the refusal and
+ * `scripts/check-chart-surface.mjs` proves it with a study that declares two.
  */
 import type { CompiledProgram, Grid as DeclaredGrid } from '../../core/emit/index.js';
 import type { Grid, GridCell } from '../../core/engine/index.js';

package/src/adapters/charts/undrawable.ts

@@ -0,0 +1,51 @@
+/**
+ * What this chart cannot draw of what a program declares, refused before a bar.
+ *
+ * `compiled-program.md` section 11: a host draws what its surface has room for,
+ * and refuses what it does not with OS6024 rather than drawing part of a study
+ * and saying nothing. Two things a version 1 program can declare have no place
+ * on this chart's surface, and both used to be dropped in silence.
+ *
+ * - **A second grid.** The descriptor has one `table` hook, so one grid reaches
+ *   a pane. Merging two into it would put cells somewhere the script never
+ *   asked for, and drawing the first alone is a study whose second panel never
+ *   appears and whose cells look broken.
+ * - **A band colour computed per bar.** The chart's band takes one colour for
+ *   the whole run and has no channel to point at, so a band whose colour the
+ *   script computes was drawn in the first plot's colour faded, which is a
+ *   colour the script did not choose.
+ *
+ * The compiled program carries no source position for a declaration, so the
+ * refusal names the declaration by its title, which is what a reader sees in
+ * the legend and the settings dialog, and its span is the load's own.
+ */
+import { diagnosticFor, makeSpan } from '../../core/index.js';
+import type { Diagnostic } from '../../core/index.js';
+import type { CompiledProgram, Field } from '../../core/emit/index.js';
+
+/** A load refusal has no line of its own: the program is what was refused. */
+const AT_LOAD = makeSpan(0, 0, 0, 0);
+
+export function undrawable(program: CompiledProgram): Diagnostic | undefined {
+  const second = program.outputs.tables[1];
+  if (second !== undefined) {
+    return diagnosticFor('OS6024', AT_LOAD, {
+      what: `the table ${titled(second.title, 'after the first')}, the second grid this study declares`,
+      limit: 'a chart pane draws one grid',
+    });
+  }
+  for (const band of program.outputs.fills) {
+    if (band.colorUpChannel !== null || band.colorDownChannel !== null) {
+      return diagnosticFor('OS6024', AT_LOAD, {
+        what: "a band's colour that is computed per bar",
+        limit: "a chart's band takes one colour for the whole run",
+      });
+    }
+  }
+  return undefined;
+}
+
+/** A title as a reader sees it, or a description where it is a setting's. */
+function titled(title: Field, otherwise: string): string {
+  return typeof title === 'string' ? `"${title}"` : otherwise;
+}

package/src/adapters/charts/venue.ts

@@ -0,0 +1,132 @@
+/**
+ * The destination a strategy runs against when a chart draws one.
+ *
+ * **Why a chart needs one at all.** A strategy asks a destination to do things
+ * and folds its position from what comes back. Handed no destination it is
+ * refused at load with OS6006, and handed one that answers nothing it runs but
+ * never learns it is in a position: every `close()` closes nothing, every entry
+ * is allowed again on the next signal, and the study draws a strategy that is
+ * wrong about itself while looking entirely normal. Measured on a stop and
+ * reverse script, that shape produced five buys and no sells.
+ *
+ * **It is the backtest's own venue, not a second one.** `Simulator` is what
+ * `backtest()` runs against, so a chart running a strategy through it fills the
+ * same orders at the same prices as the report the trader ran a moment ago. A
+ * venue written here to be simpler would be a second answer to "what would this
+ * have filled at", and the two would disagree the first time either changed:
+ * the chart would draw one set of trades and the report would list another.
+ *
+ * **What a chart supplies and what it invents.** The bars, the instrument and
+ * the declaration are the chart's own and are passed through. Money is not: a
+ * chart draws a strategy, it does not report one, so the currency, the point
+ * value and the rounding are stated here as the neutral values that make the
+ * accounting a no-op. Nothing a chart draws reads them, and a chart that
+ * guessed a point value would put a wrong profit in front of somebody.
+ *
+ * **Nothing here decides when a fill happens.** The declaration does, through
+ * `fillOn`, and the venue reads it. A market order priced at the next bar's
+ * open is known at that open; one that rested and traded inside a bar is known
+ * once the bar is complete. Both are what a venue could have told anybody at
+ * the time, and that is the whole reason the frames arrive between bars rather
+ * than inside the execution that sent them.
+ */
+
+import { DEFAULT_FILL, Simulator, declarationOf } from '../../core/backtest/index.js';
+import type { RecordedBar } from '../../core/backtest/index.js';
+import type { CompiledProgram } from '../../core/emit/index.js';
+import type { Instrument, OrderFrame, ResolvedInput, RoutedEffect } from '../../core/engine/index.js';
+import type { ChartBar } from './contract.js';
+
+/**
+ * Whether this program needs a destination before it can run at all.
+ *
+ * Read from the program's own declared capabilities rather than from whether
+ * its source said `strategy()`, because `requires` is the same fact the engine
+ * tests at load. A strategy that places no orders needs none, and anything that
+ * does need one is refused without it.
+ */
+export function needsVenue(program: CompiledProgram): boolean {
+  return program.requires.includes('orders');
+}
+
+/** One chart bar as the venue reads it. */
+function recorded(bar: ChartBar): RecordedBar {
+  return {
+    time: bar.time,
+    open: bar.open,
+    high: bar.high,
+    low: bar.low,
+    close: bar.close,
+    volume: bar.volume ?? null,
+    oi: bar.oi ?? null,
+  };
+}
+
+/**
+ * The venue for one chart run, or nothing where the program does not need one.
+ *
+ * `inputs` are the ones the engine resolved at load, because a declaration
+ * field may be written as an `input()`: a script whose `fillOn` comes from a
+ * setting would otherwise be filled the way its source happened to be written
+ * rather than the way the trader is running it.
+ */
+export function venueFor(
+  program: CompiledProgram,
+  bars: readonly ChartBar[],
+  inputs: readonly ResolvedInput[],
+  instrument: Instrument | undefined,
+): Simulator | null {
+  if (!needsVenue(program)) return null;
+
+  const declared = declarationOf(program, inputs);
+
+  return new Simulator({
+    bars: bars.map(recorded),
+    contract: {
+      symbol: instrument?.symbol ?? null,
+      exchange: instrument?.exchange ?? null,
+      // Neutral money. A chart draws a strategy and does not report one, so
+      // nothing it puts on screen reads these; stating a point value a host
+      // never gave would be inventing the size of somebody's position.
+      currency: declared.currency,
+      tickSize: instrument?.tickSize ?? null,
+      lotSize: null,
+      pointValue: 1,
+      digits: 2,
+    },
+    fill: DEFAULT_FILL,
+    // The declaration's own, so slippage is applied the way the backtest
+    // applies it. Ticks, against the instrument's tick size.
+    slippageTicks: declared.slippage,
+    fillOn: declared.fillOn,
+    qtyType: declared.qtyType,
+  });
+}
+
+/**
+ * A venue that can be asked for frames, held across a chart's recomputes.
+ *
+ * The bars a `Simulator` prices against are the ones it was built with, so a
+ * chart that has grown a bar needs a venue that knows about it. `extend` is how
+ * the tail path says so without rebuilding the orders it is already holding.
+ */
+export interface HeldVenue {
+  readonly venue: Simulator;
+  /** Frames the venue answered for a bar, waiting to be delivered before the next. */
+  pending: readonly OrderFrame[];
+}
+
+/** What a venue has to say after one bar, which the next bar's engine reads. */
+export function answersFor(held: HeldVenue, barIndex: number): void {
+  held.pending = held.venue.framesFor(barIndex);
+}
+
+/** The route an engine is loaded with, pointing at a venue built after it. */
+export function routeInto(holder: { current: Simulator | null }): (effect: RoutedEffect, bar: number) => void {
+  // Late bound on purpose. The route is handed to `load`, and the venue cannot
+  // be built until `load` has resolved the inputs the declaration reads. The
+  // route is only ever called from inside an execution, which is after both.
+  return (effect: RoutedEffect, bar: number) => {
+    holder.current?.route(effect, bar);
+  };
+}