openalgo-script 0.1.0-alpha.1 → 0.4.0

package/src/core/engine/errors.ts

@@ -0,0 +1,100 @@
+/**
+ * How the engine says something went wrong, and why it does it by throwing.
+ *
+ * **Nothing the engine exposes ever throws.** A host draws many studies in one
+ * render loop and runs many customers' scripts in one process, so a script that
+ * fails has to become a diagnostic about that script and nothing else. The
+ * public surface catches everything and returns.
+ *
+ * Inside, a failure is thrown, because an error in the middle of an expression
+ * has to abandon the rest of the bar and there is no answer to return from a
+ * `DIV` that would not have to be checked again by every instruction above it.
+ * The throw crosses the interpreter and stops at the one boundary that knows
+ * what to do with it.
+ *
+ * Every failure carries a catalogue code and a position. A bare string is not
+ * available here: `diagnosticFor` is typed per code, so a call that forgets a
+ * placeholder does not compile.
+ */
+import type { DiagnosticCode, DiagnosticValues } from '../catalogue/index.js';
+import { diagnosticFor } from '../diagnostics/index.js';
+import type { Diagnostic } from '../diagnostics/index.js';
+import type { SourceFile } from '../source/index.js';
+import { makeSpan } from '../span/index.js';
+import type { Span } from '../span/index.js';
+
+/** A diagnostic on its way out of the machine. */
+export class ScriptError extends Error {
+  readonly diagnostic: Diagnostic;
+
+  constructor(diagnostic: Diagnostic) {
+    super(diagnostic.code);
+    this.name = 'ScriptError';
+    this.diagnostic = diagnostic;
+  }
+}
+
+/**
+ * Where a diagnostic points.
+ *
+ * A compiled program carries a line and a column per instruction and not an
+ * offset, because `debug.pos` is a position in the source rather than an index
+ * into text the engine was never given. When a host hands the engine the source
+ * file as well, the offset is worked out from the position and a renderer can
+ * draw the caret under the line; without it the line and the column still say
+ * where, which is what an error message needs.
+ */
+export function spanAt(source: SourceFile | undefined, line: number, column: number): Span {
+  if (source === undefined) return makeSpan(0, 0, line, column);
+  return makeSpan(source.offsetAt({ line, column }), 0, line, column);
+}
+
+/** The position a load-time failure carries: the program, not a line of source. */
+export const NO_POSITION: Span = makeSpan(0, 0, 0, 0);
+
+export function raise<Code extends DiagnosticCode>(
+  code: Code,
+  span: Span,
+  values: DiagnosticValues[Code],
+): never {
+  throw new ScriptError(diagnosticFor(code, span, values));
+}
+
+export function failure<Code extends DiagnosticCode>(
+  code: Code,
+  span: Span,
+  values: DiagnosticValues[Code],
+): Diagnostic {
+  return diagnosticFor(code, span, values);
+}
+
+/**
+ * A verification failure, `compiled-program.md` 3.5.
+ *
+ * One code covers a malformed instruction list, an unreadable encoding and an
+ * input reference naming an input that was never declared, because they are not
+ * separate fixes: all three are defects of the compiler that wrote the program
+ * and none of them is repairable by hand.
+ */
+export function malformed(location: string, reason: string): Diagnostic {
+  return failure('OS6018', NO_POSITION, { location, reason });
+}
+
+/** The location half of OS6018 for an instruction, in the spelling 3.5 gives. */
+export function atInstruction(list: string, index: number): string {
+  return list === 'code' ? `instruction ${index}` : `${list} instruction ${index}`;
+}
+
+/**
+ * Whatever escaped that was not a diagnostic.
+ *
+ * A verified program cannot underflow the stack, jump out of bounds or address
+ * a slot that does not exist, so an exception from inside the interpreter means
+ * the program is not what verification said it was. It becomes a diagnostic on
+ * this script rather than an exception in the host's render loop, which is the
+ * whole of "one script failing takes nothing else down".
+ */
+export function unexpected(where: string, thrown: unknown): Diagnostic {
+  const reason = thrown instanceof Error ? thrown.message : String(thrown);
+  return malformed(where, `the engine could not execute it: ${reason}`);
+}

package/src/core/engine/frames.ts

@@ -0,0 +1,85 @@
+/**
+ * Frames, and where an instruction came from in the source.
+ *
+ * A frame is `compiled-program.md` 3.3's seven fields. Two of them, `cellBase`
+ * and `stateBase`, are what make one function body serve many independent
+ * pieces of state: a cell operand inside a body is added to the frame's base,
+ * so the same body reaches different cells from different call sites, and the
+ * call site supplies the bases. That is `language.md` 11.4's rule that state is
+ * allocated per call site, made mechanical.
+ *
+ * **A frame's stack region is its own.** A called function cannot see or
+ * disturb the caller's operands, which is what makes the verifier's depth walk
+ * a local question rather than a whole program one.
+ *
+ * Positions are looked up rather than carried per instruction. 2.15 stores one
+ * triple per change of position and the position of any instruction is the
+ * triple with the greatest index at or below it, so a run of instructions from
+ * one expression costs one triple. The lookup runs when a diagnostic is raised
+ * and never on the path an instruction takes.
+ */
+import type { Instruction, Position } from './types.js';
+import type { Value } from './values/index.js';
+import { ABSENT } from './values/index.js';
+
+export interface Frame {
+  readonly code: readonly Instruction[];
+  pc: number;
+  readonly slots: Value[];
+  readonly cellBase: number;
+  readonly stateBase: number;
+  /** The register bound to each series parameter, from the call site. */
+  readonly series: readonly number[];
+  readonly stack: Value[];
+  /** The position table for this frame's instruction list. */
+  readonly positions: readonly Position[];
+}
+
+export function makeFrame(
+  code: readonly Instruction[],
+  slots: number,
+  cellBase: number,
+  stateBase: number,
+  series: readonly number[],
+  positions: readonly Position[],
+): Frame {
+  return {
+    code,
+    pc: 0,
+    slots: new Array<Value>(slots).fill(ABSENT),
+    cellBase,
+    stateBase,
+    series,
+    stack: [],
+    positions,
+  };
+}
+
+/**
+ * The line and column of one instruction.
+ *
+ * A binary search rather than a scan, because a program with four thousand
+ * instructions raising a diagnostic inside a loop would otherwise walk the
+ * table once per raise, and a debugger stepping instruction by instruction asks
+ * for this on every step.
+ */
+export function positionAt(positions: readonly Position[], pc: number): {
+  readonly line: number;
+  readonly column: number;
+} {
+  let low = 0;
+  let high = positions.length - 1;
+  let found: Position | undefined;
+  while (low <= high) {
+    const middle = (low + high) >> 1;
+    const entry = positions[middle];
+    if (entry === undefined) break;
+    if (entry[0] <= pc) {
+      found = entry;
+      low = middle + 1;
+    } else {
+      high = middle - 1;
+    }
+  }
+  return found === undefined ? { line: 0, column: 0 } : { line: found[1], column: found[2] };
+}

package/src/core/engine/grids.ts

@@ -0,0 +1,98 @@
+/**
+ * The grids a program declares, and the four points in the bar cycle they touch.
+ *
+ * A grid is the one output that is neither a channel nor an instruction.
+ * `table()` emits no code at all: the declaration fixes the grid's shape before
+ * bar 0, exactly as an input's does, and the engine puts the handle in the
+ * declared slot at step 5 (`compiled-program.md` 2.8 and 5.1). Building one per
+ * bar would give a script a different object every bar for something the format
+ * calls part of the study's fixed shape, and a script that kept the handle in a
+ * `var` would be holding last bar's grid.
+ *
+ * **The cells are a buffer, not a history.** Step 3 empties every grid's cells,
+ * so what a host reads after a run is what the last executed bar wrote and
+ * nothing before it. That is why a re-executed bar rebuilds its grid rather than
+ * doubling it, why a checkpoint holds none of it, and why a hundred thousand
+ * bars of history cost a host exactly one grid to draw.
+ */
+import { fieldValue } from './inputs.js';
+import type { ResolvedInput } from './inputs.js';
+import type { CompiledProgram } from './types.js';
+import type { GridCell, Heap, Value } from './values/index.js';
+import { reference } from './values/index.js';
+
+/** A grid the program declared, with the cells this bar wrote into it. */
+export interface Grid {
+  readonly key: string;
+  readonly rows: number;
+  readonly cols: number;
+  readonly cells: readonly GridCell[];
+}
+
+/** One declared grid: its name, the slot holding it and the object it is. */
+interface Declared {
+  readonly key: string;
+  readonly slot: number;
+  readonly id: number;
+}
+
+export class Grids {
+  private readonly heap: Heap;
+  private readonly declared: readonly Declared[];
+
+  constructor(program: CompiledProgram, inputs: readonly ResolvedInput[], heap: Heap) {
+    this.heap = heap;
+    const declared: Declared[] = [];
+    for (const one of program.outputs.tables) {
+      const rows = fieldValue(one.rows, inputs);
+      const cols = fieldValue(one.cols, inputs);
+      const id = heap.allocate({
+        kind: 'table',
+        rows: typeof rows === 'number' ? rows : 0,
+        cols: typeof cols === 'number' ? cols : 0,
+        cells: [],
+      });
+      declared.push({ key: one.key, slot: one.slot, id });
+    }
+    this.declared = declared;
+    // The grids exist before the first bar, so nothing about them belongs to a
+    // bar's undo journal.
+    heap.commit();
+  }
+
+  get empty(): boolean {
+    return this.declared.length === 0;
+  }
+
+  /** Step 3: every cell buffer starts each execution of a bar empty. */
+  clear(): void {
+    for (const grid of this.declared) {
+      const object = this.heap.get(grid.id);
+      if (object !== undefined && object.kind === 'table') object.cells = [];
+    }
+  }
+
+  /** Step 5: each grid's handle lands in the slot its declaration named. */
+  fill(slots: Value[]): void {
+    for (const grid of this.declared) slots[grid.slot] = reference(grid.id);
+  }
+
+  /** A grid is reachable for as long as the study is, whatever a script holds. */
+  walk(visit: (value: Value) => void): void {
+    for (const grid of this.declared) visit(reference(grid.id));
+  }
+
+  /** The grids and the cells the last executed bar wrote into them. */
+  read(): readonly Grid[] {
+    return this.declared.map((grid) => {
+      const object = this.heap.get(grid.id);
+      const table = object !== undefined && object.kind === 'table' ? object : undefined;
+      return {
+        key: grid.key,
+        rows: table?.rows ?? 0,
+        cols: table?.cols ?? 0,
+        cells: table?.cells ?? [],
+      };
+    });
+  }
+}

package/src/core/engine/guard.ts

@@ -0,0 +1,71 @@
+/**
+ * The memory ceilings and the run-time refusals, as the library sees them.
+ *
+ * The library is handed this rather than the budget itself, so that the only
+ * thing a library call can do to the engine's counters is ask whether something
+ * it is about to build is allowed. A call cannot charge the loop budget, cannot
+ * read the clock and cannot stop a bar for a reason of its own.
+ *
+ * Every refusal here carries a catalogue code, and they are the codes the
+ * 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,
+ * and a timezone name the host's table does not hold is OS6005.
+ */
+import type { Span } from '../span/index.js';
+import type { Budget } from './budget.js';
+import { raise } from './errors.js';
+import type { Guard } from './library/index.js';
+
+export function guardFor(budget: Budget): Guard {
+  return {
+    array(span: Span, name: string, size: number): void {
+      budget.checkArray(span, name, size);
+    },
+
+    string(span: Span, text: string): string {
+      return budget.checkString(span, text);
+    },
+
+    chars(span: Span, length: number): void {
+      budget.checkLength(span, length);
+    },
+
+    drawing(span: Span, held: number): void {
+      budget.checkDrawing(span, held);
+    },
+
+    /**
+     * An argument outside its contract, OS4003.
+     *
+     * The compile-time half of this is OS3004, which the checker raises when
+     * the argument is a literal. This is the run-time half, for a length a
+     * script computed, and it names the call and the parameter so the reader is
+     * looking at one argument rather than at a line.
+     */
+    badArgument(span: Span, name: string, argument: string, found: string): never {
+      raise('OS4003', span, { name, argument, found });
+    },
+
+    badIndex(span: Span, name: string, index: string, size: number): never {
+      raise('OS4004', span, { index, name, size });
+    },
+
+    deleted(span: Span, kind: string, bar: number): never {
+      raise('OS4005', span, { kind, bar });
+    },
+
+    /**
+     * A timezone name the host's table does not hold, OS6005.
+     *
+     * Not absence, because an absent answer here would be indistinguishable
+     * from a host that stated no timezone at all, and not an invented offset,
+     * because an offset is silently wrong for half the year anywhere that
+     * observes a seasonal clock change.
+     */
+    badZone(span: Span, value: string): never {
+      raise('OS6005', span, { value });
+    },
+  };
+}

package/src/core/engine/host.ts

@@ -0,0 +1,251 @@
+/**
+ * What a host supplies, `compiled-program.md` 5.2.
+ *
+ * An engine reads all of this from the host and none of it from anywhere else.
+ * The interface is small on purpose: every fact on it is one a host already
+ * has, and nothing on it is something an engine could work out and then
+ * disagree with the host about.
+ *
+ * **The strategy's position is not here, and that is the point of the duty.**
+ * An account position is held per contract and is shared with every other
+ * strategy and every manual trade in it, so a strategy that read one would be
+ * deciding against somebody else's trade (`stdlib.md` 17.1). What the position
+ * calls read is the run's own ledger, folded from the orders this strategy sent
+ * and the fills reported for them, and that ledger lives in `ledger/`.
+ *
+ * Every fact is optional and an absent one reads as absence in a script rather
+ * than as a zero or an error. A study that sizes something by the lot size has
+ * to be able to tell "one" from "nobody told me", which is the same argument
+ * 2.10 makes for an absent volume.
+ *
+ * **There is no clock on this interface except `chart.now`.** Section 8.4 is
+ * explicit: no wall clock during a bar, except `chart.now()`, whose value the
+ * host supplies and the conformance suite fixes. The engine's own wall clock
+ * budget is passed separately, in `LoadOptions`, because it decides when to
+ * stop rather than what a script computes.
+ */
+import type { HostBar } from './bars.js';
+import type { PendingEffect } from './channels.js';
+import type { OrderIntent } from './ledger/index.js';
+import type { HostFacts } from './library/index.js';
+import type { SessionHours } from './session/index.js';
+import type { Value } from './values/index.js';
+
+/** The instrument record, `host-interface.md` 4.1, as the engine reads it. */
+export interface Instrument {
+  readonly symbol?: string;
+  readonly exchange?: string;
+  /** The chart's interval code, which `chart.intervalMinutes` is derived from. */
+  readonly interval?: string;
+  /** An IANA zone name, never a fixed offset, `host-interface.md` 4.1. */
+  readonly timezone?: string;
+  readonly tickSize?: number;
+  readonly lotSize?: number;
+  readonly pointValue?: number;
+  readonly currency?: string;
+  readonly instrumentType?: string;
+  /** The one fact a host must state, because no derivation recovers it. */
+  readonly hasVolume?: boolean;
+  readonly hasOpenInterest?: boolean;
+  /**
+   * The instrument's trading session, `host-interface.md` 4.3.
+   *
+   * The documented source of every per-bar session fact, and the only one: the
+   * engine derives `session.isFirstBar` and `session.isLastBar` from this
+   * hours, the bar's time and the timezone above. A host states the hours it
+   * schedules, once, and is never asked about a bar.
+   */
+  readonly session?: SessionHours;
+}
+
+/**
+ * Where an applied effect goes: an order route, a log, or nothing at all.
+ *
+ * An order call arrives with the intents it became (`host-interface.md` 7.1),
+ * which is what a host sends and what every frame about it carries back. A
+ * call that sent nothing, and a call with no order in it at all, arrives with
+ * none.
+ */
+export type EffectRoute = (effect: RoutedEffect, bar: number) => void;
+
+/** An applied effect, with what the engine minted for it at step 9. */
+export interface RoutedEffect extends PendingEffect {
+  readonly intents: readonly OrderIntent[];
+}
+
+/**
+ * One read, as the host is asked about it, `host-interface.md` 5.2.
+ *
+ * The whole set is handed over at load and never grows during a run: a
+ * request's identity is fixed before bar 0, which is what lets a host fetch in
+ * parallel, cache by instrument and timeframe, and have the answers in hand
+ * before the first bar runs.
+ *
+ * **Every field here is resolved.** The compiled program writes each of the
+ * three identity fields as a value, a setting to read or a chart fact to read
+ * (`compiled-program.md` 2.16), and two of its spellings mean "the chart's
+ * own": a `null` `symbol` on a `"timeframe"` read, and a `null` `exchange` on
+ * either. Both are resolved against the instrument record before this crosses,
+ * so a host is handed an identity to resolve rather than a rule to apply. A
+ * host that had to apply the rule itself would need the record it already
+ * supplied, and the two would disagree the first time one of them was wrong.
+ *
+ * **There is no range on this shape, and 5.2 says why.** The whole set is known
+ * at load, and at load the engine has been handed no bars, so it has no span to
+ * extend. `warmup` is what it does know, counted in requested bars, and the host
+ * turns it into instants from the chart's own bars.
+ */
+export interface RequestQuery {
+  /** The engine's handle, which every answer and every refusal carries back. */
+  readonly id: number;
+  readonly read: 'timeframe' | 'symbol';
+  /**
+   * The instrument, as `host-interface.md` 9 defines an identity: the one the
+   * script named, or the chart's own on a read of the chart's own instrument.
+   *
+   * Absent only where a `"symbol"` read's identity did not resolve to a string,
+   * which is a setting holding something that is not an instrument. The chart's
+   * own is never substituted there: a read of another instrument that quietly
+   * became a read of this one is a line on a chart nobody asked for.
+   */
+  readonly instrument: string | null;
+  /**
+   * Where it trades: the exchange the script named, or the chart's own when it
+   * named none, which is `stdlib.md` 15.1's documented default.
+   */
+  readonly exchange: string | null;
+  /** A timeframe string, `stdlib.md` 15.2, resolved from the program. */
+  readonly timeframe: string;
+  readonly mode: 'confirmed' | 'developing' | 'lookahead';
+  /**
+   * Requested bars of history the expression needs, or nothing when no number
+   * is known.
+   *
+   * A floor rather than a promise: a host that extends the range backwards by
+   * less gets a read that is absent for longer, never a wrong number.
+   */
+  readonly warmup: number | null;
+}
+
+/**
+ * Why a host cannot answer, `host-interface.md` 5.4.
+ *
+ * **A refusal is reported and is never an empty answer**, because an empty
+ * series looks exactly like an instrument that did not trade. The reason text
+ * reaches the script through `req.error(read)`, and the study keeps drawing
+ * everything that does not depend on the failed read.
+ */
+export interface RequestRefusal {
+  readonly code: 'OS6007' | 'OS6008' | 'OS6009' | 'OS6014' | 'OS6015';
+  /** The host's own words, carried and never paraphrased, for OS6009. */
+  readonly reason?: string;
+  /** The intervals the host does serve for this instrument, for OS6014. */
+  readonly available?: string;
+}
+
+/**
+ * What a host says about one read.
+ *
+ * `bars` is the answer: the host's own bars at the requested timeframe, oldest
+ * first, never padded or synthesised. `refused` is 5.4.
+ *
+ * `pending` is a host that is still fetching. The read is absent and
+ * `req.isReady` is false, and it stays that way for this run: 5.3 delivers an
+ * 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.
+ */
+export type RequestAnswer =
+  | { readonly bars: readonly HostBar[] }
+  | { readonly pending: true }
+  | { readonly refused: RequestRefusal };
+
+/**
+ * Where the engine asks for another instrument's or another interval's bars.
+ *
+ * Returning nothing means the host does not serve this request. On a read of
+ * the chart's own instrument that is the ordinary case and the engine folds the
+ * bars it already holds; on a read of another instrument the engine holds none
+ * of them, so nothing to serve is OS6007.
+ */
+export type RequestProvider = (query: RequestQuery) => RequestAnswer | undefined;
+
+export interface EngineHost {
+  readonly instrument?: Instrument;
+  /** The chart clock, for `chart.now()`. Fixed by the host, never read here. */
+  readonly now?: number;
+  /**
+   * Where step 9 sends an applied effect.
+   *
+   * An engine with no route still runs every study ever written and refuses
+   * exactly the strategies, because `orders` is then a capability it does not
+   * declare and OS6006 names it at load.
+   */
+  readonly route?: EffectRoute;
+  /**
+   * Bars for another instrument or another interval, `host-interface.md` 5.
+   *
+   * Optional, and the capability follows it: a host with no provider declares
+   * no `req.symbol`, so a program that reads another instrument is refused at
+   * load with OS6006 naming the tag rather than drawing a study with a silently
+   * empty line through it. `req.timeframe` needs no provider, because the
+   * engine folds the chart's own bars, which is the read 5.1 says an engine can
+   * satisfy from what it already holds.
+   */
+  readonly requestBars?: RequestProvider;
+}
+
+/** A number the host stated, or absence when it stated none. */
+export function hostNumber(value: number | undefined): Value {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+export function hostString(value: string | undefined): Value {
+  return typeof value === 'string' ? value : null;
+}
+
+/** A condition the host stated, or absence when it stated none. */
+export function hostBool(value: boolean | undefined): Value {
+  return typeof value === 'boolean' ? value : null;
+}
+
+/**
+ * What the request set can say about a read, so this file need not know it.
+ *
+ * `req.isReady` and `req.error` name a read rather than taking its value, which
+ * is why the compiler resolved the name to the request's id: a value on a bar
+ * cannot say which request produced it (2.16). A read this program does not
+ * make has not been answered and has reported no reason.
+ */
+export interface RequestReplies {
+  answered(id: Value): Value;
+  failure(id: Value): Value;
+}
+
+/**
+ * The facts a library call reads, built over one host.
+ *
+ * The host is fetched through a function rather than captured, because a host
+ * may be replaced between two runs of one engine and every read here has to see
+ * the one in force now. Every entry is one row of `compiled-program.md` 5.2 and
+ * there is no row that is not on that list.
+ */
+export function hostFactsFor(of: () => EngineHost, reads: RequestReplies): HostFacts {
+  return {
+    symbol: () => hostString(of().instrument?.symbol),
+    exchange: () => hostString(of().instrument?.exchange),
+    interval: () => hostString(of().instrument?.interval),
+    timezone: () => hostString(of().instrument?.timezone),
+    tickSize: () => hostNumber(of().instrument?.tickSize),
+    lotSize: () => hostNumber(of().instrument?.lotSize),
+    pointValue: () => hostNumber(of().instrument?.pointValue),
+    currency: () => hostString(of().instrument?.currency),
+    instrumentType: () => hostString(of().instrument?.instrumentType),
+    hasVolume: () => hostBool(of().instrument?.hasVolume),
+    hasOpenInterest: () => hostBool(of().instrument?.hasOpenInterest),
+    now: () => hostNumber(of().now),
+    requestReady: (id: Value) => reads.answered(id),
+    requestError: (id: Value) => reads.failure(id),
+  };
+}