openalgo-script 0.4.0 → 0.6.0

package/dist/core/emit/canonical.js

@@ -1,16 +1,77 @@
 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) {
     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) {
+    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, point) {
+    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) {
     let out = '"';

package/dist/core/emit/canonical.js.map

@@ -1 +1 @@
-{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../../../src/core/emit/canonical.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../../../src/core/emit/canonical.ts"],"names":[],"mappings":"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"}

package/dist/core/engine/arithmetic.d.ts

@@ -1,28 +1,3 @@
-/**
- * The operator instructions, `compiled-program.md` 4.5 to 4.7.
- *
- * Five rules live in this file and nowhere else, which is section 7's claim
- * about the whole language: absence propagates through arithmetic and ordering
- * comparison, is total under equality, is three-valued under `and`, `or` and
- * `not`, and is false at a branch. The last one is `JUMP_FALSE` and is in the
- * machine; the other four are here. An engine that gets all five right has the
- * whole of `language.md` section 6, and an engine that special cases absence
- * anywhere else has a bug.
- *
- * Two details that look like nothing and are not:
- *
- * **Finiteness is checked after each individual operation**, not at the end of
- * an expression, so `(1e308 * 10) / 10` is absent rather than `1e307`. Checking
- * per expression would make the answer depend on where an engine happened to
- * round, which is the whole failure this project exists to prevent.
- *
- * **`MOD` is truncated division and the library's `mod` is floored.** They are
- * different functions with the same name in two places on purpose: the operator
- * follows the sign of its left operand, which is what every language's `%`
- * does, and the library call follows the sign of its right operand, which is
- * what a script wants when it wraps an index. Collapsing them would silently
- * change one of the two.
- */
 import type { Value } from './values/index.js';
 /** Whether a corrupt program reached an operator with tags it cannot take. */
 export declare class OperandMismatch extends Error {
@@ -53,6 +28,12 @@ export declare function negate(a: Value): Value;
  * 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 declare function compare(opcode: 'LT' | 'LE' | 'GT' | 'GE', a: Value, b: Value): Value;
 /** `EQ` and `NE` are total: they always produce a boolean. */

package/dist/core/engine/arithmetic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"arithmetic.d.ts","sourceRoot":"","sources":["../../../src/core/engine/arithmetic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG/C,8EAA8E;AAC9E,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM;CAK3B;AAED;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAK7C;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAElD;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAElD;AAED,iEAAiE;AACjE,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAIhD;AAED,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAInD;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK,CAItC;AAaD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAepF;AAED,8DAA8D;AAC9D,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO,CAElD;AAED,0EAA0E;AAC1E,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK,CAInC;AAED;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAK7C;AAED,iFAAiF;AACjF,wBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAK5C;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAE9C"}
+{"version":3,"file":"arithmetic.d.ts","sourceRoot":"","sources":["../../../src/core/engine/arithmetic.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG/C,8EAA8E;AAC9E,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM;CAK3B;AAED;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAK7C;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAElD;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAElD;AAED,iEAAiE;AACjE,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAIhD;AAED,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAInD;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK,CAItC;AAaD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAcpF;AAgBD,8DAA8D;AAC9D,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO,CAElD;AAED,0EAA0E;AAC1E,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK,CAInC;AAED;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAK7C;AAED,iFAAiF;AACjF,wBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAK5C;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAE9C"}

package/dist/core/engine/arithmetic.js

@@ -1,3 +1,29 @@
+/**
+ * The operator instructions, `compiled-program.md` 4.5 to 4.7.
+ *
+ * Five rules live in this file and nowhere else, which is section 7's claim
+ * about the whole language: absence propagates through arithmetic and ordering
+ * comparison, is total under equality, is three-valued under `and`, `or` and
+ * `not`, and is false at a branch. The last one is `JUMP_FALSE` and is in the
+ * machine; the other four are here. An engine that gets all five right has the
+ * whole of `language.md` section 6, and an engine that special cases absence
+ * anywhere else has a bug.
+ *
+ * Two details that look like nothing and are not:
+ *
+ * **Finiteness is checked after each individual operation**, not at the end of
+ * an expression, so `(1e308 * 10) / 10` is absent rather than `1e307`. Checking
+ * per expression would make the answer depend on where an engine happened to
+ * round, which is the whole failure this project exists to prevent.
+ *
+ * **`MOD` is truncated division and the library's `mod` is floored.** They are
+ * different functions with the same name in two places on purpose: the operator
+ * follows the sign of its left operand, which is what every language's `%`
+ * does, and the library call follows the sign of its right operand, which is
+ * 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 { ABSENT, numberValue, valuesEqual } from './values/index.js';
 /** Whether a corrupt program reached an operator with tags it cannot take. */
 export class OperandMismatch extends Error {
@@ -69,13 +95,19 @@ function numeric(opcode, a, b, of) {
  * 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, a, b) {
     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)
+    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':
@@ -88,6 +120,19 @@ export function compare(opcode, a, b) {
             return a >= b;
     }
 }
+/** An ordering comparison read off a three way order: negative, zero or positive. */
+function ordered(opcode, order) {
+    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, b) {
     return valuesEqual(a, b);

package/dist/core/engine/arithmetic.js.map

@@ -1 +1 @@
-{"version":3,"file":"arithmetic.js","sourceRoot":"","sources":["../../../src/core/engine/arithmetic.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErE,8EAA8E;AAC9E,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,MAAM,CAAS;IAExB,YAAY,MAAc;QACxB,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,GAAG,CAAC,CAAQ,EAAE,CAAQ;IACpC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC5C,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9E,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACjE,MAAM,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,CAAQ,EAAE,CAAQ;IACzC,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,CAAQ,EAAE,CAAQ;IACzC,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,MAAM,CAAC,CAAQ,EAAE,CAAQ;IACvC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC5C,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,MAAM,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;IACrF,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,SAAS,CAAC,CAAQ,EAAE,CAAQ;IAC1C,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC5C,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,MAAM,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;IACrF,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,CAAQ;IAC7B,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC9B,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,MAAM,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;IAC5D,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,OAAO,CACd,MAAc,EACd,CAAQ,EACR,CAAQ,EACR,EAAoC;IAEpC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC5C,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,MAAM,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC;IACtF,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,OAAO,CAAC,MAAiC,EAAE,CAAQ,EAAE,CAAQ;IAC3E,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC5C,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,CAAC;IACnE,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,CAAC;IACnE,IAAI,CAAC,WAAW,IAAI,CAAC,WAAW;QAAE,MAAM,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC;IACpE,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,IAAI;YACP,OAAO,CAAC,GAAG,CAAC,CAAC;QACf,KAAK,IAAI;YACP,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,KAAK,IAAI;YACP,OAAO,CAAC,GAAG,CAAC,CAAC;QACf;YACE,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,MAAM,CAAC,CAAQ,EAAE,CAAQ;IACvC,OAAO,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC3B,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,GAAG,CAAC,CAAQ;IAC1B,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC9B,IAAI,OAAO,CAAC,KAAK,SAAS;QAAE,MAAM,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;IAC7D,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,GAAG,CAAC,CAAQ,EAAE,CAAQ;IACpC,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAC7C,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC5C,IAAI,OAAO,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,SAAS;QAAE,MAAM,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;IACvF,OAAO,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,EAAE,CAAC,CAAQ,EAAE,CAAQ;IACnC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC5C,IAAI,OAAO,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,SAAS;QAAE,MAAM,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;IACtF,OAAO,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAY;IACnC,OAAO,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,IAAI,CAAC;AAC3C,CAAC"}
+{"version":3,"file":"arithmetic.js","sourceRoot":"","sources":["../../../src/core/engine/arithmetic.ts"],"names":[],"mappings":"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"}

package/dist/core/engine/bar-source.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Where the bars a run reads come from: an array of records, or columns.
+ *
+ * The bar cycle reads one bar at a time and does not care where its fields come
+ * from, so the representation is decided at the door and nowhere else. Two are
+ * accepted (issue 0005):
+ *
+ * - **Records**, one `HostBar` per bar, which is the live path: one bar arrives
+ *   at a time and an array of one is absurd.
+ * - **Columns**, one array per field, owned by the host. A long history held as
+ *   columns costs about a third of the memory of one object per bar and no
+ *   allocation per bar at rest, and a store that already holds bars as columns
+ *   can hand over typed array views with no parse at all. The engine reads
+ *   `open[i]` when bar `i` executes and builds the one record that execution
+ *   needs, which is gone by the next bar.
+ *
+ * **In a column, absence is `null` or `NaN`.** A typed array cannot hold `null`,
+ * and a price the host does not have is absent, never zero (`host-interface.md`
+ * 3.1), so `NaN` is the typed array's spelling of it. A time that is `NaN` is a
+ * bar with no time, which the hand-over refuses with OS6025 exactly as it
+ * refuses a record with none.
+ *
+ * **The number of bars is the length of `time`.** A shorter price, volume or
+ * interest column reads as absent past its end, which is the same thing a hole in
+ * a record is, and nothing is invented to fill it.
+ */
+import type { HostBar } from './bars.js';
+/** Numbers by bar index, absent written as `null` or `NaN`. */
+export type BarColumn = ArrayLike<number | null>;
+/** A history as columns, one per field of `host-interface.md` 3.1. */
+export interface BarColumns {
+    readonly time: BarColumn;
+    readonly open: BarColumn;
+    readonly high: BarColumn;
+    readonly low: BarColumn;
+    readonly close: BarColumn;
+    readonly volume?: BarColumn;
+    readonly oi?: BarColumn;
+}
+/** What the bar cycle and the fold read: how many bars, and bar `i`. */
+export interface BarSource {
+    readonly length: number;
+    at(index: number): HostBar | undefined;
+}
+export declare function isColumns(bars: readonly HostBar[] | BarColumns): bars is BarColumns;
+/** Either form, as the bar cycle and the fold read it. */
+export declare function sourceOf(bars: readonly HostBar[] | BarColumns): BarSource;
+export declare function recordSource(bars: readonly HostBar[]): BarSource;
+export declare function columnSource(columns: BarColumns): BarSource;
+/**
+ * The bars a run has been handed: a whole history, then whatever arrives live.
+ *
+ * `run` replaces the history; `append` and `update` write one bar over it. A
+ * bar written live is held as the record it arrived as, which is the only form
+ * a live bar has.
+ */
+export declare class KnownBars implements BarSource {
+    private base;
+    private readonly live;
+    get length(): number;
+    at(index: number): HostBar | undefined;
+    set(index: number, bar: HostBar): void;
+    reset(base: BarSource): void;
+}
+//# sourceMappingURL=bar-source.d.ts.map

package/dist/core/engine/bar-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bar-source.d.ts","sourceRoot":"","sources":["../../../src/core/engine/bar-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,+DAA+D;AAC/D,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAEjD,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC;CACzB;AAED,wEAAwE;AACxE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACxC;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,UAAU,GAAG,IAAI,IAAI,UAAU,CAEnF;AAED,0DAA0D;AAC1D,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,UAAU,GAAG,SAAS,CAEzE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,CAEhE;AAOD,wBAAgB,YAAY,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAiB3D;AAED;;;;;;GAMG;AACH,qBAAa,SAAU,YAAW,SAAS;IACzC,OAAO,CAAC,IAAI,CAA+B;IAC3C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IAEtC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAItC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI;IAItC,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;CAI7B"}

package/dist/core/engine/bar-source.js

@@ -0,0 +1,58 @@
+export function isColumns(bars) {
+    return !Array.isArray(bars);
+}
+/** Either form, as the bar cycle and the fold read it. */
+export function sourceOf(bars) {
+    return isColumns(bars) ? columnSource(bars) : recordSource(bars);
+}
+export function recordSource(bars) {
+    return { get length() { return bars.length; }, at: (index) => bars[index] };
+}
+function cell(column, index) {
+    const value = column === undefined || index >= column.length ? null : column[index];
+    return value === null || value === undefined || Number.isNaN(value) ? null : value;
+}
+export function columnSource(columns) {
+    const length = columns.time.length;
+    return {
+        length,
+        at(index) {
+            if (index < 0 || index >= length)
+                return undefined;
+            return {
+                time: cell(columns.time, index),
+                open: cell(columns.open, index),
+                high: cell(columns.high, index),
+                low: cell(columns.low, index),
+                close: cell(columns.close, index),
+                volume: cell(columns.volume, index),
+                oi: cell(columns.oi, index),
+            };
+        },
+    };
+}
+/**
+ * The bars a run has been handed: a whole history, then whatever arrives live.
+ *
+ * `run` replaces the history; `append` and `update` write one bar over it. A
+ * bar written live is held as the record it arrived as, which is the only form
+ * a live bar has.
+ */
+export class KnownBars {
+    base = recordSource([]);
+    live = [];
+    get length() {
+        return Math.max(this.base.length, this.live.length);
+    }
+    at(index) {
+        return this.live[index] ?? this.base.at(index);
+    }
+    set(index, bar) {
+        this.live[index] = bar;
+    }
+    reset(base) {
+        this.base = base;
+        this.live.length = 0;
+    }
+}
+//# sourceMappingURL=bar-source.js.map

package/dist/core/engine/bar-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bar-source.js","sourceRoot":"","sources":["../../../src/core/engine/bar-source.ts"],"names":[],"mappings":"AAgDA,MAAM,UAAU,SAAS,CAAC,IAAqC;IAC7D,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,QAAQ,CAAC,IAAqC;IAC5D,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAwB;IACnD,OAAO,EAAE,IAAI,MAAM,KAAK,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;AAC9E,CAAC;AAED,SAAS,IAAI,CAAC,MAA6B,EAAE,KAAa;IACxD,MAAM,KAAK,GAAG,MAAM,KAAK,SAAS,IAAI,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpF,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;AACrF,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAmB;IAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;IACnC,OAAO;QACL,MAAM;QACN,EAAE,CAAC,KAAa;YACd,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,IAAI,MAAM;gBAAE,OAAO,SAAS,CAAC;YACnD,OAAO;gBACL,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;gBAC/B,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;gBAC/B,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;gBAC/B,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC;gBAC7B,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;gBACjC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC;gBACnC,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC;aAC5B,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,SAAS;IACZ,IAAI,GAAc,YAAY,CAAC,EAAE,CAAC,CAAC;IAC1B,IAAI,GAAc,EAAE,CAAC;IAEtC,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACtD,CAAC;IAED,EAAE,CAAC,KAAa;QACd,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IACjD,CAAC;IAED,GAAG,CAAC,KAAa,EAAE,GAAY;QAC7B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,IAAe;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IACvB,CAAC;CACF"}

package/dist/core/engine/engine.d.ts

@@ -6,6 +6,7 @@ import type { Grid } from './grids.js';
 import type { LedgerRow, OrderFrame } from './ledger/index.js';
 import type { CompiledProgram } from './types.js';
 import type { RequestPlan } from './request-plan.js';
+import type { BarColumns } from './bar-source.js';
 import type { Value } from './values/index.js';
 import type { Drawing } from './drawings.js';
 import type { BarResult, RunResult } from './results.js';
@@ -47,7 +48,7 @@ export declare class Engine {
      * chart bar is inside, and on a live feed there is nothing there yet. That is
      * the mode repainting on history, permanently and by design.
      */
-    private known;
+    private readonly known;
     private supplied;
     private index;
     private updates;
@@ -96,7 +97,12 @@ export declare class Engine {
      * pane with nothing drawn on it is what a study that computed nothing also
      * produces and only the engine can tell the two apart.
      */
-    run(bars: readonly HostBar[], states?: readonly BarState[]): RunResult;
+    run(bars: readonly HostBar[] | BarColumns, states?: readonly BarState[]): RunResult;
+    /**
+     * The dataset a driver appends one bar at a time, handed to the fold before
+     * bar 0 as `run` hands it, so a `"lookahead"` read reads it as history.
+     */
+    history(bars: readonly HostBar[] | BarColumns): void;
     /**
      * A frame from the destination, `host-interface.md` 7.2. Held until the next
      * bar begins rather than folded where it lands: nothing reaches a running
@@ -107,15 +113,6 @@ export declare class Engine {
     /** The strategy's own ledger, `stdlib.md` 17.7, oldest row first. */
     orders(): readonly LedgerRow[];
     private execute;
-    /**
-     * A bar that failed.
-     *
-     * Steps 7 to 11 do not run, the bar's output columns keep whatever the
-     * previous execution published or stay absent, and the engine reports the
-     * error with its code and source position. It does not continue to the next
-     * bar with a half executed state, so the journal is rolled back and the
-     * script is marked stopped.
-     */
     /**
      * A hand-over the engine refuses, before any of it has been executed.
      *
@@ -126,6 +123,7 @@ export declare class Engine {
      * state nobody can account for.
      */
     private refuse;
+    /** A bar that failed: steps 7 to 11 do not run, the journal rolls back, the script stops. */
     private stopped;
     /** Step 11, and the sweep that pays for the objects the bar left behind. */
     private checkpoint;

package/dist/core/engine/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/core/engine/engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/core/engine/engine.ts"],"names":[],"mappings":"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"}

package/dist/core/engine/engine.js

@@ -13,7 +13,8 @@ import { Registers } from './registers.js';
 import { Grids } from './grids.js';
 import { ledgerFor, routedEffects } from './orders.js';
 import { NO_SESSION, sessionReader } from './session/index.js';
-import { noBars, outOfOrder } from './series.js';
+import { handOver, noBars } from './series.js';
+import { KnownBars, sourceOf } from './bar-source.js';
 import { barMinutesOf } from './timeframe.js';
 import { RequestSet } from './requests.js';
 import { Heap } from './values/index.js';
@@ -56,7 +57,7 @@ export class Engine {
      * chart bar is inside, and on a live feed there is nothing there yet. That is
      * the mode repainting on history, permanently and by design.
      */
-    known = [];
+    known = new KnownBars();
     supplied = 0;
     index = -1;
     updates = 0;
@@ -155,7 +156,7 @@ export class Engine {
         // that has already failed keeps the failure it has, which is the one that
         // explains what went wrong first.
         if (this.failure === undefined) {
-            const problem = outOfOrder(bar, this.known[this.index], this.index + 1);
+            const problem = handOver(bar, this.known.at(this.index), this.index + 1);
             if (problem !== undefined)
                 return this.refuse(problem);
         }
@@ -167,7 +168,7 @@ export class Engine {
         this.started = true;
         this.previousClose = this.lastClose;
         if (this.known.length <= this.index)
-            this.known[this.index] = bar;
+            this.known.set(this.index, bar);
         return this.execute(bar, state, true);
     }
     /**
@@ -185,7 +186,7 @@ export class Engine {
         // update whose time has moved back onto the bar before it is a series the
         // engine cannot run on, whatever it is called.
         if (this.failure === undefined) {
-            const problem = outOfOrder(bar, this.known[this.index - 1], this.index);
+            const problem = handOver(bar, this.known.at(this.index - 1), this.index);
             if (problem !== undefined)
                 return this.refuse(problem);
         }
@@ -193,7 +194,7 @@ export class Engine {
         this.updates += 1;
         // A revision replaces the bar the fold already read, so the bucket it is
         // inside is rebuilt from this reading rather than from the one it replaced.
-        this.known[this.index] = bar;
+        this.known.set(this.index, bar);
         return this.execute(bar, state, false);
     }
     /**
@@ -211,27 +212,34 @@ export class Engine {
      * produces and only the engine can tell the two apart.
      */
     run(bars, states = []) {
+        const source = sourceOf(bars);
         const out = [];
-        // A dataset with nothing in it is the one hand-over that has no bar to
-        // report against, so it is answered here rather than by the loop below,
-        // which would run no iterations and return a clean, empty, wordless result.
-        if (bars.length === 0 && !this.started) {
+        // No bars at all is answered here: the loop below would return an empty, wordless result.
+        if (source.length === 0 && !this.started) {
             const diagnostic = this.failure ?? noBars(this.options.host?.instrument);
             this.failure = diagnostic;
             return { bars: [], diagnostic };
         }
-        this.known = [...bars];
-        for (let i = 0; i < bars.length; i += 1) {
-            const bar = bars[i];
+        this.known.reset(source);
+        for (let i = 0; i < source.length; i += 1) {
+            const bar = source.at(i);
             if (bar === undefined)
                 continue;
-            const result = this.append(bar, states[i] ?? {}, bars.length);
+            const result = this.append(bar, states[i] ?? {}, source.length);
             out.push(result);
             if (result.diagnostic !== undefined)
                 return { bars: out, diagnostic: result.diagnostic };
         }
         return { bars: out, diagnostic: undefined };
     }
+    /**
+     * The dataset a driver appends one bar at a time, handed to the fold before
+     * bar 0 as `run` hands it, so a `"lookahead"` read reads it as history.
+     */
+    history(bars) {
+        if (!this.started)
+            this.known.reset(sourceOf(bars));
+    }
     /**
      * A frame from the destination, `host-interface.md` 7.2. Held until the next
      * bar begins rather than folded where it lands: nothing reaches a running
@@ -266,7 +274,7 @@ export class Engine {
         // session or is inside the one that bar was already in. Read from the bars
         // themselves rather than carried, so a re-executed bar compares against the
         // same neighbour it compared against the first time.
-        const previous = this.known[index - 1]?.time ?? null;
+        const previous = this.known.at(index - 1)?.time ?? null;
         this.facts = factsFor(index, this.supplied, state, isNew, this.updates, this.sessions.factsAt(bar.time ?? null, previous));
         this.view = barViewOf(bar, this.facts, this.previousClose);
         try {
@@ -331,15 +339,6 @@ export class Engine {
             diagnostic: undefined,
         };
     }
-    /**
-     * A bar that failed.
-     *
-     * Steps 7 to 11 do not run, the bar's output columns keep whatever the
-     * previous execution published or stay absent, and the engine reports the
-     * error with its code and source position. It does not continue to the next
-     * bar with a half executed state, so the journal is rolled back and the
-     * script is marked stopped.
-     */
     /**
      * A hand-over the engine refuses, before any of it has been executed.
      *
@@ -361,6 +360,7 @@ export class Engine {
             diagnostic,
         };
     }
+    /** A bar that failed: steps 7 to 11 do not run, the journal rolls back, the script stops. */
     stopped(thrown) {
         const diagnostic = thrown instanceof ScriptError ? thrown.diagnostic : unexpected('the bar', thrown);
         this.rollback();