openalgo-script 0.5.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

@@ -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/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/index.ts

@@ -74,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/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;

package/src/core/engine/requests.ts

@@ -48,6 +48,8 @@
  */
 import type { Span } from '../span/index.js';
 import type { HostBar } from './bars.js';
+import { sourceOf } from './bar-source.js';
+import type { BarSource } from './bar-source.js';
 import type { Clock, EngineLimits } from './budget.js';
 import type { EngineHost } from './host.js';
 import type { ResolvedInput } from './inputs.js';
@@ -97,7 +99,7 @@ interface Read {
   readonly register: number;
   readonly body: RequestBody;
   /** The host's bars for a `symbol` read, or nothing when the fold is the chart's. */
-  readonly source: readonly HostBar[] | undefined;
+  readonly source: BarSource | undefined;
   readonly ready: boolean;
   readonly reason: string;
   /** How far into the source the fold has read. */
@@ -146,7 +148,7 @@ export class RequestSet {
    * have been revised since the last execution, and the bucket it is inside has
    * to be rebuilt from the revision rather than from the reading it replaced.
    */
-  fill(registers: Registers, bars: readonly HostBar[], index: number, fresh: boolean): void {
+  fill(registers: Registers, bars: BarSource, index: number, fresh: boolean): void {
     const heap = this.parts.heapOf();
     for (const read of this.reads) {
       if (fresh) {
@@ -227,7 +229,7 @@ function build(parts: RequestParts, request: Request, plan: RequestPlan): Read {
     plan,
     register: request.series,
     body,
-    source: answer !== undefined && 'bars' in answer ? answer.bars : undefined,
+    source: answer !== undefined && 'bars' in answer ? sourceOf(answer.bars) : undefined,
     // A fold of the chart's own bars needs nothing from the host, so it is
     // answered the moment it is planned. A read the host is still fetching is
     // not: the read is absent, `req.isReady` is false, and the study keeps
@@ -247,9 +249,9 @@ function build(parts: RequestParts, request: Request, plan: RequestPlan): Read {
 }
 
 /** The read's value for the chart bar at `index`, and the fold that gets there. */
-function valueOf(read: Read, bars: readonly HostBar[], index: number): Value {
+function valueOf(read: Read, bars: BarSource, index: number): Value {
   if (!read.ready) return ABSENT;
-  const bar = bars[index];
+  const bar = bars.at(index);
   const at = bar?.time ?? null;
   if (at === null) return ABSENT;
   const key = keyOf(read, at);
@@ -258,7 +260,7 @@ function valueOf(read: Read, bars: readonly HostBar[], index: number): Value {
   const source = read.source ?? bars;
   const lookahead = read.plan.request.mode === 'lookahead';
   for (;;) {
-    const next = source[read.cursor];
+    const next = source.at(read.cursor);
     if (next === undefined) break;
     const found = next.time === null ? undefined : keyOf(read, next.time);
     if (found === undefined) {
@@ -310,7 +312,7 @@ function feed(read: Read, bar: HostBar, key: number): void {
 }
 
 /** A re-executed bar: the fold as it stood when the bar began. */
-function restore(read: Read, bars: readonly HostBar[]): void {
+function restore(read: Read, bars: BarSource): void {
   read.cursor = read.mark.cursor;
   read.openKey = read.mark.openKey;
   read.openFrom = read.mark.openFrom;
@@ -318,7 +320,7 @@ function restore(read: Read, bars: readonly HostBar[]): void {
   if (read.openKey === undefined) return;
   const source = read.source ?? bars;
   for (let at = read.openFrom; at < read.cursor; at += 1) {
-    const bar = source[at];
+    const bar = source.at(at);
     if (bar === undefined || bar.time === null) continue;
     if (keyOf(read, bar.time) !== read.openKey) continue;
     read.open = read.open === undefined ? start(bar) : extend(read.open, bar);
@@ -380,3 +382,4 @@ function lower(a: number | null, b: number | null | undefined): number | null {
 function both(a: number | null, b: number | null): number | null {
   return a === null || b === null ? null : a + b;
 }
+

package/src/core/engine/series.ts

@@ -1,5 +1,5 @@
 /**
- * The two things the engine checks about the bars it is handed,
+ * The three things the engine checks about the bars it is handed,
  * `host-interface.md` 3.5 and conformance item 1.
  *
  * Everything else about a series the engine takes exactly as stated: it does
@@ -55,6 +55,23 @@ export function noBars(instrument: Instrument | undefined): Diagnostic {
   });
 }
 
+/**
+ * A bar handed over with no time, OS6025.
+ *
+ * `host-interface.md` 3.1 states `time` for every bar with no absent case, and
+ * the order rule is built on it. Reading a missing one as the absent value, as
+ * `barField` would, steps the bar over every calendar fold and makes every
+ * session fact absent on a bar that is on the chart: a study draws a gap where
+ * the host has data, and nothing says why. It is a bar of the wrong shape, not
+ * one out of order, so it has a code and a fix of its own. A time that is not a
+ * finite number is no time either.
+ */
+export function undated(bar: HostBar, index: number): Diagnostic | undefined {
+  const time: unknown = bar.time;
+  if (typeof time === 'number' && Number.isFinite(time)) return undefined;
+  return failure('OS6025', NO_POSITION, { index });
+}
+
 /**
  * A bar whose time does not follow the one before it, OS6011.
  *
@@ -63,11 +80,9 @@ export function noBars(instrument: Instrument | undefined): Diagnostic {
  * only one whose position tells the host where its own ordering went wrong.
  *
  * `previous` is the bar already handed over, or nothing for the first bar of a
- * run, which follows nothing and is therefore always in order. A time the host
- * did not state is not compared: the absent value is what `barField` gives a
- * script for it (3.1), and the catalogue has no code for a bar dated nothing,
- * so inventing this one for it would be a refusal the specification does not
- * describe.
+ * run, which follows nothing and is therefore always in order. A bar with no
+ * time never reaches this comparison: `undated` refuses it first, because a
+ * bar dated nothing is not two instants in the wrong order.
  */
 export function outOfOrder(
   bar: HostBar,
@@ -80,3 +95,12 @@ export function outOfOrder(
   if (time > before) return undefined;
   return failure('OS6011', NO_POSITION, { index, time, previous: index - 1 });
 }
+
+/** Both checks of a bar handed over, in the order they are made: its shape, then its order. */
+export function handOver(
+  bar: HostBar,
+  previous: HostBar | undefined,
+  index: number,
+): Diagnostic | undefined {
+  return undated(bar, index) ?? outOfOrder(bar, previous, index);
+}

package/src/core/engine/session/record.ts

@@ -106,10 +106,10 @@ function hoursOf(stated: SessionHours | undefined): Hours | null {
  *
  * Each of the three is reported at load rather than answered with absence,
  * because absence there is indistinguishable from the honest case and the honest
- * case is the one a reader will assume. This decides nothing about what a bare
- * read of an instrument fact returns, which is issue 0002 and is open: a record
- * the host contradicts itself in is a different question from a fact it did not
- * state.
+ * case is the one a reader will assume. A bare read of an instrument fact the
+ * host did not state is a different question with the opposite answer: it is
+ * absent and never refused (`host-interface.md` 4.5, decision 66), because a
+ * record the host contradicts itself in is not a fact it left out.
  */
 export function recordProblem(
   stated: SessionHours | undefined,