openalgo-script 0.2.0 → 0.4.0

package/src/core/backtest/settings.ts

@@ -0,0 +1,280 @@
+/**
+ * What the host chose, which is the half of a run that is not the program.
+ *
+ * **The dividing rule, and everything in this module follows from it: the
+ * record stores what the host chose, and what the program states is stored
+ * once, as the program.** So there is no capital here, no slippage and no
+ * commission: the declaration states those and the declaration is in the
+ * record. A charge schedule the host supplied is here because the host supplied
+ * it; a schedule derived from the declaration is derived again on replay.
+ *
+ * **The fill policy carries its own version** precisely so that a record made
+ * before the policy changed replays as it ran, rather than being quietly re-run
+ * under today's rules and reported as the same study. A policy that could not
+ * say which revision it was would make every stored run a claim about whichever
+ * engine happened to read it last.
+ *
+ * `fillOn` is deliberately not here: it is the declaration's, and the
+ * declaration is the program.
+ *
+ * Two refusals live in this module when the behaviour lands. A setting the run
+ * cannot be carried out under is OS6021, and a supplied schedule beside a
+ * declared commission that is not the default is OS6023, because two cost
+ * models stated at once is a number nobody can explain afterwards.
+ */
+import { scheduleFromDeclaration, scheduleProblem } from '../accounting/index.js';
+import type { ChargeSchedule, Contract } from '../accounting/index.js';
+import { diagnosticFor } from '../diagnostics/index.js';
+import type { Diagnostic } from '../diagnostics/index.js';
+import type { Value } from '../engine/index.js';
+import type { RunDeclaration } from './declaration.js';
+
+/**
+ * Where a refusal about a setting points.
+ *
+ * Nowhere in the script. A run setting is what the host stated before the first
+ * bar, and a caret under a line of the strategy would blame the one party that
+ * did not choose it. The money layer states the same position for the same
+ * reason.
+ */
+const NO_POSITION: Diagnostic['span'] = { offset: 0, length: 0, line: 0, column: 0 };
+
+/** The window of the supplied bars a report is about. */
+export interface DateRange {
+  /** Inclusive, UTC ms; null means the first bar supplied. */
+  readonly from: number | null;
+  /** Inclusive; null means the last. */
+  readonly to: number | null;
+}
+
+/** How a resting order is decided against a bar, and who holds a level. */
+export interface FillPolicy {
+  /** A limit fills only when the bar traded through it. */
+  readonly limitNeedsThrough: boolean;
+  readonly stopFillsAtOpenOnGap: boolean;
+  /** Who holds a bracket's levels; 'destination' until 17.9 exists. */
+  readonly levels: 'destination' | 'engine';
+  /** This policy's own revision, so an old record replays as it ran. */
+  readonly version: number;
+}
+
+/**
+ * How closely two numbers have to agree, and why they are allowed not to.
+ *
+ * Exact by default. A bound that is not zero without a reason beside it is
+ * refused, because a tolerance with no reason is a failed comparison somebody
+ * turned off. The reason a tolerance exists at all is a second implementation,
+ * never this one's own re-run: a rerun of the same record on this engine is
+ * bit-identical or it is a defect.
+ */
+export interface Tolerance {
+  readonly abs: number;
+  readonly rel: number;
+  /** Required whenever either bound is non-zero. */
+  readonly reason: string | null;
+}
+
+/** Everything the host decided about one run. */
+export interface BacktestSettings {
+  readonly range: DateRange;
+  readonly contract: Contract;
+  /** Null derives one from the declaration. */
+  readonly costs: ChargeSchedule | null;
+  readonly fill: FillPolicy;
+  readonly inputs: Readonly<Record<string, Value>>;
+  readonly now: number | null;
+  readonly tolerance: Tolerance;
+}
+
+/**
+ * How a resting order is decided when the host states nothing.
+ *
+ * Conservative on both counts, because a backtest that is wrong is wrong in the
+ * strategy's favour by default: a limit is only filled where the bar traded
+ * through it, so an order resting exactly at the extreme of a bar is not
+ * credited with a fill nobody can prove happened, and a stop that gapped is
+ * filled at the open rather than at its trigger, which is the price a trader
+ * would actually have been given.
+ *
+ * `levels` is `destination` because there is nowhere else for it to be: a
+ * bracket reaches a destination as a protective instruction attached to a tag
+ * and the engine holds no level of its own. The other spelling exists so that a
+ * record made today says which of the two it ran under.
+ *
+ * `version` is this policy's own revision. It travels in the record so that a
+ * run stored before the rules changed replays as it ran rather than being
+ * quietly re-decided under today's.
+ */
+export const DEFAULT_FILL: FillPolicy = {
+  limitNeedsThrough: true,
+  stopFillsAtOpenOnGap: true,
+  levels: 'destination',
+  version: 1,
+};
+
+/** Exact, which is what a comparison is until somebody writes down why it is not. */
+export const EXACT: Tolerance = { abs: 0, rel: 0, reason: null };
+
+/** The whole window of whatever bars were supplied. */
+export const WHOLE_RANGE: DateRange = { from: null, to: null };
+
+/**
+ * The settings a run takes when the host states only the contract.
+ *
+ * Every default here is the absence of a choice rather than a choice made on
+ * the host's behalf: the whole of the bars supplied, no schedule, exact
+ * comparison, no inputs overridden and no clock. A host that wants any of it
+ * different says so, and what it said is what the record stores.
+ *
+ * **The contract is the first argument and cannot be in the second.** The
+ * second was `Partial<BacktestSettings>`, which names a `contract` field that
+ * this function then ignored in favour of the positional one: a caller passing
+ * a contract there silently got the other, and a test written that way passed
+ * while proving nothing. Excluding the field makes it a compiler error at the
+ * call rather than a wrong answer at the end of a run.
+ */
+export function settingsFor(
+  contract: Contract,
+  chosen: Omit<Partial<BacktestSettings>, 'contract'> = {},
+): BacktestSettings {
+  return {
+    range: chosen.range ?? WHOLE_RANGE,
+    contract,
+    costs: chosen.costs ?? null,
+    fill: chosen.fill ?? DEFAULT_FILL,
+    inputs: chosen.inputs ?? {},
+    now: chosen.now ?? null,
+    tolerance: chosen.tolerance ?? EXACT,
+  };
+}
+
+/**
+ * What a run cannot be carried out under, before its first bar.
+ *
+ * Four questions, and every one of them is a figure nobody could explain
+ * afterwards rather than a tidiness rule:
+ *
+ * - **Two cost models at once**, OS6023. A supplied schedule and a declared
+ *   commission describe the same money. Applied together they charge it twice
+ *   and applied one at a time they charge whichever an engine preferred, which
+ *   is a rule nobody wrote down.
+ * - **A schedule that cannot be evaluated**, OS6021, which `scheduleProblem`
+ *   decides, because the schedule is the money layer's and the rule for it is
+ *   written once, there. **Whichever schedule the run will be charged under**,
+ *   which is the declaration's own when the host supplied none: asking only
+ *   about a supplied one left every refusal in the money layer unreachable on
+ *   the path almost every run takes.
+ * - **A quantity in a unit this destination cannot fill**, OS6021. A backtest
+ *   fills in units and works out no running equity, so a quantity in cash or in
+ *   a percentage of equity is one it cannot convert, and a lot needs a lot size
+ *   the instrument may not state.
+ * - **A tolerance with a bound and no reason**, OS6021. A comparison allowed to
+ *   pass by a margin nobody justified is a failed comparison somebody switched
+ *   off, and the reason a tolerance exists at all is a second implementation:
+ *   a rerun of one record on this engine is bit-identical or it is a defect.
+ *
+ * Nothing has been computed when this is asked, so a refusal costs one run
+ * rather than a report a reader has to be told to distrust.
+ */
+export function checkSettings(
+  settings: BacktestSettings,
+  declared: RunDeclaration,
+): Diagnostic | null {
+  if (settings.costs !== null && declared.isStrategy && declared.commission !== 0) {
+    return diagnosticFor('OS6023', NO_POSITION, {
+      commission: declared.commission,
+      commissionType: declared.commissionType,
+    });
+  }
+
+  // Whichever schedule the run will actually be charged under, which is the
+  // declaration's own when the host supplied none. Guarding this on
+  // `settings.costs !== null` left every refusal in the money layer unreachable
+  // on the default path: a declared commission of -5 was charged as a credit
+  // and turned a loss into a gain, with nothing raised anywhere.
+  const schedule = settings.costs ?? scheduleForDeclaration(declared, settings.contract);
+  if (schedule !== null) {
+    const problem = scheduleProblem(schedule, settings.contract);
+    if (problem !== null) return problem;
+  }
+
+  const sizing = sizingProblem(declared, settings.contract);
+  if (sizing !== null) return sizing;
+
+  return toleranceProblem(settings.tolerance);
+}
+
+/** The schedule a run with no host schedule is charged under, or none. */
+function scheduleForDeclaration(
+  declared: RunDeclaration,
+  contract: Contract,
+): ChargeSchedule | null {
+  if (!declared.isStrategy) return null;
+  return scheduleFromDeclaration(
+    declared.commission,
+    declared.commissionType,
+    declared.slippage,
+    contract.currency,
+    contract.digits,
+  );
+}
+
+/**
+ * Whether this destination can fill the unit the strategy sizes in.
+ *
+ * **A quantity is stated in the declaration's own unit and the destination is
+ * the party that converts it** (`host-interface.md` 7.1). This one filled every
+ * order at the number the script wrote, whatever unit it was written in, so a
+ * strategy sizing in lots on a lot of sixty five traded one sixty fifth of what
+ * it asked for and every money figure in the record was out by that factor,
+ * with nothing refused and nothing said. A record like that is worse than a
+ * refused run twice over: somebody trades on the number, and a second engine is
+ * handed it as a conformance case and taught the wrong quantity.
+ *
+ * So: units and lots are converted, and the two that need a running equity this
+ * destination does not hold are refused by name. A refusal costs one run. The
+ * alternative cost a whole report that looked right.
+ */
+function sizingProblem(declared: RunDeclaration, contract: Contract): Diagnostic | null {
+  if (!declared.isStrategy) return null;
+  if (declared.qtyType === 'units' || declared.qtyType === '') return null;
+  if (declared.qtyType === 'lots') {
+    if (contract.lotSize !== null && contract.lotSize > 0) return null;
+    return diagnosticFor('OS6021', NO_POSITION, {
+      setting: 'A quantity stated in lots',
+      problem:
+        'this instrument states no lot size, so there is nothing to convert a lot into',
+    });
+  }
+  return diagnosticFor('OS6021', NO_POSITION, {
+    setting: 'A quantity stated in ' + declared.qtyType,
+    problem:
+      'a backtest fills in units and works out no running equity to size against, so it ' +
+      'cannot convert one. State the quantity in units or in lots',
+  });
+}
+
+/**
+ * A bound, and the reason it is there.
+ *
+ * Both bounds are checked rather than the first one found, because a tolerance
+ * carrying two bounds and one reason is two allowances and one justification.
+ */
+function toleranceProblem(tolerance: Tolerance): Diagnostic | null {
+  const stated = tolerance.reason !== null && tolerance.reason.trim() !== '';
+  const bounded = tolerance.abs !== 0 || tolerance.rel !== 0;
+  if (bounded && !stated) {
+    return diagnosticFor('OS6021', NO_POSITION, {
+      setting: 'The comparison tolerance',
+      problem: 'a bound of ' + String(tolerance.abs) + ' absolute and ' + String(tolerance.rel) +
+        ' relative is stated with no reason beside it',
+    });
+  }
+  if (tolerance.abs < 0 || tolerance.rel < 0) {
+    return diagnosticFor('OS6021', NO_POSITION, {
+      setting: 'The comparison tolerance',
+      problem: 'a bound below zero admits nothing and refuses what is exact',
+    });
+  }
+  return null;
+}

package/src/core/backtest/simulate.ts

@@ -0,0 +1,304 @@
+/**
+ * The destination a backtest runs against: intents in, frames out.
+ *
+ * **This is a host, not part of the engine**, and the division is the one thing
+ * to keep straight while reading it. `stdlib.md` 17.1 puts slippage and
+ * commission on the destination: the engine folds the price it is told and
+ * never adjusts one, so the price worsening below is a venue giving a worse
+ * fill, which is what a venue does, and not an engine moving a number, which is
+ * what the invariant forbids. Everything here could be a broker.
+ *
+ * **A frame is cumulative and reaches the engine between bars.** Every frame
+ * restates the whole life of one order from its beginning, so a repeat costs
+ * nothing, and none of them is handed over during an execution: they are
+ * answered here and collected at the boundary, which is where
+ * `host-interface.md` 7.4 puts the intake.
+ *
+ * **When a fill is known is not when it happened.** A market order decided at
+ * the close of a bar and filled at the next bar's open is known at that open,
+ * so its frame is delivered before that bar executes and the strategy holds the
+ * position for the whole of it. An order that rested and traded somewhere
+ * inside a bar is only known to have traded once that bar is complete, so its
+ * frame is delivered before the bar after it. Both are the truthful reading of
+ * what a venue could have told anybody at the time, and the difference between
+ * them is why they are not folded together.
+ *
+ * **A bracket is answered with nothing at all**, exactly as a venue with no
+ * order to report would answer. A bracket reaches a destination as a protective
+ * instruction attached to a tag and the engine appends no row for it, so there
+ * is nothing for a frame to be about: a fill reported against one would name an
+ * intent no row holds and the fold would refuse it. The row a bracket wants is
+ * decision 55 and it is not in this release, so a stop cannot fill here and a
+ * page that says it can is ahead of the engine.
+ */
+import type { Contract } from '../accounting/index.js';
+import type { OrderFrame, OrderIntent, OrderSide, RoutedEffect } from '../engine/index.js';
+import type { RecordedBar } from './record.js';
+import { testResting } from './resting.js';
+import type { RestingOrder } from './resting.js';
+import type { FillPolicy } from './settings.js';
+
+/** What the venue prices against and how it decides a fill. */
+export interface SimulatorOptions {
+  readonly bars: readonly RecordedBar[];
+  readonly contract: Contract;
+  readonly fill: FillPolicy;
+  /** Adverse always, in ticks, applied to a market fill and to a stop. */
+  readonly slippageTicks: number;
+  /** The declaration's own fill rule: where a market order is priced. */
+  readonly fillOn: string;
+  /**
+   * The unit the declaration's quantity is stated in, `language.md` 13.3.
+   *
+   * Here because converting it is the destination's job and a fill is counted
+   * in units. Only the units this destination can arrive at reach it: the rest
+   * are refused before the first bar by `checkSettings`.
+   */
+  readonly qtyType: string;
+}
+
+/** One order this venue holds, and what it has said about it. */
+interface Order {
+  readonly intent: OrderIntent;
+  readonly ref: string;
+  readonly placedOn: number;
+  /** Absent on a market order, which rests on nothing. */
+  readonly rest: RestingOrder | null;
+  filledQty: number;
+  live: boolean;
+  /** Whether a stop limit has reached its trigger and is now a limit. */
+  triggered: boolean;
+}
+
+/** `language.md` 13.3: a market order priced at the close of its own bar. */
+const AT_CLOSE = 'close';
+
+/**
+ * A venue, for one run.
+ *
+ * It holds the orders it was handed and nothing else: no position, no money and
+ * no view of what the strategy is doing, because a destination has none of
+ * those about somebody else's strategy.
+ */
+export class Simulator {
+  private readonly options: SimulatorOptions;
+  private readonly orders: Order[] = [];
+  /** The intents handed over, in the order they were, whatever became of them. */
+  readonly intents: OrderIntent[] = [];
+  /** Brackets, held so that a run can say how many it was handed and answered. */
+  readonly brackets: OrderIntent[] = [];
+  private queued: Order[] = [];
+  private answered: OrderFrame[] = [];
+  private refs = 0;
+  private seq = 0;
+
+  constructor(options: SimulatorOptions) {
+    this.options = options;
+  }
+
+  /** Step 9: what the strategy decided reaches the venue. */
+  route(effect: RoutedEffect, barIndex: number): void {
+    for (const intent of effect.intents) {
+      this.intents.push(intent);
+      if (intent.kind === 'bracket') {
+        this.brackets.push(intent);
+        continue;
+      }
+      if (intent.kind === 'cancel') {
+        this.withdraw(intent, barIndex);
+        continue;
+      }
+      this.accept(intent, barIndex);
+    }
+  }
+
+  /**
+   * The frames a boundary hands over: everything this venue can say now.
+   *
+   * The orders that were already resting are decided against this bar first and
+   * the orders this bar sent are answered after, which is the order the venue
+   * learned of them in.
+   */
+  framesFor(barIndex: number): readonly OrderFrame[] {
+    const bar = this.options.bars[barIndex];
+    if (bar !== undefined) {
+      for (const order of this.orders) {
+        if (!order.live || order.rest === null || order.placedOn >= barIndex) continue;
+        this.decide(order, bar, barIndex);
+      }
+    }
+
+    const sent = this.queued;
+    this.queued = [];
+    for (const order of sent) this.open(order, barIndex);
+
+    const out = this.answered;
+    this.answered = [];
+    return out;
+  }
+
+  /** How many orders this venue is still holding, which a run reports. */
+  get working(): number {
+    return this.orders.filter((order) => order.live).length;
+  }
+
+  /** An order the strategy sent, which this venue now holds. */
+  private accept(intent: OrderIntent, barIndex: number): void {
+    this.refs += 1;
+    const order: Order = {
+      intent,
+      ref: refOf(this.refs),
+      placedOn: barIndex,
+      rest: restingFor(intent),
+      filledQty: 0,
+      live: true,
+      triggered: false,
+    };
+    this.orders.push(order);
+    this.queued.push(order);
+  }
+
+  /**
+   * A cancellation, which is about the orders a tag names and not about itself.
+   *
+   * Every live order carrying the tag is withdrawn and answered, which is what
+   * releases the position they were claiming, and the cancellation is then
+   * answered as an order of its own, because the engine appended a row for it
+   * and a row nothing ever answers stays at `placed` for the life of the run.
+   */
+  private withdraw(intent: OrderIntent, barIndex: number): void {
+    for (const order of this.orders) {
+      if (!order.live || order.intent.tag !== intent.tag) continue;
+      order.live = false;
+      this.say(order.intent, order.ref, 'cancelled', order.filledQty, null, barIndex);
+    }
+    // The cancellation is confirmed after what it withdrew, which is the order
+    // a venue does it in: the request is answered once it has been carried out.
+    this.refs += 1;
+    this.say(intent, refOf(this.refs), 'cancelled', 0, null, barIndex);
+  }
+
+  /**
+   * The first thing a venue says about an order it has taken.
+   *
+   * A working frame before any fill, because 7.4 asks for a frame on every
+   * change of status and a script waiting for a working order to clear waits
+   * blind without one. A market order is then filled in the same breath where
+   * the declaration prices it at this bar's close, and at the next bar's open
+   * where it does not.
+   */
+  private open(order: Order, barIndex: number): void {
+    this.say(order.intent, order.ref, 'working', 0, null, barIndex);
+    if (order.rest !== null) return;
+
+    const atClose = this.options.fillOn === AT_CLOSE;
+    const bar = this.options.bars[atClose ? barIndex : barIndex + 1];
+    const price = atClose ? (bar?.close ?? null) : (bar?.open ?? null);
+    // A market order sent on the last bar of a run and priced at the next open
+    // has no next open. It stays working and is reported as an order the run
+    // ended holding, which is what it is.
+    if (price === null) return;
+    this.complete(order, this.worsen(price, order.intent.side), barIndex);
+  }
+
+  /** One resting order against one bar. */
+  private decide(order: Order, bar: RecordedBar, barIndex: number): void {
+    const rest = order.rest;
+    if (rest === null) return;
+    const outcome = testResting(order.triggered ? asLimit(rest) : rest, bar, this.options.fill);
+    if (!outcome.filled) {
+      if (outcome.triggered) order.triggered = true;
+      return;
+    }
+    const price = outcome.slips ? this.worsen(outcome.price, order.intent.side) : outcome.price;
+    this.complete(order, price, barIndex);
+  }
+
+  /**
+   * The whole of an order, filled at one price.
+   *
+   * **The quantity is converted into units here, because that is what a fill
+   * is counted in and what every money figure is folded over.** A quantity
+   * travels in the declaration's own unit (`host-interface.md` 7.1) and the
+   * destination is the party that converts it. This filled the number verbatim,
+   * so a strategy sizing in lots on a lot of sixty five traded one sixty fifth
+   * of what it asked for and the whole report was out by that factor. The units
+   * this destination cannot arrive at are refused before the first bar rather
+   * than guessed at here, so by this point the unit is one of two.
+   */
+  private complete(order: Order, price: number, barIndex: number): void {
+    const stated = order.intent.qty ?? 0;
+    const lot = this.options.contract.lotSize;
+    const qty =
+      this.options.qtyType === 'lots' && lot !== null && lot > 0 ? stated * lot : stated;
+    order.filledQty = qty;
+    order.live = false;
+    this.say(order.intent, order.ref, 'filled', qty, price, barIndex);
+  }
+
+  /**
+   * A price worsened by the slippage the run was carried out under.
+   *
+   * **Adverse always: a buy pays more and a sell receives less.** The sign is
+   * taken as written rather than as a magnitude, because a slippage below zero
+   * is refused before the first bar and taking its magnitude here would be this
+   * function quietly covering for a hole in that refusal. It went uncovered for
+   * a while: `scheduleProblem` has always refused a negative rate, and
+   * `checkSettings` asked it only about a schedule the host supplied, so a
+   * declaration stating a slippage of minus one improved both sides of every
+   * fill and the backtest paid the strategy to trade.
+   *
+   * A slippage in ticks with no tick size to measure a tick in charges nothing.
+   * The comment here once said that was refused before the first bar and it was
+   * not; it still is not, because an instrument with no tick is a fact a host
+   * may legitimately not hold, and a run that charges no slippage is a study
+   * before slippage rather than a wrong answer. What has changed is that this
+   * says so instead of claiming a refusal that never existed.
+   */
+  private worsen(price: number, side: OrderSide | null): number {
+    const tick = this.options.contract.tickSize;
+    if (tick === null || this.options.slippageTicks === 0) return price;
+    const move = this.options.slippageTicks * tick;
+    return side === 'sell' ? price - move : price + move;
+  }
+
+  /** One frame, cumulative, in the order this venue spoke. */
+  private say(
+    intent: OrderIntent,
+    ref: string,
+    status: string,
+    filledQty: number,
+    avgFillPrice: number | null,
+    barIndex: number,
+  ): void {
+    this.seq += 1;
+    this.answered.push({
+      intentId: intent.intentId,
+      status,
+      filledQty,
+      avgFillPrice,
+      orderRef: ref,
+      sentInstrument: intent.instrument,
+      sentProduct: intent.product,
+      time: this.options.bars[barIndex]?.time ?? null,
+      text: '',
+      seq: this.seq,
+    });
+  }
+}
+
+/** This venue's own reference for an order, which the engine records and never parses. */
+function refOf(count: number): string {
+  return 'ORD-' + String(count);
+}
+
+/** The resting order an intent is, or nothing where it is a market order. */
+function restingFor(intent: OrderIntent): RestingOrder | null {
+  if (intent.type === null || intent.type === 'market' || intent.side === null) return null;
+  return { side: intent.side, type: intent.type, limit: intent.limit, trigger: intent.trigger };
+}
+
+/** A stop limit that has triggered, which is a limit from that moment on. */
+function asLimit(rest: RestingOrder): RestingOrder {
+  return { side: rest.side, type: 'limit', limit: rest.limit, trigger: null };
+}

package/src/core/catalogue/catalogue.generated.ts

@@ -137,6 +137,10 @@ export const ENTRIES = {
   OS6017: { code: "OS6017", title: "The program's language version is not one this engine implements", severity: "error", stage: "host", since: 1, autofix: false, message: "This program was compiled from language version {found}, and this engine implements {versions}.", fix: "Upgrade the engine to one that implements language version {found}, or recompile the source against a version it has.", placeholders: ["found", "versions"] },
   OS6018: { code: "OS6018", title: "The compiled program is malformed", severity: "error", stage: "host", since: 1, autofix: false, message: "The program failed verification at {location}: {reason}.", fix: "Recompile the script from its source; a program that fails verification came from a broken compiler or was edited after it was written, and neither is repairable by hand.", placeholders: ["location", "reason"] },
   OS6019: { code: "OS6019", title: "A host setting fails the input's validation", severity: "error", stage: "host", since: 1, autofix: false, message: "The host supplied {value} for {key}, and {validation}.", fix: "Correct the value in the settings dialog, or widen the input's own min, max or options so the value is allowed.", placeholders: ["value", "key", "validation"] },
+  OS6020: { code: "OS6020", title: "The report window holds no bars", severity: "error", stage: "host", since: 1, autofix: false, message: "The window from {from} to {to} holds none of the {count} bars supplied.", fix: "Widen the window until it covers bars, or supply the bars it covers. Both bounds are inclusive and are compared against the times of the bars supplied rather than against a calendar, so a window that falls inside a gap in the data is empty however wide it looks.", placeholders: ["from", "to", "count"] },
+  OS6021: { code: "OS6021", title: "A run setting cannot be applied as stated", severity: "error", stage: "host", since: 1, autofix: false, message: "{setting} cannot be applied: {problem}.", 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.", placeholders: ["setting", "problem"] },
+  OS6022: { code: "OS6022", title: "The bars are not the bars the record was made from", severity: "error", stage: "host", since: 1, autofix: false, message: "The bars supplied hash to {found}, and the record was made from {expected}.", fix: "Replay against the bars the record names. Where the revision is the point, make a second record over the revised bars and compare the two runs, rather than overwriting one run with the other under one name.", placeholders: ["found", "expected"] },
+  OS6023: { code: "OS6023", title: "Two cost models are stated at once", severity: "error", stage: "host", since: 1, autofix: false, message: "A charge schedule was supplied, and the declaration states a commission of {commission} in {commissionType}.", fix: "Supply the schedule and leave the declaration's commission at its default of zero, or state the commission in the declaration and supply no schedule. A schedule is the one of the two that can carry a floor, a cap, a charge levied on a charge, and a cost that falls on one side of the trade only.", placeholders: ["commission", "commissionType"] },
   OS7001: { code: "OS7001", title: "Only a strategy can do that", severity: "error", stage: "check", since: 1, autofix: false, message: "{name} is available only in a file declared with strategy().", fix: "Change study(...) on line {line} to strategy(...), or replace {name} with signal(\"...\") to mark the bar without trading.", placeholders: ["name", "line"] },
   OS7002: { code: "OS7002", title: "An order argument is absent", severity: "error", stage: "runtime", since: 1, autofix: false, message: "{name}'s {argument} is absent on this bar.", fix: "Guard the call with isNone({argument}), or supply a fallback with orElse() where one is genuinely correct.", placeholders: ["name", "argument"] },
   OS7003: { code: "OS7003", title: "An order function inside a request expression", severity: "error", stage: "check", since: 1, autofix: false, message: "{name} inside a request expression would place an order from another instrument's bars.", fix: "Read the value with the request, and place the order at the top level from the result.", placeholders: ["name"] },
@@ -154,6 +158,8 @@ export const ENTRIES = {
   OS7015: { code: "OS7015", title: "The strategy has no order destination", severity: "error", stage: "host", since: 1, autofix: false, message: "This strategy placed an order and the host supplied no destination.", fix: "Connect a destination in the host, or run the file as a study(): replace buy() with signal(\"BUY\").", placeholders: [] },
   OS7016: { code: "OS7016", title: "A close names a tag nothing places", severity: "error", stage: "check", since: 1, autofix: false, message: "No order in this file is placed with the tag {tag}.", fix: "Use the tag the entry was placed with, or leave the tag out to flatten the whole leg.", placeholders: ["tag"] },
   OS7017: { code: "OS7017", title: "A close states more than it is closing", severity: "error", stage: "runtime", since: 1, autofix: false, message: "close was given a quantity of {qty}, and {part} has {held} left to close.", fix: "Leave the quantity out and close() flattens what is left, or size the part from pos.size and keep the quantity at or under {held}.", placeholders: ["qty", "part", "held"] },
+  OS7018: { code: "OS7018", title: "A frame names an order this strategy did not place", severity: "error", stage: "host", since: 1, autofix: false, message: "The frame names intent {intent}, and this strategy holds no such order.", fix: "Answer with the intent id the engine sent. A destination's own reference is carried in the frame's reference field, where the engine records it and never parses it, and it is not what an answer is addressed by.", placeholders: ["intent"] },
+  OS7019: { code: "OS7019", title: "A fill was reported with no price", severity: "error", stage: "host", since: 1, autofix: false, message: "The frame reports {qty} filled for intent {intent}, and no average fill price.", fix: "Report the average fill price the destination computed over the cumulative quantity, on every frame that reports a quantity greater than the last one. A frame carrying no new quantity needs no price.", placeholders: ["qty", "intent"] },
   OS8001: { code: "OS8001", title: "A stateful call inside a branch", severity: "warning", stage: "check", since: 1, autofix: false, message: "{name} advances only on the bars where this branch runs, and is absent on the rest.", fix: "Compute it unconditionally at the top level and use the result inside the branch.", placeholders: ["name"] },
   OS8002: { code: "OS8002", title: "A higher timeframe read with onUnconfirmed", severity: "warning", stage: "check", since: 1, autofix: false, message: "This file sets onUnconfirmed = true and reads {timeframe}; together they repaint.", fix: "Drop onUnconfirmed = true, or guard every use of the read with bar.isConfirmed.", placeholders: ["timeframe"] },
   OS8003: { code: "OS8003", title: "No version declaration", severity: "warning", stage: "check", since: 1, autofix: true, message: "This file declares no language version; it was compiled as version {version}.", fix: "Add version {version} as the first line of the file.", placeholders: ["version"] },

package/src/core/catalogue/values.generated.ts

@@ -129,6 +129,10 @@ export interface DiagnosticValues {
   readonly OS6017: { readonly found: PlaceholderValue; readonly versions: PlaceholderValue };
   readonly OS6018: { readonly location: PlaceholderValue; readonly reason: PlaceholderValue };
   readonly OS6019: { readonly value: PlaceholderValue; readonly key: PlaceholderValue; readonly validation: PlaceholderValue };
+  readonly OS6020: { readonly from: PlaceholderValue; readonly to: PlaceholderValue; readonly count: PlaceholderValue };
+  readonly OS6021: { readonly setting: PlaceholderValue; readonly problem: PlaceholderValue };
+  readonly OS6022: { readonly found: PlaceholderValue; readonly expected: PlaceholderValue };
+  readonly OS6023: { readonly commission: PlaceholderValue; readonly commissionType: PlaceholderValue };
   readonly OS7001: { readonly name: PlaceholderValue; readonly line: PlaceholderValue };
   readonly OS7002: { readonly name: PlaceholderValue; readonly argument: PlaceholderValue };
   readonly OS7003: { readonly name: PlaceholderValue };
@@ -146,6 +150,8 @@ export interface DiagnosticValues {
   readonly OS7015: Record<string, never>;
   readonly OS7016: { readonly tag: PlaceholderValue };
   readonly OS7017: { readonly qty: PlaceholderValue; readonly part: PlaceholderValue; readonly held: PlaceholderValue };
+  readonly OS7018: { readonly intent: PlaceholderValue };
+  readonly OS7019: { readonly qty: PlaceholderValue; readonly intent: PlaceholderValue };
   readonly OS8001: { readonly name: PlaceholderValue };
   readonly OS8002: { readonly timeframe: PlaceholderValue };
   readonly OS8003: { readonly version: PlaceholderValue };

package/src/core/check/index.ts

@@ -55,13 +55,16 @@ export type { Warmup } from './warmup.js';
 export { BAR_ZERO, allOf, atBar, atLeastBar, delayed, earlier, isNever, later } from './warmup.js';
 
 export type { LibraryEntry, LibraryParameter, WarmupRule } from './library.js';
+export type { LibraryProse } from './surface.js';
 export {
   NAMESPACES,
   REQUEST_NAMES,
   STRATEGY_NAMESPACES,
+  describedNames,
   isLibraryName,
   isNamespace,
   libraryEntries,
   libraryNames,
   membersOf,
+  proseFor,
 } from './surface.js';