openalgo-script 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openalgo-script",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "An open trading language. Write a study or a strategy once, plot it, backtest it, trade it.",
   "keywords": [
     "trading",
@@ -62,11 +62,23 @@
     "check:reproducible": "npm run build && node --disallow-code-generation-from-strings scripts/check-reproducible.mjs",
     "check:section-20": "node --disallow-code-generation-from-strings scripts/check-section-20.mjs",
     "check:entry-points": "npm run build && node --disallow-code-generation-from-strings scripts/check-entry-points.mjs",
-    "test": "node --disallow-code-generation-from-strings scripts/check-duplication.mjs && node --disallow-code-generation-from-strings scripts/check-error-codes.mjs && node --disallow-code-generation-from-strings scripts/check-examples.mjs && node --disallow-code-generation-from-strings scripts/check-catalogue-tests.mjs && node --disallow-code-generation-from-strings scripts/check-layering.mjs && node --disallow-code-generation-from-strings scripts/check-limits.mjs && node --disallow-code-generation-from-strings scripts/check-modularity.mjs && node --disallow-code-generation-from-strings scripts/check-names.mjs && node --disallow-code-generation-from-strings scripts/check-raises.mjs && node --disallow-code-generation-from-strings scripts/check-section-20.mjs && npm run build && node --disallow-code-generation-from-strings scripts/check-defaults.mjs && node --disallow-code-generation-from-strings scripts/check-entry-points.mjs && node --disallow-code-generation-from-strings scripts/check-chart-surface.mjs && npm run test:unit && node --disallow-code-generation-from-strings scripts/check-reproducible.mjs && node --disallow-code-generation-from-strings scripts/check-examples-compile.mjs && node --disallow-code-generation-from-strings scripts/check-no-eval.mjs && npm run bench",
+    "check:number-writer": "node --disallow-code-generation-from-strings scripts/check-number-writer.mjs",
+    "check:python": "node --disallow-code-generation-from-strings scripts/check-python.mjs",
+    "check:format-tables": "npm run build && node --disallow-code-generation-from-strings scripts/check-format-tables.mjs",
+    "check:format-additive": "npm run build && node --disallow-code-generation-from-strings scripts/check-format-additive.mjs",
+    "check:format-corpus": "npm run build && node --disallow-code-generation-from-strings scripts/check-format-corpus.mjs",
+    "check:colour-channels": "npm run build && node --disallow-code-generation-from-strings scripts/check-colour-channels.mjs",
+    "check:vectors": "npm run build && npm run build:test && node --disallow-code-generation-from-strings scripts/check-library-vectors.mjs",
+    "suite": "npm run build && node --disallow-code-generation-from-strings scripts/run-suite.mjs",
+    "suite:engine": "npm run build && node --disallow-code-generation-from-strings scripts/run-suite.mjs --adapter engine/adapter.mjs",
+    "suite:agree": "node --disallow-code-generation-from-strings scripts/run-suite.mjs --adapter scripts/adapter.mjs --against engine/adapter.mjs",
+    "generate:vectors": "npm run build && npm run build:test && node --disallow-code-generation-from-strings scripts/generate-library-vectors.mjs",
+    "test": "node --disallow-code-generation-from-strings scripts/check-duplication.mjs && node --disallow-code-generation-from-strings scripts/check-error-codes.mjs && node --disallow-code-generation-from-strings scripts/check-examples.mjs && node --disallow-code-generation-from-strings scripts/check-catalogue-tests.mjs && node --disallow-code-generation-from-strings scripts/check-layering.mjs && node --disallow-code-generation-from-strings scripts/check-limits.mjs && node --disallow-code-generation-from-strings scripts/check-matrix.mjs && node --disallow-code-generation-from-strings scripts/check-modularity.mjs && node --disallow-code-generation-from-strings scripts/check-names.mjs && node --disallow-code-generation-from-strings scripts/check-raises.mjs && node --disallow-code-generation-from-strings scripts/check-section-20.mjs && node --disallow-code-generation-from-strings scripts/check-number-writer.mjs && node --disallow-code-generation-from-strings scripts/check-python.mjs && npm run build && node --disallow-code-generation-from-strings scripts/check-defaults.mjs && node --disallow-code-generation-from-strings scripts/check-entry-points.mjs && node --disallow-code-generation-from-strings scripts/check-chart-surface.mjs && npm run test:unit && node --disallow-code-generation-from-strings scripts/check-library-vectors.mjs && node --disallow-code-generation-from-strings scripts/check-reproducible.mjs && node --disallow-code-generation-from-strings scripts/check-format-tables.mjs && node --disallow-code-generation-from-strings scripts/check-format-additive.mjs && node --disallow-code-generation-from-strings scripts/check-format-corpus.mjs && node --disallow-code-generation-from-strings scripts/check-colour-channels.mjs && node --disallow-code-generation-from-strings scripts/check-examples-compile.mjs && node --disallow-code-generation-from-strings scripts/harvest-cases.mjs --check && npm run suite:agree && node --disallow-code-generation-from-strings scripts/check-no-eval.mjs && npm run bench",
     "test:unit": "npm run build:test && node --disallow-code-generation-from-strings scripts/run-tests.mjs",
     "check:layering": "node --disallow-code-generation-from-strings scripts/check-layering.mjs",
     "check:duplication": "node --disallow-code-generation-from-strings scripts/check-duplication.mjs",
     "check:limits": "node --disallow-code-generation-from-strings scripts/check-limits.mjs",
+    "check:matrix": "node --disallow-code-generation-from-strings scripts/check-matrix.mjs",
     "check:modularity": "node --disallow-code-generation-from-strings scripts/check-modularity.mjs",
     "generate:errors": "node --disallow-code-generation-from-strings scripts/generate-error-catalogue.mjs",
     "typecheck": "npm run generate && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",

package/spec/README.md

@@ -13,13 +13,14 @@ round.
 | [`host-interface.md`](./host-interface.md) | Everything a platform supplies so an engine can run, and everything the engine hands back: the boundary |
 | [`conformance.md`](./conformance.md) | How the suite is run, and what a passing result entitles an implementation to claim |
 
-Six documents, and the list above is the whole of it. Two more files sit beside
+Six documents, and the list above is the whole of it. Three more sit beside
 them and are not the specification:
 
 | File | Holds |
 |---|---|
 | [`decisions.md`](./decisions.md) | The minutes of every settled cross-document question, and the home register that says which document owns each fact |
 | [`feature-matrix.md`](./feature-matrix.md) | One row per feature: whether it is specified, implemented or planned, the section that defines it, and the test that proves it |
+| [`vectors/`](./vectors/) | Bit patterns a second engine holds itself to without reading this repository's source: `number-text.json`, the boundary cases of `language.md` 5.5 as bit patterns, decimals and text, and `library/`, one file per arithmetic function of the manifest with inputs and results as binary64 bit patterns |
 
 `errors.json` is `errors.md` in machine form, generated from the same entries.
 It is not a document of its own, and a change to one is the same change to the

package/spec/errors.json

@@ -2640,8 +2640,8 @@
         "setting": "the setting that cannot be applied, such as the charge schedule or the comparison tolerance",
         "problem": "what makes it unusable, such as a charge line levied on a line declared after it"
       },
-      "cause": "A run states the settings it is carried out under before its first bar, and a setting that cannot be carried out is refused there rather than quietly producing a figure. A charge line levied on lines not declared before it has no single evaluation order, so two engines would charge two different amounts and both would be defensible. A slippage stated in ticks with no tick size to measure a tick in would charge nothing at all, which is a backtest that lies in the strategy's favour. A comparison tolerance carrying a bound and no reason is a failed comparison somebody switched off.",
-      "fix": "State the setting so it can be carried out: declare a charge line after every line it is levied on, supply the tick size a slippage in ticks is measured in, or write down the reason a tolerance needs a bound. Nothing has been computed at the point this is refused, so correcting the setting and running again costs one run.",
+      "cause": "A run states the settings it is carried out under before its first bar, and a setting that cannot be carried out is refused there rather than quietly producing a figure. A charge line levied on lines not declared before it has no single evaluation order, so two engines would charge two different amounts and both would be defensible. A slippage stated in ticks with no tick size to measure a tick in would charge nothing at all, which is a backtest that lies in the strategy's favour. A comparison tolerance carrying a bound and no reason is a failed comparison somebody switched off, and one past the cap conformance.md section 6 puts on a declared tolerance is a comparison the suite will not accept, so a run that declared one is refused a case rather than written into one that fails every runner it meets.",
+      "fix": "State the setting so it can be carried out: declare a charge line after every line it is levied on, supply the tick size a slippage in ticks is measured in, write down the reason a tolerance needs a bound, or bring a bound past the cap back inside it. Nothing has been computed at the point this is refused, so correcting the setting and running again costs one run.",
       "autofix": false,
       "example": {
         "kind": "transcript",
@@ -3021,7 +3021,7 @@
       "since": 1,
       "message": "This strategy placed an order and the host supplied no destination.",
       "placeholders": {},
-      "cause": "A strategy needs somewhere for orders to go: a paper engine, a backtest simulator or a broker connection. Running one with no destination would compute a position nothing ever took.",
+      "cause": "A strategy needs somewhere for orders to go: a sandbox engine, a backtest simulator or a broker connection. Running one with no destination would compute a position nothing ever took.",
       "fix": "Connect a destination in the host, or run the file as a study(): replace buy() with signal(\"BUY\").",
       "autofix": false,
       "example": {

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

@@ -41,6 +41,11 @@ import type { ChartBar, ChartCalcContext, ChartSettings, ChartStore } from './co
 import { refused, stopped } from './errors.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 +121,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 +155,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 +185,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 +235,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 +292,65 @@ 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;
+
   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 +363,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 +386,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/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);
+  };
+}