openalgo-script 0.4.0 → 0.5.0

package/src/core/backtest/simulate.ts

@@ -30,6 +30,21 @@
  * 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';
@@ -38,11 +53,70 @@ 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: FillPolicy;
+  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. */
@@ -64,7 +138,11 @@ interface Order {
   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;
@@ -73,6 +151,20 @@ interface Order {
 /** `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.
  *
@@ -123,6 +215,13 @@ export class Simulator {
     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);
       }
@@ -145,12 +244,17 @@ export class Simulator {
   /** 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,
     };
@@ -188,6 +292,15 @@ export class Simulator {
    * 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;
 
@@ -227,15 +340,96 @@ export class Simulator {
    * 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;
+    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.
    *
@@ -270,6 +464,7 @@ export class Simulator {
     filledQty: number,
     avgFillPrice: number | null,
     barIndex: number,
+    text = '',
   ): void {
     this.seq += 1;
     this.answered.push({
@@ -281,7 +476,7 @@ export class Simulator {
       sentInstrument: intent.instrument,
       sentProduct: intent.product,
       time: this.options.bars[barIndex]?.time ?? null,
-      text: '',
+      text,
       seq: this.seq,
     });
   }

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

@@ -138,7 +138,7 @@ export const ENTRIES = {
   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"] },
+  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"] },

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 }),

package/src/core/check/library-prose.generated.ts

@@ -49,7 +49,7 @@ export const LIBRARY_PROSE: Readonly<Record<string, LibraryProse>> = {
   "book.exit": {"summary":"Exit the whole book as a unit"},
   "book.exitAt": {"summary":"Square off every leg at this `\"HHMM\"` in the chart's timezone"},
   "book.isOpen": {"summary":"Whether any leg holds a position","warmup":"bar 0"},
-  "book.lockProfit": {"summary":"Arm a floor at a profit, then advance it as profit grows"},
+  "book.lockProfit": {"summary":"Activate a floor at a profit, then advance it as profit grows"},
   "book.profit": {"summary":"The book's profit in money, open and realised since it was last flat","warmup":"bar 0"},
   "book.squareOffAtExpiry": {"summary":"Square off a leg this many minutes before its contract expires"},
   "book.stop": {"summary":"Square off every leg when the book's profit falls to `-amount`"},
@@ -332,7 +332,7 @@ export const LIBRARY_PROSE: Readonly<Record<string, LibraryProse>> = {
   "str.split": {"summary":"Split into parts"},
   "str.startsWith": {"summary":"Prefix test"},
   "str.substring": {"summary":"`from` inclusive, `to` exclusive, to the end when `to` is absent"},
-  "str.trim": {"summary":"Leading and trailing spaces removed"},
+  "str.trim": {"summary":"Leading and trailing whitespace removed: the code points listed below"},
   "str.upper": {"summary":"Upper case, invariant, not locale dependent"},
   "sum": {"summary":"Total over the window","warmup":"bar `len - 1`"},
   "sumSkip": {"summary":"Total over the window, ignoring absent bars","warmup":"bar `len - 1`"},

package/src/core/emit/canonical.ts

@@ -1,5 +1,5 @@
 /**
- * The canonical encoding, `compiled-program.md` 2.14.
+ * The canonical encoding, `compiled-program.md` 2.14, and the one number writer.
  *
  * It exists so that a hash of a program means something: two compilers, in two
  * languages, handed the same source, produce the same bytes. So none of the
@@ -9,8 +9,8 @@
  * - Object keys sorted ascending by Unicode code point. Sorted rather than in
  *   the specification's listed order, because a sort is a rule an emitter in any
  *   language can follow without a table.
- * - A number is the shortest decimal string that reads back as the same
- *   binary64 value, with an exponent written as `e` and an optional `-`.
+ * - A number is written by the rule of `language.md` 5.5, which is the same
+ *   rule for every number that becomes text anywhere in the language.
  * - A string escapes only the quote, the backslash and the code points below
  *   0x20, the last as `\u00XX` except for `\n`, `\r` and `\t`.
  */
@@ -18,16 +18,74 @@ import type { CompiledProgram } from './program.js';
 import { sha256 } from './sha256.js';
 
 /**
- * A number, shortest round trip.
+ * A number as text: the one writer.
  *
- * The host's own shortest form is already the shortest that reads back
- * identically. What it is not is the spelling the specification asks for: a
- * positive exponent is written with a `+` that the format does not allow, so
- * that one sign is removed and nothing else is touched.
+ * Two engines compare numbers as bits, but they compare text in a case file, an
+ * expected column, a table cell and `text(x)`, so how a number becomes text has
+ * to be one rule that both implement, and in this repository it has to be one
+ * function. This is that function. `scripts/check-number-writer.mjs` reads
+ * every file under `src` and refuses a conversion outside this module, so a
+ * number cannot reach text by a host's default somewhere else and disagree with
+ * this one by a plus sign.
+ *
+ * **The digits are the host's and the layout is not.** The shortest decimal
+ * digit string that reads back as the same binary64 is what every host this
+ * engine runs on produces, and what a second engine's host produces too; that
+ * part is taken from the host's own shortest form. Where the two hosts part
+ * company is the layout, when a value is written positionally and when with an
+ * exponent, and how the exponent is spelled, so that half is written here from
+ * the rule in `language.md` 5.5 and not left to the host. The rule is the one
+ * the first host follows natively, minus the `+` it writes on a positive
+ * exponent, and `spec/vectors/number-text.json` holds the boundary cases a
+ * second engine checks itself against.
  */
 export function canonicalNumber(value: number): string {
   if (!Number.isFinite(value)) throw new Error('a compiled program holds finite numbers only');
-  return String(value === 0 ? 0 : value).replace('e+', 'e');
+  // Zero and negative zero are one value to the language (compiled-program.md
+  // 3.1) and one spelling here.
+  if (value === 0) return '0';
+  const { digits, point } = shortestDigits(Math.abs(value));
+  return (value < 0 ? '-' : '') + layout(digits, point);
+}
+
+/**
+ * The shortest round trip digits of a positive finite magnitude, and where the
+ * decimal point falls: the value is `0.d1d2...dk` times ten to the `point`.
+ *
+ * Read out of the host's own shortest form rather than computed here, because
+ * the search for the shortest digit string is the one part of the conversion
+ * every host already agrees on. Whatever layout the host chose is undone: the
+ * digits and the point are all that is kept.
+ */
+function shortestDigits(magnitude: number): { readonly digits: string; readonly point: number } {
+  const shown = String(magnitude);
+  const e = shown.indexOf('e');
+  const mantissa = e < 0 ? shown : shown.slice(0, e);
+  const exponent = e < 0 ? 0 : Number(shown.slice(e + 1));
+  const dot = mantissa.indexOf('.');
+  const whole = dot < 0 ? mantissa : mantissa.slice(0, dot);
+  const fraction = dot < 0 ? '' : mantissa.slice(dot + 1);
+  let digits = whole + fraction;
+  let point = whole.length + exponent;
+  // A positional form below one carries leading zeros that are not digits of
+  // the value, and a whole number carries trailing zeros that are its layout.
+  while (digits.startsWith('0')) {
+    digits = digits.slice(1);
+    point -= 1;
+  }
+  while (digits.endsWith('0')) digits = digits.slice(0, -1);
+  return { digits, point };
+}
+
+/** `language.md` 5.5: positional between the two thresholds, an exponent outside them. */
+function layout(digits: string, point: number): string {
+  const count = digits.length;
+  if (count <= point && point <= 21) return digits + '0'.repeat(point - count);
+  if (0 < point && point <= 21) return `${digits.slice(0, point)}.${digits.slice(point)}`;
+  if (-6 < point && point <= 0) return `0.${'0'.repeat(-point)}${digits}`;
+  const exponent = point - 1;
+  const lead = count === 1 ? digits : `${digits[0]}.${digits.slice(1)}`;
+  return `${lead}e${exponent < 0 ? '-' : ''}${String(Math.abs(exponent))}`;
 }
 
 export function canonicalString(value: string): string {

package/src/core/engine/arithmetic.ts

@@ -23,6 +23,7 @@
  * what a script wants when it wraps an index. Collapsing them would silently
  * change one of the two.
  */
+import { compareStrings } from './library/index.js';
 import type { Value } from './values/index.js';
 import { ABSENT, numberValue, valuesEqual } from './values/index.js';
 
@@ -99,12 +100,17 @@ function numeric(
  * absence is treated two ways, and it is deliberate: an operator that can
  * itself be absent gives a script no way to ask whether a value is absent at
  * all, so equality is the exception and every other comparison is not.
+ *
+ * **Two strings are ordered by code point** (`language.md` 9.3, `stdlib.md`
+ * section 10), through the one order `sort` uses, and not by the host's own
+ * operator, which orders by sixteen bit unit and puts a symbol outside the
+ * basic plane below the last thousands of the plane. Numbers take the host's
+ * operator, which is the binary64 order every engine shares.
  */
 export function compare(opcode: 'LT' | 'LE' | 'GT' | 'GE', a: Value, b: Value): Value {
   if (a === null || b === null) return ABSENT;
-  const bothNumbers = typeof a === 'number' && typeof b === 'number';
-  const bothStrings = typeof a === 'string' && typeof b === 'string';
-  if (!bothNumbers && !bothStrings) throw new OperandMismatch(opcode);
+  if (typeof a === 'string' && typeof b === 'string') return ordered(opcode, compareStrings(a, b));
+  if (typeof a !== 'number' || typeof b !== 'number') throw new OperandMismatch(opcode);
   switch (opcode) {
     case 'LT':
       return a < b;
@@ -117,6 +123,20 @@ export function compare(opcode: 'LT' | 'LE' | 'GT' | 'GE', a: Value, b: Value):
   }
 }
 
+/** An ordering comparison read off a three way order: negative, zero or positive. */
+function ordered(opcode: 'LT' | 'LE' | 'GT' | 'GE', order: number): boolean {
+  switch (opcode) {
+    case 'LT':
+      return order < 0;
+    case 'LE':
+      return order <= 0;
+    case 'GT':
+      return order > 0;
+    default:
+      return order >= 0;
+  }
+}
+
 /** `EQ` and `NE` are total: they always produce a boolean. */
 export function equals(a: Value, b: Value): boolean {
   return valuesEqual(a, b);

package/src/core/engine/index.ts

@@ -24,7 +24,7 @@
 export { Engine } from './engine.js';
 export type { BarResult, RunResult } from './results.js';
 
-export { load } from './load.js';
+export { load, loadText } from './load.js';
 export type { LoadOptions, LoadResult } from './load.js';
 
 export type { AlertFiring } from './alerts.js';

package/src/core/engine/library/arrays.ts

@@ -22,6 +22,7 @@ import type { Value } from '../values/index.js';
 import { isNumber, reference, valuesEqual } from '../values/index.js';
 import { entry, refAt, stringAt, valueAt, wholeAt } from './binding.js';
 import type { CallContext, ManifestEntry } from './binding.js';
+import { compareStrings } from './code-points.js';
 import { result } from '../../stdlib/index.js';
 
 /** The array a handle names, or nothing when the handle is absent or stale. */
@@ -68,12 +69,17 @@ function within(
   return index;
 }
 
-/** The order `sort` uses, written down so two engines cannot differ. */
+/**
+ * The order `sort` uses, written down so two engines cannot differ.
+ *
+ * Two strings order by code point (`language.md` 9.3), which is not the order
+ * the host's `<` gives once a string holds a symbol outside the basic plane.
+ */
 function rank(a: Value, b: Value): number {
   if (a === null) return b === null ? 0 : 1;
   if (b === null) return -1;
   if (typeof a === 'number' && typeof b === 'number') return a < b ? -1 : a > b ? 1 : 0;
-  if (typeof a === 'string' && typeof b === 'string') return a < b ? -1 : a > b ? 1 : 0;
+  if (typeof a === 'string' && typeof b === 'string') return compareStrings(a, b);
   if (typeof a === 'boolean' && typeof b === 'boolean') return a === b ? 0 : a ? 1 : -1;
   return 0;
 }

package/src/core/engine/library/code-points.ts

@@ -0,0 +1,73 @@
+/**
+ * The two string rules two engines have to share, written from the page.
+ *
+ * **A string is a sequence of code points** (`compiled-program.md` 3.1), and the
+ * host this engine is written in stores one as sixteen bit units. Every rule
+ * here counts code points and not units, because the two disagree the moment a
+ * string holds a symbol outside the basic plane, and a rule written on the
+ * host's units would be a rule a second engine could not follow.
+ *
+ * **Ordering.** Two strings are ordered by comparing code points from the
+ * front, the first difference deciding, and a string that runs out first
+ * ordering first (`language.md` 9.3, `stdlib.md` section 10). The host's own
+ * `<` orders by unit, which puts every symbol outside the basic plane, stored
+ * as a surrogate pair from U+D800, below the code points from U+E000 to U+FFFF
+ * that come after it, so it is not used.
+ *
+ * **Whitespace.** `str.trim` removes, and `toNumber` ignores, exactly the code
+ * points `stdlib.md` section 10 lists, which are the ones with the Unicode
+ * White_Space property. The host's own `trim` removes a set that is nearly this
+ * one: it takes the byte order mark U+FEFF as well, and a second engine's host
+ * takes the four separators U+001C to U+001F and leaves the byte order mark, so
+ * neither host's default is the set, and the set is implemented from the list.
+ * `tests/engine/strings.test.ts` walks every code point of the basic plane
+ * against the list read out of the page.
+ */
+
+/** The code points `str.trim` removes, as `stdlib.md` section 10 lists them. */
+const WHITESPACE: ReadonlySet<number> = new Set([
+  0x0009, 0x000a, 0x000b, 0x000c, 0x000d, 0x0020, 0x0085, 0x00a0, 0x1680,
+  0x2000, 0x2001, 0x2002, 0x2003, 0x2004, 0x2005, 0x2006, 0x2007, 0x2008, 0x2009, 0x200a,
+  0x2028, 0x2029, 0x202f, 0x205f, 0x3000,
+]);
+
+/** Code points, which is what every index over a string counts. */
+export function points(text: string): string[] {
+  return [...text];
+}
+
+/** Whether one code point is in the trimmed set. */
+export function isWhitespace(point: number): boolean {
+  return WHITESPACE.has(point);
+}
+
+/** `text` with the whitespace of the written set taken off both ends. */
+export function trimmed(text: string): string {
+  const all = points(text);
+  let from = 0;
+  let to = all.length;
+  while (from < to && isWhitespace(all[from]?.codePointAt(0) ?? -1)) from += 1;
+  while (to > from && isWhitespace(all[to - 1]?.codePointAt(0) ?? -1)) to -= 1;
+  return from === 0 && to === all.length ? text : all.slice(from, to).join('');
+}
+
+/**
+ * The order of two strings, negative when `a` comes first, by code point.
+ *
+ * Walked with the string iterator so a surrogate pair is one code point, and
+ * compared as numbers so U+10000 comes after U+FFFF, which is the order the
+ * page states and the one an engine with four byte strings gets for free.
+ */
+export function compareStrings(a: string, b: string): number {
+  const left = a[Symbol.iterator]();
+  const right = b[Symbol.iterator]();
+  for (;;) {
+    const one = left.next();
+    const other = right.next();
+    if (one.done) return other.done ? 0 : -1;
+    if (other.done) return 1;
+    const x = one.value.codePointAt(0) ?? 0;
+    const y = other.value.codePointAt(0) ?? 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+}

package/src/core/engine/library/index.ts

@@ -37,6 +37,12 @@ import { TREND_ENTRIES } from './trend.js';
 import { VOLUME_ENTRIES } from './volume.js';
 import type { ManifestEntry } from './binding.js';
 
+/**
+ * The two string rules, for the operators outside this module and the tests:
+ * `code-points.ts` says why neither is the host's own.
+ */
+export { compareStrings, isWhitespace, trimmed } from './code-points.js';
+
 const ENTRIES: readonly ManifestEntry[] = [
   ...COLOUR_ENTRIES,
   ...MATHS_ENTRIES,