openalgo-script 0.4.0 → 0.6.0

package/src/core/engine/engine.ts

@@ -49,7 +49,9 @@ import type { CompiledProgram, Position } from './types.js';
 import type { RequestPlan } from './request-plan.js';
 import { NO_SESSION, sessionReader } from './session/index.js';
 import type { 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 type { BarColumns } from './bar-source.js';
 import { barMinutesOf } from './timeframe.js';
 import { RequestSet } from './requests.js';
 import type { Value } from './values/index.js';
@@ -96,7 +98,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.
    */
-  private known: HostBar[] = [];
+  private readonly known = new KnownBars();
 
   private supplied = 0;
   private index = -1;
@@ -230,7 +232,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);
     }
     if (this.started) this.checkpoint();
@@ -239,7 +241,7 @@ export class Engine {
     this.updates = 1;
     this.started = true;
     this.previousClose = this.lastClose;
-    if (this.known.length <= this.index) this.known[this.index] = bar;
+    if (this.known.length <= this.index) this.known.set(this.index, bar);
     return this.execute(bar, state, true);
   }
 
@@ -257,14 +259,14 @@ 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);
     }
     this.rollback();
     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);
   }
 
@@ -282,27 +284,34 @@ export 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 {
+    const source = sourceOf(bars);
     const out: BarResult[] = [];
-    // 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: readonly HostBar[] | BarColumns): void {
+    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
@@ -339,7 +348,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,
@@ -418,15 +427,6 @@ export class Engine {
     };
   }
 
-  /**
-   * 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.
    *
@@ -449,6 +449,7 @@ export class Engine {
     };
   }
 
+  /** A bar that failed: steps 7 to 11 do not run, the journal rolls back, the script stops. */
   private stopped(thrown: unknown): BarResult {
     const diagnostic =
       thrown instanceof ScriptError ? thrown.diagnostic : unexpected('the bar', thrown);

package/src/core/engine/guard.ts

@@ -10,7 +10,7 @@
  * catalogue has: an array past its element ceiling is OS5002, a string past its
  * character ceiling is OS5008, one more drawing object than the host will hold
  * is OS5010, an argument outside its contract is OS4003, an index outside an
- * array is OS4004, a change to an object a script already deleted is OS4005,
+ * array is OS4004, a cell outside a table's declared shape is OS4008, a change to an object a script already deleted is OS4005,
  * and a timezone name the host's table does not hold is OS6005.
  */
 import type { Span } from '../span/index.js';
@@ -52,6 +52,17 @@ export function guardFor(budget: Budget): Guard {
       raise('OS4004', span, { index, name, size });
     },
 
+    /**
+     * A cell outside the grid its table declared, OS4008.
+     *
+     * Not OS4004, which is about an array and would name an index and a
+     * flattened element count: a table's shape is two numbers the declaration
+     * fixed, and the fix is to declare the shape the script writes.
+     */
+    badCell(span: Span, row: number, column: number, rows: number, columns: number): never {
+      raise('OS4008', span, { row, column, rows, columns });
+    },
+
     deleted(span: Span, kind: string, bar: number): never {
       raise('OS4005', span, { kind, bar });
     },

package/src/core/engine/host.ts

@@ -25,6 +25,7 @@
  * stop rather than what a script computes.
  */
 import type { HostBar } from './bars.js';
+import type { BarColumns } from './bar-source.js';
 import type { PendingEffect } from './channels.js';
 import type { OrderIntent } from './ledger/index.js';
 import type { HostFacts } from './library/index.js';
@@ -154,10 +155,11 @@ export interface RequestRefusal {
  * answer between bars and then recalculates the study over its whole history,
  * which is a fresh load rather than an answer spliced into a run already past
  * the bars it would have changed. A host that wants the engine to fold the
- * chart's own bars instead returns nothing at all.
+ * chart's own bars instead returns nothing at all. The bars may be records or
+ * columns, as a run's may (`bar-source.ts`).
  */
 export type RequestAnswer =
-  | { readonly bars: readonly HostBar[] }
+  | { readonly bars: readonly HostBar[] | BarColumns }
   | { readonly pending: true }
   | { readonly refused: RequestRefusal };
 

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';
@@ -32,6 +32,7 @@ export type { AlertFiring } from './alerts.js';
 export type { Grid } from './grids.js';
 
 export type { BarFacts, BarState, HostBar } from './bars.js';
+export type { BarColumn, BarColumns } from './bar-source.js';
 export { BAR_FIELDS, barField, isBarField } from './bars.js';
 
 export type { Clock, EngineLimits } from './budget.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/binding.ts

@@ -160,6 +160,8 @@ export interface Guard {
   badArgument(span: Span, name: string, argument: string, found: string): never;
   /** Raise a run-time diagnostic against an index outside an array. */
   badIndex(span: Span, name: string, index: string, size: number): never;
+  /** Raise a run-time diagnostic against a cell outside a table's declared shape. */
+  badCell(span: Span, row: number, column: number, rows: number, columns: number): never;
   /** Raise a run-time diagnostic against an object a script already deleted. */
   deleted(span: Span, kind: string, bar: number): never;
   /** Raise a run-time diagnostic against a zone name the host does not know. */

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,
@@ -68,6 +74,17 @@ for (const one of ENTRIES) {
 }
 
 /** The entry for one name and argument count, or nothing when there is none. */
+/**
+ * Every name and argument count this engine holds, as `name/arity`, sorted.
+ *
+ * `scripts/check-manifests.mjs` compares it with the second engine's, so a call
+ * one engine holds and the other does not is found by a build rather than by the
+ * first case that reaches it.
+ */
+export function manifestKeys(): readonly string[] {
+  return [...INDEX.keys()].sort();
+}
+
 export function manifestEntry(name: string, arity: number): ManifestEntry | undefined {
   return INDEX.get(keyOf(name, arity));
 }

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

@@ -234,12 +234,7 @@ export const OBJECT_ENTRIES: readonly ManifestEntry[] = [
     const col = wholeAt(ctx, 'cell', 'col', args, 2);
     if (row === null || col === null) return null;
     if (row >= object.rows || col >= object.cols) {
-      ctx.guard.badIndex(
-        ctx.span,
-        ctx.nameOf(valueAt(args, 0)),
-        `${row}, ${col}`,
-        object.rows * object.cols,
-      );
+      ctx.guard.badCell(ctx.span, row, col, object.rows, object.cols);
     }
     const written: GridCell = {
       row,

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/request-body.ts

@@ -28,6 +28,8 @@
 import type { Span } from '../span/index.js';
 import { barField, factsFor } from './bars.js';
 import type { HostBar } from './bars.js';
+import { recordSource } from './bar-source.js';
+import type { BarSource } from './bar-source.js';
 import { Budget, stepBound } from './budget.js';
 import type { Clock, EngineLimits } from './budget.js';
 import { Channels } from './channels.js';
@@ -59,12 +61,7 @@ export interface BodyInput {
  */
 export interface NestedRequests {
   readonly empty: boolean;
-  fill(
-    registers: Registers,
-    bars: readonly HostBar[],
-    index: number,
-    fresh: boolean,
-  ): void;
+  fill(registers: Registers, bars: BarSource, index: number, fresh: boolean): void;
 }
 
 export interface BodyParts {
@@ -120,6 +117,7 @@ export class RequestBody {
   private lastClose: number | null = null;
   /** The requested bars themselves, kept only when a read inside folds them. */
   private readonly history: HostBar[] = [];
+  private readonly historySource = recordSource(this.history);
   /**
    * The value the last closed requested bar handed back.
    *
@@ -251,7 +249,7 @@ export class RequestBody {
     const nested = this.parts.nested;
     if (nested !== undefined && !nested.empty) {
       this.history[index] = bar;
-      nested.fill(this.registers, this.history, index, this.touches === 0);
+      nested.fill(this.registers, this.historySource, index, this.touches === 0);
     }
 
     this.machine.run();

package/src/core/engine/request-plan.ts

@@ -218,9 +218,9 @@ export function undatable(plan: RequestPlan): boolean {
  *
  * OS6012's own message, because the zone is an instrument fact the host did not
  * supply and that is exactly what this read needs and cannot default. Nothing
- * is raised: a fact the host did not state leaves the read absent, and this is
- * the sentence that explains the absence rather than a second answer to the
- * question `host-interface.md` 4.5 leaves open.
+ * is raised: a fact the host did not state leaves the read absent, as
+ * `host-interface.md` 4.5 settles it, and this is the sentence that explains
+ * the absence rather than a second answer to it.
  */
 export function undatableReason(query: RequestQuery): string {
   return diagnosticFor('OS6012', NO_POSITION, { fact: 'a timezone', symbol: named(query) }).message;