openalgo-script 0.2.0 → 0.5.0

package/src/core/backtest/drive.ts

@@ -0,0 +1,468 @@
+/**
+ * The loop: a compiled program, some bars, and the record of what happened.
+ *
+ * **Everything is collected as it arrives.** Each bar hands back what it
+ * applied and what the frames delivered before it did to the ledger, and that
+ * is what the record is built from. Nothing is read back at the end except one
+ * snapshot of the ledger, and that snapshot is copied rather than kept:
+ * `engine.orders()` hands back the ledger's own array, which the fold writes
+ * into and a refused bar truncates, so a driver holding on to it would report
+ * whatever the array happened to say last rather than what the run did.
+ *
+ * **Every bar supplied executes and only the ones inside the window are
+ * reported.** A bar before the window is warmup: it runs, its orders are real,
+ * and a position opened on it is carried in. What it does not get is an equity
+ * point. `range.ts` decides which is which and refuses a window holding no bar
+ * at all, before the first bar rather than after the last.
+ *
+ * **The bar count handed over is the total.** An engine told that each bar is
+ * the only bar reports `bar.isLast` true on every one of them, and a strategy
+ * that flattens on the last bar then flattens on all of them.
+ *
+ * **Frames are delivered at the boundary and folded there.** What the venue
+ * answered after bar k reaches the engine before bar k + 1 executes, which is
+ * where `host-interface.md` 7.4 puts the intake, and the outcome of that fold
+ * 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, Contract, RecordedFill } 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,
+  EngineHost,
+  Instrument,
+  LedgerRow,
+  OrderIntent,
+  RoutedEffect,
+} from '../engine/index.js';
+import { declarationOf } from './declaration.js';
+import type { RunDeclaration } from './declaration.js';
+import { Delivery, framedAs, ordinalsOf } from './deliver.js';
+import type { Delivered, 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 { Simulator } from './simulate.js';
+import { checkSettings } from './settings.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: false; readonly diagnostic: Diagnostic };
+
+/**
+ * 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;
+}
+
+/**
+ * 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
+ * holding no bars are all runs that did not happen, and a record of one would
+ * 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.
+ */
+function drive(
+  program: CompiledProgram,
+  bars: readonly RecordedBar[],
+  settings: BacktestSettings,
+  options: DriveOptions,
+  choose: (declared: RunDeclaration, schedule: ChargeSchedule) => Destination,
+): BacktestResult {
+  const framed = windowFor(bars, settings.range);
+  if (!framed.ok) return { ok: false, diagnostic: framed.diagnostic };
+
+  let sending: Destination | undefined;
+  const instrument = instrumentFor(settings.contract, options.instrument ?? {});
+  const loaded = load(program, {
+    settings: settings.inputs,
+    host: hostFor(instrument, settings.now, (effect, bar) => sending?.route(effect, bar)),
+  });
+  if (!loaded.ok) return { ok: false, diagnostic: loaded.diagnostic };
+
+  const engine = loaded.engine;
+  const declared = declarationOf(engine.program, loaded.inputs);
+  const problem = checkSettings(settings, declared);
+  if (problem !== null) return { ok: false, diagnostic: problem };
+
+  const schedule = scheduleFor(settings, declared);
+  const destination = choose(declared, schedule);
+  sending = destination;
+
+  const run = walk(engine, destination, bars, framed.covered);
+  const ordinals = ordinalsOf(destination.intents);
+  const marks = marksFor(bars, framed.covered);
+
+  return {
+    ok: true,
+    record: recordOf({
+      program: engine.program,
+      ...(options.sourceText === undefined ? {} : { sourceText: options.sourceText }),
+      settings,
+      instrument,
+      bars,
+      form: options.form ?? 'inline',
+      // 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(), destination.intents, ordinals),
+      diagnostics: run.diagnostics,
+      report: reportOf(run.fills, marks, schedule, settings.contract, declared.capital),
+    }),
+  };
+}
+
+/** The simulated destination, as a destination the loop below can drive. */
+function simulated(venue: Simulator): Destination {
+  return {
+    route: (effect, barIndex) => venue.route(effect, barIndex),
+    answers: (barIndex) =>
+      venue.framesFor(barIndex).map((frame) => ({ frame, afterBar: barIndex, row: null })),
+    intents: venue.intents,
+  };
+}
+
+/** 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,
+  destination: Destination,
+  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 = destination.answers(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 ledger at the end, copied out of the engine's own array. */
+function ordersOf(
+  rows: readonly LedgerRow[],
+  intents: readonly OrderIntent[],
+  ordinals: ReadonlyMap<number, number>,
+): readonly RecordedOrder[] {
+  return rows.map((row) => {
+    const intent = intents.find((one) => one.intentId === row.intentId);
+    return orderIn(row, ordinals.get(row.intentId) ?? 0, intent?.qtyType ?? '');
+  });
+}
+
+/**
+ * The cost model the run is carried out under.
+ *
+ * The host's schedule where it supplied one, and otherwise the declaration's
+ * own commission as the one kind of schedule the money layer evaluates. Both
+ * cannot be stated at once: that is OS6023 and it is refused before this is
+ * asked.
+ */
+function scheduleFor(settings: BacktestSettings, declared: RunDeclaration): ChargeSchedule {
+  if (settings.costs !== null) return settings.costs;
+  return scheduleFromDeclaration(
+    declared.commission,
+    declared.commissionType,
+    declared.slippage,
+    settings.contract.currency,
+    settings.contract.digits,
+  );
+}
+
+/**
+ * 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.
+ */
+function hostFor(
+  instrument: Instrument,
+  now: number | null,
+  route: (effect: RoutedEffect, bar: number) => void,
+): EngineHost {
+  return {
+    instrument,
+    ...(now === null ? {} : { now }),
+    route,
+  };
+}

package/src/core/backtest/index.ts

@@ -0,0 +1,64 @@
+/**
+ * The backtest: a program, some bars, and a record of what happened.
+ *
+ * **A run produces a record, and the record is the product.** Not a number
+ * printed at the end and not a chart: a document that carries the program, the
+ * bars, the settings the host chose, every frame the destination answered,
+ * every fill the engine folded, the ledger at the end and the report. A second
+ * engine is handed that document as a conformance case, and this engine is
+ * handed it again months later to prove that an upgrade did not change a result.
+ *
+ * **The cost model lives in this module and not in the engine.** `stdlib.md`
+ * 17.1 puts slippage and commission on the destination, and the engine folds the
+ * price it is told; a backtest is a destination, so this is where a price is
+ * worsened by a tick and a fill is charged. The engine never adjusts a price and
+ * this module never folds one.
+ *
+ * `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, backtestSupplied } from './drive.js';
+export type { BacktestResult, DriveOptions, InstrumentFacts } from './drive.js';
+export { declarationOf } from './declaration.js';
+export type { RunDeclaration } from './declaration.js';
+export { marksFor, windowFor } from './range.js';
+export type { ReportWindow, WindowResult } from './range.js';
+export { replay, rerun } from './replay.js';
+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, 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';
+export type {
+  BarsInRecord,
+  RecordedBar,
+  RecordedDiagnostic,
+  RecordedFrame,
+  RecordedOrder,
+  RunRecord,
+} from './record.js';
+export { compareRuns } from './compare.js';
+export type { RunComparison } from './compare.js';

package/src/core/backtest/range.ts

@@ -0,0 +1,137 @@
+/**
+ * Which bars a report is about, and which merely got it there.
+ *
+ * **Every bar supplied executes, and only some of them are reported.** That is
+ * the whole of this file and it is the fact a driver written without it gets
+ * wrong. A study of the last year needs the indicators warm before the year
+ * starts, so bars before the window are handed to the engine exactly as the
+ * reported ones are: they execute, their orders are real, and a position opened
+ * on one of them is carried into the window rather than appearing from nowhere
+ * at its first bar. What they are not is reported: no equity point, and no
+ * calendar month of their own.
+ *
+ * **A window holding no bar at all is refused**, OS6020, rather than reported
+ * as a flat curve. A flat curve is what a strategy that did nothing also
+ * produces, and only this can tell the two apart.
+ *
+ * **Both bounds are inclusive and are compared against the times of the bars
+ * supplied**, never against a calendar. A window that falls inside a gap in the
+ * data is empty however wide it looks, which is the truthful answer: there are
+ * no bars in it.
+ *
+ * The other fact a driver gets wrong is not a window at all and is written here
+ * because this is where a driver looks: the bar count handed to the engine is
+ * the total it will be given, not the number given so far. An engine told that
+ * each bar is the only bar reports `bar.isLast` true on every one of them, and
+ * a strategy that flattens on the last bar flattens on all of them.
+ */
+import type { BarMark } from '../accounting/index.js';
+import { diagnosticFor } from '../diagnostics/index.js';
+import type { Diagnostic } from '../diagnostics/index.js';
+import type { DateRange } from './settings.js';
+import type { RecordedBar } from './record.js';
+
+/** Which of the bars supplied the report is about. */
+export interface ReportWindow {
+  /** The first reported bar, by index into the bars supplied. */
+  readonly first: number;
+  /** The last reported bar, inclusive. */
+  readonly last: number;
+  /** How many bars run before the first reported one. */
+  readonly warmup: number;
+  /** Every bar supplied, which is what the engine is told a run holds. */
+  readonly total: number;
+}
+
+export type WindowResult =
+  | { readonly ok: true; readonly covered: ReportWindow }
+  | { readonly ok: false; readonly diagnostic: Diagnostic };
+
+/**
+ * The window a range names over the bars supplied.
+ *
+ * A bar with no time is inside an unstated bound and outside a stated one,
+ * because a bound is a comparison and there is nothing to compare it with. A
+ * run over bars none of which carry a time is therefore reported whole when the
+ * host named no range, which is what a host handing over a bare series means,
+ * and refused the moment it names one, which is what a host asking for a window
+ * it cannot be given deserves to be told.
+ */
+export function windowFor(bars: readonly RecordedBar[], range: DateRange): WindowResult {
+  let first = -1;
+  let last = -1;
+  for (let index = 0; index < bars.length; index += 1) {
+    const bar = bars[index];
+    if (bar === undefined || !inside(bar.time, range)) continue;
+    if (first < 0) first = index;
+    last = index;
+  }
+
+  if (first < 0) {
+    return {
+      ok: false,
+      diagnostic: diagnosticFor('OS6020', NO_POSITION, {
+        from: bound(range.from, bars[0]?.time ?? null, 'the first bar supplied'),
+        to: bound(range.to, bars[bars.length - 1]?.time ?? null, 'the last bar supplied'),
+        count: bars.length,
+      }),
+    };
+  }
+
+  return { ok: true, covered: { first, last, warmup: first, total: bars.length } };
+}
+
+/** Whether one bar's own time is inside the window, both bounds inclusive. */
+export function inside(time: number | null, range: DateRange): boolean {
+  if (range.from === null && range.to === null) return true;
+  if (time === null) return false;
+  if (range.from !== null && time < range.from) return false;
+  if (range.to !== null && time > range.to) return false;
+  return true;
+}
+
+/**
+ * Whether a bar is reported, which is the question the marks are built from.
+ *
+ * Asked of an index rather than of a time, because the window is decided once
+ * and a bar asked twice has to be answered the same way both times.
+ */
+export function inReport(index: number, covered: ReportWindow): boolean {
+  return index >= covered.first && index <= covered.last;
+}
+
+/**
+ * The bars as the report marks against them: the close, and whether it counts.
+ *
+ * One mark per bar supplied, warmup included, because the money layer sweeps
+ * the warmup rather than being handed a shortened list: a trade opened before
+ * the window is already in the fold at the window's first point, with its
+ * charges paid and its position marked. A mark says which of the two it is and
+ * the fold decides what to do about it.
+ *
+ * Built here rather than in the driver because a replay marks the same bars the
+ * same way, and two places deciding what a warmup bar is would be two reports
+ * of one run.
+ */
+export function marksFor(bars: readonly RecordedBar[], covered: ReportWindow): readonly BarMark[] {
+  return bars.map((bar, index) => ({
+    barIndex: index,
+    time: bar.time,
+    close: bar.close,
+    inReport: inReport(index, covered),
+  }));
+}
+
+/** What a refusal calls a bound the host left for the bars to decide. */
+function bound(stated: number | null, fallback: number | null, word: string): number | string {
+  if (stated !== null) return stated;
+  return fallback === null ? word : fallback;
+}
+
+/**
+ * Where a refusal about the window points.
+ *
+ * Nowhere in the script, for the same reason every other run setting points
+ * nowhere: the window is the host's choice and the script did not make it.
+ */
+const NO_POSITION: Diagnostic['span'] = { offset: 0, length: 0, line: 0, column: 0 };