openalgo-script 0.2.0 → 0.5.0

package/src/core/backtest/simulate.ts

@@ -0,0 +1,499 @@
+/**
+ * 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.
+ *
+ * **A destination that behaves badly does it on a schedule, stated before the
+ * run and never by chance.** Every case harvested before this one ran against a
+ * venue that filled every order whole and on time, so two engines were proved
+ * to agree about the half of a day that costs nobody anything. The other half
+ * is a partial fill, an order arriving in pieces, a rejection, a cancellation,
+ * an expiry and a fill that turns up after the order has ended, and
+ * `SimulatorOptions.fill` carries the schedule saying which order each of those
+ * happens to and at which boundary. There is no random number here and there
+ * will not be one: `stdlib.md` 8.2 keeps a script that answers differently on a
+ * second run out of a conformance suite, and a venue rolling a die would make
+ * every case it wrote unreproducible in the same breath. **An order the
+ * schedule names is answered by the schedule and by nothing else**, so a run
+ * stating none is the run the cases before this one were harvested from, to the
+ * bit, which is what lets this exist at all.
+ */
+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 this destination does to one order, at one boundary.
+ *
+ * Four words reaching every status of `stdlib.md` 17.7 a host may send. `fill`
+ * carries the cumulative quantity, so one word covers the acknowledgement
+ * before anything has traded, a fill of part of the order and a fill of the
+ * whole of it: `working` and `filled` are that quantity read against the
+ * order's own rather than two instructions. The other three are the three ways
+ * an order ends carrying less than it asked for, and an engine never handed
+ * one has never been asked what it does with the quantity still working.
+ */
+export type VenueDoes = 'fill' | 'reject' | 'cancel' | 'expire';
+
+/** One act of the schedule: what the destination does, to which order, when. */
+export interface VenueAct {
+  /**
+   * The nth order this destination took, counting from one.
+   *
+   * Orders and not intents: a bracket is never taken and a cancellation is
+   * answered without being held, so neither is counted and neither can be named
+   * here. An ordinal for the reason `conformance.md` section 3 gives a case's
+   * own frames: nobody writing a schedule knows the id an engine will mint.
+   */
+  readonly order: number;
+  /**
+   * Boundaries after the one the order arrived at, `0` being that boundary.
+   *
+   * Counted from the order rather than stated as a bar index, because the bar
+   * a strategy decides an order on moves the moment anything else about the run
+   * does, and a schedule in bar indices is one nobody can read back.
+   */
+  readonly afterBars: number;
+  readonly does: VenueDoes;
+  /**
+   * The cumulative quantity a fill reports, in units, or absent for all of it.
+   *
+   * Cumulative because a frame is (`stdlib.md` 17.8): `0` is the
+   * acknowledgement a venue sends before anything has traded, a number below
+   * the order's own is a partial fill, and one at or above it completes the
+   * order. A quantity below what this venue has already reported is a stale
+   * frame, which a venue really sends and the fold has to swallow, so it is
+   * stated here rather than refused.
+   */
+  readonly units?: number | null;
+  /** The destination's own text, which the ledger records against the row. */
+  readonly text?: string;
+}
+
+/**
+ * The fill policy, and what this destination does to the orders it names.
+ *
+ * The schedule sits on the policy because it is the same kind of fact: how this
+ * destination decides a fill, chosen before the first bar and carried in the
+ * record beside the policy's own version, so a stored run replays as it ran.
+ */
+export interface VenuePolicy extends FillPolicy {
+  readonly schedule?: readonly VenueAct[];
+}
+
+/** What the venue prices against and how it decides a fill. */
+export interface SimulatorOptions {
+  readonly bars: readonly RecordedBar[];
+  readonly contract: Contract;
+  readonly fill: VenuePolicy;
+  /** 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;
+  /** The acts the schedule states about this order, in the order they were stated. */
+  readonly acts: readonly VenueAct[];
+  filledQty: number;
+  /** This venue's average over `filledQty`, absent while nothing has filled. */
+  avgPrice: number | null;
+  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';
+
+/**
+ * The word this venue reports each ending under.
+ *
+ * A destination with words of its own maps them onto the vocabulary in its
+ * adapter, which is where `stdlib.md` 17.7 puts the mapping because a status
+ * vocabulary differs per destination. This is this one's, and the whole of what
+ * a schedule's verb means.
+ */
+const ENDED: Readonly<Record<Exclude<VenueDoes, 'fill'>, string>> = {
+  reject: 'rejected',
+  cancel: 'cancelled',
+  expire: 'expired',
+};
+
+/**
+ * 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) {
+        // An order the schedule names is answered by the schedule, whether or
+        // not it is still live: a fill after a cancellation is the one thing
+        // this exists for and the order is dead by then.
+        if (order.acts.length > 0) {
+          if (order.placedOn < barIndex) this.perform(order, bar, barIndex);
+          continue;
+        }
+        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;
+    // The ordinal of this order among the orders taken, which is what an act
+    // names. Read before the order joins them, so the first is one.
+    const ordinal = this.orders.length + 1;
+    const order: Order = {
+      intent,
+      ref: refOf(this.refs),
+      placedOn: barIndex,
+      rest: restingFor(intent),
+      acts: (this.options.fill.schedule ?? []).filter((act) => act.order === ordinal),
+      filledQty: 0,
+      avgPrice: null,
+      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 {
+    // A scheduled order is answered by its schedule from its first breath. The
+    // acknowledgement below is a thing this venue chooses to say, so a schedule
+    // that wants one states it, and one that wants the destination to sit on an
+    // order and say nothing gets that instead.
+    if (order.acts.length > 0) {
+      const bar = this.options.bars[barIndex];
+      if (bar !== undefined) this.perform(order, bar, barIndex);
+      return;
+    }
+    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 qty = this.unitsOf(order.intent);
+    order.filledQty = qty;
+    order.avgPrice = price;
+    order.live = false;
+    this.say(order.intent, order.ref, 'filled', qty, price, barIndex);
+  }
+
+  /**
+   * The acts due at this boundary, in the order the schedule stated them.
+   *
+   * Due is counted from the bar that sent the order, so an act names a moment
+   * in the life of its own order rather than a bar of the run. Two acts due
+   * together are answered as written, which is how a schedule states a
+   * cancellation and the fill that raced it.
+   *
+   * Liveness is not consulted. An order that has ended can still be spoken
+   * about, because the frame that arrives after it ended is the whole reason
+   * this is here: `stdlib.md` 17.8's fill after a terminal status, which a
+   * venue sends whenever a cancel races a fill and which an engine refusing it
+   * loses, leaving a position the strategy cannot see.
+   */
+  private perform(order: Order, bar: RecordedBar, barIndex: number): void {
+    for (const act of order.acts) {
+      if (order.placedOn + act.afterBars !== barIndex) continue;
+      if (act.does === 'fill') {
+        this.report(order, act, bar, barIndex);
+        continue;
+      }
+      // The order ends, reporting what it filled before it ended, because a
+      // frame is cumulative: `stdlib.md` 17.8 has the row keeping the terminal
+      // word and the quantity recording what traded, both true at once.
+      order.live = false;
+      const ended = ENDED[act.does];
+      const price = order.filledQty > 0 ? order.avgPrice : null;
+      this.say(order.intent, order.ref, ended, order.filledQty, price, barIndex, act.text ?? '');
+    }
+  }
+
+  /**
+   * A fill the schedule stated, at this bar's close and worsened like any other.
+   *
+   * **The average is this venue's own, over the cumulative quantity**, the
+   * figure `stdlib.md` 17.8 step 3 says the row takes whole. A venue reporting
+   * the last piece's price and calling it an average hands the engine a number
+   * that is not one, and the engine may not work its own out from two of them,
+   * so the lie settles into the ledger and into every trade folded from it.
+   *
+   * A stated quantity at or below what this venue has already reported adds
+   * nothing and moves nothing: that is a repeated or a stale frame, which a real
+   * destination sends and the fold has to swallow. It carries the average this
+   * venue holds now rather than then, because it keeps no history of its own
+   * averages and the fold ignores the price of a frame adding no quantity. A
+   * bar with no close prices nothing, so an act due at one says nothing rather
+   * than raising a quantity with no price against it, which step 3 refuses.
+   */
+  private report(order: Order, act: VenueAct, bar: RecordedBar, barIndex: number): void {
+    const whole = this.unitsOf(order.intent);
+    const stated = act.units ?? whole;
+    const delta = stated - order.filledQty;
+    if (delta > 0) {
+      if (bar.close === null) return;
+      // Written in this order and left in it: the source order of a sum is
+      // what decides its last bit, and a case harvested from this venue is
+      // asserted to the bit.
+      const price = this.worsen(bar.close, order.intent.side);
+      order.avgPrice = ((order.avgPrice ?? 0) * order.filledQty + price * delta) / stated;
+      order.filledQty = stated;
+      if (order.filledQty >= whole) order.live = false;
+    }
+    // `working` is live and not completely filled, `filled` is the whole
+    // quantity: 17.7's two words read off the quantity rather than stated
+    // twice by a schedule that could disagree with the number beside them.
+    const status = order.filledQty >= whole ? 'filled' : 'working';
+    const price = stated > 0 ? order.avgPrice : null;
+    this.say(order.intent, order.ref, status, stated, price, barIndex, act.text ?? '');
+  }
+
+  /**
+   * The order's quantity in units, which is what a fill is counted in.
+   *
+   * The conversion `complete` did inline, wanted in two places the moment a
+   * schedule can fill an order in pieces: the whole a piece is measured
+   * against has to be the number the fill path would have reported.
+   */
+  private unitsOf(intent: OrderIntent): number {
+    const stated = intent.qty ?? 0;
+    const lot = this.options.contract.lotSize;
+    return this.options.qtyType === 'lots' && lot !== null && lot > 0 ? stated * lot : stated;
+  }
+
+  /**
+   * 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,
+    text = '',
+  ): 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, 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.", 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';

package/src/core/check/library-orders.ts

@@ -240,7 +240,7 @@ const legs: readonly LibraryEntry[] = [
   }),
   entry('leg.stop(name: string, price: number) -> nothing', { ...strategyOnly, planned: true }),
   entry('leg.target(name: string, price: number) -> nothing', { ...strategyOnly, planned: true }),
-  entry('leg.trail(name: string, distance: number, arm?: number = none) -> nothing', {
+  entry('leg.trail(name: string, distance: number, activateAt?: number = none) -> nothing', {
     ...strategyOnly,
     planned: true,
   }),
@@ -258,7 +258,7 @@ const book: readonly LibraryEntry[] = [
   entry('book.stop(amount: number) -> nothing', { ...strategyOnly, planned: true }),
   entry('book.target(amount: number) -> nothing', { ...strategyOnly, planned: true }),
   entry(
-    'book.lockProfit(arm: number, lock: number, step?: number = none, advance?: number = none) -> nothing',
+    'book.lockProfit(activateAt: number, lock: number, step?: number = none, advance?: number = none) -> nothing',
     { ...strategyOnly, planned: true },
   ),
   entry('book.trailStopsToEntry(at: number) -> nothing', { ...strategyOnly, planned: true }),