openalgo-script 0.4.0 → 0.5.0

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

@@ -8,34 +8,50 @@
  * one element, or two engines will disagree about the length of a string
  * holding a symbol outside the basic plane and about every substring taken
  * after one. That is what the spread into an array is doing everywhere below:
- * it costs a pass over the string and buys agreement.
+ * it costs a pass over the string and buys agreement. The trimmed set and the
+ * order of two strings are in `code-points.ts`, written from the page.
  *
  * **Number to string is specified, not the host's default.** `text(x)` is the
- * shortest decimal string that reads back as the same binary64 value, which is
- * what this language's own conversion already produces. `text(x, d)` rounds to
- * `d` decimals with halves away from zero and always emits exactly `d` digits
- * after the point, because this is a display conversion and half up is what a
- * reader of a price expects.
+ * rule of `language.md` 5.5 and goes through the one writer that implements
+ * it, `canonicalNumber`, as does every digit this file writes: a host's own
+ * conversion is never asked. `text(x, d)` rounds to `d` decimals with halves
+ * away from zero and always emits exactly `d` digits after the point, because
+ * this is a display conversion and half up is what a reader of a price expects.
  */
-import { roundHalfAway } from '../../stdlib/index.js';
+import { canonicalNumber } from '../../emit/index.js';
+import { roundHalfAway, scaleOf } from '../../stdlib/index.js';
 import type { Value } from '../values/index.js';
 import { isColour, reference } from '../values/index.js';
 import { entry, numberAt, refAt, stringAt, valueAt, wholeAt } from './binding.js';
 import type { CallContext, ManifestEntry } from './binding.js';
+import { points, trimmed } from './code-points.js';
 
 /** A value as `text(x)` spells it. */
 export function spell(ctx: CallContext, value: Value): string {
   if (value === null) return 'none';
-  if (typeof value === 'number') return String(value);
-  if (typeof value === 'boolean') return String(value);
+  if (typeof value === 'number') return canonicalNumber(value);
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
   if (typeof value === 'string') return value;
   if (isColour(value)) {
-    const byte = (x: number): string => x.toString(16).padStart(2, '0');
-    return `#${byte(value.r)}${byte(value.g)}${byte(value.b)}${byte(roundHalfAway(value.a * 255))}`;
+    const alpha = roundHalfAway(value.a * 255);
+    return `#${hexByte(value.r)}${hexByte(value.g)}${hexByte(value.b)}${hexByte(alpha)}`;
   }
   return ctx.heap.get(value.id)?.kind ?? 'none';
 }
 
+/**
+ * A whole number from 0 to 255 as two hex digits, from a table.
+ *
+ * A colour's channels are whole numbers (`compiled-program.md` 3.1), so this
+ * is not the decimal rendering rule and asks no host conversion: each nibble
+ * indexes a string of sixteen characters.
+ */
+const HEX_DIGITS = '0123456789abcdef';
+
+function hexByte(channel: number): string {
+  return `${HEX_DIGITS[channel >> 4] ?? '0'}${HEX_DIGITS[channel & 15] ?? '0'}`;
+}
+
 /** A magnitude as decimal digits, and how many of them fall before the point. */
 interface Spread {
   readonly digits: string;
@@ -108,24 +124,31 @@ function written(of: Spread): string {
  * least one digit, and exactly `d` digits after the point. `spread` is what
  * makes that true of every magnitude rather than of the ones below a threshold.
  *
- * **Past the scaling range the digits are the shortest form's, zero filled.**
- * Scaling by `10 ** d` leaves binary64 altogether for a large enough magnitude
- * or a large enough `d`, and there is nothing to round out there: a binary64 at
- * or above 2 ** 53 is a whole number already, and a decimal place that far from
- * the leading digit is past every digit the value carries. Two engines write
- * the same digits, because the shortest decimal form is what each one's own
- * conversion produces. Inside the range the scaling is what it was, so no value
- * that had an answer has a different one.
+ * **The scale is `round(x, d)`'s**, `scaleOf` from the numeric library, so
+ * the display conversion and the rounding call multiply by one value
+ * (`stdlib.md` 20.7) and cannot part by an ulp at the one count where the
+ * host's power does.
+ *
+ * **The digits are the shortest form's, zero filled, at every magnitude.**
+ * Below 2 ** 53 a rounded whole number has no digits but its own, so nothing
+ * ordinary changes; at or above it the shortest form is what both engines
+ * write, and it is what this uses inside the scaling range as well as past it,
+ * where scaling by ten to the `d` leaves binary64 altogether and there is
+ * nothing to round: a binary64 that large is a whole number already, and a
+ * decimal place that far from the leading digit is past every digit the value
+ * carries. One rule for the digits at every magnitude, rather than the exact
+ * binary expansion below a threshold and the shortest form above it.
  */
 function fixed(x: number, decimals: number): string {
-  const scaled = roundHalfAway(x * Math.pow(10, decimals));
+  const scaled = roundHalfAway(x * scaleOf(decimals));
   const usable = Number.isFinite(scaled);
   const sign = (usable ? scaled < 0 : x < 0) ? '-' : '';
-  // Within the scaling range the whole number's own digits are asked for and
-  // not its shortest form, which drops the low digits of a large one.
+  // The digits are the shortest form's at every magnitude, through the one
+  // writer: a rounded whole below 2 ** 53 has no other digits, and above it
+  // the shortest form is the one rule both engines write (language.md 5.5).
   const magnitude = usable
-    ? spread(Math.abs(scaled).toFixed(0), 0)
-    : spread(Math.abs(x).toString(), decimals);
+    ? spread(canonicalNumber(Math.abs(scaled)), 0)
+    : spread(canonicalNumber(Math.abs(x)), decimals);
   const digits = written(magnitude).padStart(decimals + 1, '0');
   if (decimals === 0) return sign + digits;
   const whole = digits.slice(0, digits.length - decimals);
@@ -143,7 +166,7 @@ function fixed(x: number, decimals: number): string {
  * have. `str.repeat` measures first for the same reason.
  */
 function lengthOf(x: number, decimals: number): number {
-  const before = Math.max(1, spread(Math.abs(x).toString(), 0).point);
+  const before = Math.max(1, spread(canonicalNumber(Math.abs(x)), 0).point);
   return before + decimals + (decimals > 0 ? 1 : 0);
 }
 
@@ -154,22 +177,17 @@ function lengthOf(x: number, decimals: number): number {
  * which accepts hexadecimal, infinities and a bare leading point in some
  * languages and not others. Absence rather than zero for text that is not a
  * number, so a script can tell text that is not a number apart from the number
- * zero.
+ * zero. The whitespace ignored at either end is `str.trim`'s set and no other.
  */
 const NUMERIC = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
 
 function parseNumber(text: string): Value {
-  const trimmed = text.trim();
-  if (!NUMERIC.test(trimmed)) return null;
-  const parsed = Number(trimmed);
+  const bare = trimmed(text);
+  if (!NUMERIC.test(bare)) return null;
+  const parsed = Number(bare);
   return Number.isFinite(parsed) ? (parsed === 0 ? 0 : parsed) : null;
 }
 
-/** Code points, which is what every index in this file counts. */
-function points(text: string): string[] {
-  return [...text];
-}
-
 function makeArray(ctx: CallContext, items: Value[]): Value {
   ctx.guard.array(ctx.span, 'the array', items.length);
   return reference(ctx.heap.allocate({ kind: 'array', items }));
@@ -198,7 +216,7 @@ export const TEXT_ENTRIES: readonly ManifestEntry[] = [
 
   entry('str.upper', 's', (ctx, args) => map(ctx, args, (s) => s.toUpperCase())),
   entry('str.lower', 's', (ctx, args) => map(ctx, args, (s) => s.toLowerCase())),
-  entry('str.trim', 's', (ctx, args) => map(ctx, args, (s) => s.trim())),
+  entry('str.trim', 's', (ctx, args) => map(ctx, args, trimmed)),
 
   entry('str.contains', 's part', (_ctx, args) => pair(args, (s, part) => s.includes(part))),
   entry('str.startsWith', 's part', (_ctx, args) => pair(args, (s, part) => s.startsWith(part))),

package/src/core/engine/load.ts

@@ -10,6 +10,7 @@
  * bar four thousand with half a study on the screen.
  */
 import type { Diagnostic } from '../diagnostics/index.js';
+import { canonicalise } from '../emit/index.js';
 import type { SourceFile } from '../source/index.js';
 import { BAR_FIELDS } from './bars.js';
 import { limitsWith } from './budget.js';
@@ -116,3 +117,70 @@ export function load(program: unknown, options: LoadOptions = {}): LoadResult {
     inputs: resolved.inputs,
   };
 }
+
+/**
+ * Loads a compiled program from text, which is where canonicity is required.
+ *
+ * `load` takes a parsed object because a host that compiled in this process
+ * never serialised, and there is nothing for such an object to be canonical
+ * about. Text is the other boundary, `compiled-program.md` 9.4 step 1 and
+ * section 13 (decision 57): a program an engine reads from outside its process
+ * arrives as the canonical encoding of 2.14, and text that parses to a program
+ * but is not that encoding is refused, because the hash a host recorded was
+ * taken over canonical bytes and text in any other spelling is text that hash
+ * does not name. So the text is parsed, written out again by the one canonical
+ * writer, and the two are compared character for character. Either failure is
+ * OS6018 naming where the text stops being readable or stops being canonical,
+ * counted in characters of the text, which is where an editor's cursor lands.
+ *
+ * What passes here is the object `load` verifies from step 2 on, so every
+ * refusal that applies to an object applies to text as well and in the same
+ * order.
+ */
+export function loadText(text: string, options: LoadOptions = {}): LoadResult {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (thrown) {
+    const message = thrown instanceof Error ? thrown.message : String(thrown);
+    const at = /position (\d+)/.exec(message);
+    return {
+      ok: false,
+      diagnostic: malformed(
+        at === null ? 'the text' : `character ${at[1]}`,
+        'the text stops being the object notation of section 2.14 there, so it is not a program',
+      ),
+    };
+  }
+
+  let canonical: string;
+  try {
+    canonical = canonicalise(parsed);
+  } catch (thrown) {
+    const message = thrown instanceof Error ? thrown.message : String(thrown);
+    return {
+      ok: false,
+      diagnostic: malformed('the text', `it parses but cannot be written in the canonical form: ${message}`),
+    };
+  }
+  if (canonical !== text) {
+    return {
+      ok: false,
+      diagnostic: malformed(
+        `character ${firstDifference(text, canonical)}`,
+        'the text is not the canonical encoding of the program it parses to, and a program ' +
+          'read from outside the process has to be, because that is what its hash was taken over',
+      ),
+    };
+  }
+  return load(parsed, options);
+}
+
+/** Where two texts part, as an index into either, or the shorter one's length. */
+function firstDifference(a: string, b: string): number {
+  const shorter = Math.min(a.length, b.length);
+  for (let i = 0; i < shorter; i += 1) {
+    if (a[i] !== b[i]) return i;
+  }
+  return shorter;
+}

package/src/core/engine/verify-tables.ts

@@ -21,8 +21,51 @@ const META_KINDS = ['study', 'strategy'] as const;
 const CHANNEL_TYPES = ['number', 'string', 'color', 'bool'] as const;
 const EFFECTS = ['none', 'signal', 'order', 'draw', 'log'] as const;
 
+/**
+ * The tables a later minor of this format major added, with the minor that
+ * added each.
+ *
+ * 9.2's rule read from the other side, which 9.4 step 3 states and decision 56
+ * settled: a table a later minor added and an earlier program lacks reads as
+ * empty, never as a refusal, because 9.5's first line is a promise about that
+ * program. A program stamped at this minor or a later one has no such excuse.
+ * Section 2 says an empty table is written as an empty array and never
+ * omitted, so its absence there is the defect check 1 exists for, and the
+ * version is what tells the two apart.
+ *
+ * `spec/format-history.json` records the same additions, one entry per format
+ * version, and `tests/engine/format-minors.test.ts` holds this list to that
+ * file: a table the history says a later minor added has to be one a program
+ * at the earlier minor may lack.
+ */
+const ADDED_AT_MINOR: readonly { readonly table: string; readonly minor: number }[] = [
+  { table: 'requests', minor: 1 },
+];
+
+/** The minor of a `major.minor` the version step has already proved is one. */
+function minorOf(raw: Readonly<Record<string, unknown>>): number {
+  const version = raw['openscript'] as Readonly<Record<string, unknown>>;
+  return Number(String(version['format']).split('.')[1] ?? '0');
+}
+
+/**
+ * Writes the empty table an earlier minor is owed into the program itself.
+ *
+ * Into the object rather than into a local, because every later step reads
+ * the program as its own type and would find the table missing again: the
+ * verifier hands the same object on, and the engine holds it.
+ */
+function supplyAddedTables(raw: Readonly<Record<string, unknown>>): void {
+  const minor = minorOf(raw);
+  for (const added of ADDED_AT_MINOR) {
+    if (raw[added.table] !== undefined || minor >= added.minor) continue;
+    (raw as Record<string, unknown>)[added.table] = [];
+  }
+}
+
 /** Check 1 over every table the machine indexes, and every declaration field. */
 export function checkTables(shape: ShapeCheck, raw: Readonly<Record<string, unknown>>): boolean {
+  supplyAddedTables(raw);
   for (const name of ['requires', 'inputs', 'channels', 'consts', 'series', 'cells', 'states',
     'functions', 'callSites', 'loops', 'code', 'requests']) {
     if (!shape.array(raw[name], name)) return false;

package/src/core/index.ts

@@ -250,10 +250,15 @@ export { DECLARATION_CALLS, declarationDefaultText, namedColour } from './emit/i
  * same check on its own, for a host that keeps compiled programs and wants to
  * refuse a bad one when it arrives rather than when it is first drawn.
  *
+ * `loadText` is `load` for a program that arrives as text, which is the one
+ * boundary where the canonical encoding is required (`compiled-program.md`
+ * section 13): text that parses to a program but is not that encoding is
+ * refused, because the hash a host recorded was taken over canonical bytes.
+ *
  * `capabilitiesFor` and `LANGUAGE_VERSIONS` are this engine's half of the
  * compatibility statement in 9.1, beside `COMPILED_FORMAT_VERSION` above.
  */
-export { load } from './engine/index.js';
+export { load, loadText } from './engine/index.js';
 export type { BarResult, Engine, LoadOptions, LoadResult, RunResult } from './engine/index.js';
 export type {
   BarState,
@@ -311,21 +316,25 @@ export type {
   MonthlyReturn,
   RecordedFill,
   Report,
+  SideAnalysis,
   Summary,
   Trade,
+  TradeAnalysis,
   TradeMarker,
 } from './accounting/index.js';
 export { chargeFor, scheduleFromDeclaration, scheduleProblem } from './accounting/index.js';
 export { markersOf, monthlyOver, reportOf } from './accounting/index.js';
 export { tradesOf } from './accounting/index.js';
-export { equityOver, summaryOf } from './accounting/index.js';
+export { analysisOf, equityOver, summaryOf } from './accounting/index.js';
 export {
   DEFAULT_FILL,
   EXACT,
   WHOLE_RANGE,
   RECORD_VERSION,
   backtest,
+  backtestSupplied,
   barsHash,
+  caseFilesFrom,
   checkSettings,
   compareRuns,
   recordFromJson,
@@ -341,8 +350,13 @@ export type { BacktestResult, ReplayResult, ReportWindow } from './backtest/inde
 export type {
   BacktestSettings,
   BarsInRecord,
+  CaseFiles,
+  CaseIdentity,
+  CaseResult,
   DateRange,
+  DriveOptions,
   FillPolicy,
+  InstrumentFacts,
   RecordedBar,
   RecordedDiagnostic,
   RecordedFrame,

package/src/core/stdlib/index.ts

@@ -105,6 +105,7 @@ export {
   roundTo,
   roundToStep,
   roundToTick,
+  scaleOf,
   sign,
   sin,
   sqrt,

package/src/core/stdlib/maths/index.ts

@@ -18,6 +18,7 @@ export {
   roundTo,
   roundToStep,
   roundToTick,
+  scaleOf,
   trunc,
 } from './rounding.js';
 

package/src/core/stdlib/maths/rounding.ts

@@ -31,6 +31,28 @@ export function round(x: Value): Value {
   return isPresent(x) ? result(roundHalfAway(x)) : NONE;
 }
 
+/**
+ * Ten to each whole power a binary64 can hold, as the binary64 nearest to it.
+ *
+ * `stdlib.md` 20.7: the scale a fixed decimal rounding or conversion multiplies
+ * by is the nearest binary64 to the power of ten, the value the literal `1e23`
+ * reads as, and not what a floating point power returns, which is an ulp away
+ * from it for one count on this engine's host. Built once from exact integer
+ * arithmetic, and it is the one table: `text(x, decimals)` in the engine's
+ * library scales by it through `scaleOf` rather than holding a copy.
+ */
+const POWERS_OF_TEN: readonly number[] = Array.from({ length: 309 }, (_, count) =>
+  Number(10n ** BigInt(count)),
+);
+
+/**
+ * The scale for a digit count: the nearest binary64 to ten to that power, and
+ * past the last finite power the infinity the power would have been.
+ */
+export function scaleOf(decimals: number): number {
+  return POWERS_OF_TEN[decimals] ?? Infinity;
+}
+
 /**
  * `round(x, decimals)`: to a fixed number of decimals, halves away from zero.
  *
@@ -40,7 +62,7 @@ export function round(x: Value): Value {
 export function roundTo(x: Value, decimals: number): Value {
   if (!isPresent(x)) return NONE;
   if (!Number.isInteger(decimals) || decimals < 0) return NONE;
-  const scale = Math.pow(10, decimals);
+  const scale = scaleOf(decimals);
   return result(roundHalfAway(x * scale) / scale);
 }
 

package/src/core/version/version.generated.ts

@@ -4,7 +4,7 @@
 // spec/compiled-program.md, so neither can drift from the thing it names.
 
 /** This build's package version. The release refuses to publish unless the tag, the manifest and this agree. */
-export const VERSION = "0.4.0";
+export const VERSION = "0.5.0";
 
 /**
  * The compiled program format this compiler emits.