openalgo-script 0.1.0-alpha.1 → 0.4.0

package/src/core/engine/operations.ts

@@ -0,0 +1,171 @@
+/**
+ * The instructions whose behaviour is more than one line, lifted out of the
+ * dispatch loop.
+ *
+ * Four of the forty-one have rules a reader has to be able to find: the two
+ * history reads, the array subscript and the numeric `for`. Each is written
+ * here as a plain function of what it needs, so the loop stays a switch that
+ * can be read top to bottom and each rule sits beside the part of
+ * `compiled-program.md` section 4 that states it.
+ */
+import type { Span } from '../span/index.js';
+import { raise } from './errors.js';
+import type { Frame } from './frames.js';
+import type { Memory } from './memory.js';
+import type { Registers } from './registers.js';
+import type { CompiledProgram, Constant, Instruction } from './types.js';
+import type { Heap, Value } from './values/index.js';
+import { ABSENT, isRef } from './values/index.js';
+
+/** What the operations below need from the machine, and nothing more. */
+export interface Ops {
+  readonly program: CompiledProgram;
+  readonly registers: Registers;
+  readonly memory: Memory;
+  readonly heap: Heap;
+  readonly slots: Value[];
+  here(): Span;
+  barIndex(): number;
+}
+
+/** A pool entry as a machine value. Entries 0, 1 and 2 are fixed by 2.9. */
+export function constantValueOf(held: Constant | undefined): Value {
+  if (held === undefined) return ABSENT;
+  switch (held[0]) {
+    case 'z':
+      return ABSENT;
+    case 'b':
+    case 'n':
+    case 's':
+      return held[1];
+    default:
+      return { tag: 'color', r: held[1][0], g: held[1][1], b: held[1][2], a: held[1][3] };
+  }
+}
+
+/**
+ * `HIST`, resolved in the order 4.4 gives and in no other.
+ *
+ * Case 3 and case 4 are different on purpose. A depth past the start of the
+ * dataset is absence, because the value never existed; a depth past the
+ * retained history is OS4002, because it existed and the engine threw it away.
+ * Returning absence for both would hide a real bug behind a plausible gap.
+ */
+export function historyRead(ops: Ops, register: number, back: Value): Value {
+  if (back === null) return ABSENT;
+  if (typeof back !== 'number' || !Number.isInteger(back) || back < 0) {
+    raise('OS4001', ops.here(), { index: describe(back) });
+  }
+  const bar = ops.barIndex();
+  if (back > bar) return ABSENT;
+  const depth = ops.program.limits.history;
+  if (depth !== null && back > depth) {
+    raise('OS4002', ops.here(), { index: back, depth, suggested: back });
+  }
+  return ops.registers.at(register, bar, back);
+}
+
+/** `ELEM`: an index outside the array is a mistake, not a missing measurement. */
+export function elementRead(ops: Ops, array: Value, index: Value): Value {
+  const object = ops.heap.deref(array);
+  const size = object !== undefined && object.kind === 'array' ? object.items.length : 0;
+  if (
+    object === undefined ||
+    object.kind !== 'array' ||
+    typeof index !== 'number' ||
+    !Number.isInteger(index) ||
+    index < 0 ||
+    index >= size
+  ) {
+    raise('OS4004', ops.here(), { index: describe(index), name: nameOf(ops, array), size });
+  }
+  return object.items[index] ?? ABSENT;
+}
+
+/**
+ * `FOR_INIT`: pops the step, then the limit, then the start, in that order.
+ *
+ * An absent bound is OS4013 rather than zero iterations. Treating absence as
+ * "do not run" was rejected because a `for` loop whose bound is absent during
+ * warmup would silently produce nothing and the script would look correct.
+ */
+export function forInit(ops: Ops, instruction: Instruction, frame: Frame): void {
+  const step = frame.stack.pop() ?? ABSENT;
+  const limit = frame.stack.pop() ?? ABSENT;
+  const start = frame.stack.pop() ?? ABSENT;
+  const bounds = [
+    [start, 'start'],
+    [limit, 'limit'],
+    [step, 'step'],
+  ] as const;
+  for (const [value, bound] of bounds) {
+    if (value === null) raise('OS4013', ops.here(), { bound });
+  }
+  for (const [value] of bounds) {
+    if (typeof value !== 'number') raise('OS4001', ops.here(), { index: describe(value) });
+  }
+  if (step === 0) {
+    raise('OS3004', ops.here(), {
+      name: 'this loop',
+      argument: 'step',
+      range: 'anything but zero',
+      found: 0,
+    });
+  }
+  frame.slots[instruction[2] as number] = start;
+  frame.slots[instruction[3] as number] = limit;
+  frame.slots[instruction[4] as number] = step;
+  // A descending range with a positive step runs zero times and is never
+  // silently reversed.
+  const from = start as number;
+  const to = limit as number;
+  const by = step as number;
+  if (by > 0 ? from > to : from < to) frame.pc = instruction[5] as number;
+}
+
+/** `FOR_NEXT`: advance, and jump back to the `TICK` when another turn is due. */
+export function forNext(instruction: Instruction, frame: Frame): void {
+  const variable = instruction[2] as number;
+  const limit = frame.slots[instruction[3] as number] as number;
+  const step = frame.slots[instruction[4] as number] as number;
+  const next = (frame.slots[variable] as number) + step;
+  frame.slots[variable] = next === 0 ? 0 : next;
+  if (step > 0 ? next <= limit : next >= limit) frame.pc = instruction[5] as number;
+}
+
+/**
+ * The name a value goes by, for a diagnostic that has to say which array.
+ *
+ * The scan is over the named slots and cells of frame 0, which is where a
+ * script's own names live. A value held only inside another object has no name
+ * in the program, and the message says "the array" rather than inventing one: a
+ * fix that named something the reader cannot find in their file is worse than a
+ * fix that names nothing.
+ */
+export function nameOf(ops: Ops, value: Value): string {
+  if (!isRef(value)) return 'the value';
+  const names = ops.program.debug.names;
+  for (let i = 0; i < ops.slots.length; i += 1) {
+    const held = ops.slots[i];
+    if (held !== undefined && isRef(held) && held.id === value.id) {
+      const name = names.slots[i];
+      if (name !== undefined && name !== '') return name;
+    }
+  }
+  for (let i = 0; i < ops.program.cells.length; i += 1) {
+    const held = ops.memory.load(i);
+    if (isRef(held) && held.id === value.id) {
+      const name = names.cells[i];
+      if (name !== undefined && name !== '') return name;
+    }
+  }
+  return 'the array';
+}
+
+/** A value as a diagnostic has to print it. */
+export function describe(value: Value): string {
+  if (value === null) return 'none';
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return value.tag === 'color' ? 'a colour' : 'an object';
+}

package/src/core/engine/orders.ts

@@ -0,0 +1,121 @@
+/**
+ * The order path at step 9: what the run's ledger is built from, and what an
+ * applied order call becomes.
+ *
+ * Two things live here rather than in the bar cycle, because neither is about
+ * the cycle. **A ledger is built from the declaration**, whose `product`,
+ * `qtyType` and `qty` are fixed before bar 0 like every other declaration
+ * field, and **an order call becomes intents** at the one step that is allowed
+ * to reach the outside world.
+ *
+ * The ledger module knows nothing about a compiled program, which is what keeps
+ * the fold of a frame free of the shape of the file it came from, so the
+ * reading of the declaration is here, on the engine's side of that door.
+ */
+import type { Diagnostic } from '../diagnostics/index.js';
+import type { PendingEffect } from './channels.js';
+import type { EffectRoute, RoutedEffect } from './host.js';
+import type { Instrument } from './host.js';
+import { fieldValue } from './inputs.js';
+import type { ResolvedInput } from './inputs.js';
+import { Ledger } from './ledger/index.js';
+import type { IntentBar } from './ledger/index.js';
+import type { CompiledProgram, Field } from './types.js';
+
+/**
+ * One field of the `strategy()` declaration, resolved the way every other
+ * declaration field is: once, at load, against the inputs.
+ *
+ * The fallback is the documented default rather than a guess. A study has no
+ * strategy declaration at all and never places an order, so the values it takes
+ * here are never read.
+ */
+function declared(field: Field | undefined, inputs: readonly ResolvedInput[]): unknown {
+  return field === undefined ? null : fieldValue(field, inputs);
+}
+
+export function ledgerFor(
+  program: CompiledProgram,
+  inputs: readonly ResolvedInput[],
+  instrument: Instrument | undefined,
+): Ledger {
+  const strategy = program.meta.strategy;
+  const product = declared(strategy?.product, inputs);
+  const qtyType = declared(strategy?.qtyType, inputs);
+  const qty = declared(strategy?.qty, inputs);
+  const pyramiding = declared(strategy?.pyramiding, inputs);
+  return new Ledger({
+    // The file's only leg is the instrument its chart is showing (`stdlib.md`
+    // 17.1), and its identity is the host's own, carried and never parsed. The
+    // leg declarations that name any other contract are planned.
+    instrument: { symbol: instrument?.symbol ?? null, exchange: instrument?.exchange ?? null },
+    product: typeof product === 'string' ? product : 'intraday',
+    qtyType: typeof qtyType === 'string' ? qtyType : 'units',
+    declaredQty: typeof qty === 'number' ? qty : 1,
+    // The instrument's own arithmetic, read from the record the host stated and
+    // never guessed at: a tick size the host does not know is absent, and a
+    // price is then refused against nothing rather than against a default.
+    tickSize: typeof instrument?.tickSize === 'number' ? instrument.tickSize : null,
+    pyramiding: typeof pyramiding === 'number' ? pyramiding : 1,
+  });
+}
+
+/** What one bar's step 9 did with its order calls. */
+export interface AppliedOrders {
+  /** The effects the bar applied, each carrying what it sent. */
+  readonly effects: readonly RoutedEffect[];
+  /** Why the bar sent nothing at all, where an order was refused. */
+  readonly refusal: Diagnostic | undefined;
+}
+
+/**
+ * The effects a bar applied, mapped and then routed.
+ *
+ * An order call becomes intents here and nowhere else, because the ledger is
+ * what mints the id every frame about the order carries back, and a call an
+ * execution threw away never reached this step at all.
+ *
+ * **Mapping the whole bar and routing it are two passes, and that is what keeps
+ * a refused order away from the destination.** A rule like OS7013 is about two
+ * calls at once, so the second call is what refuses the pair, and a loop that
+ * routed each call as it mapped it would already have sent the first. Every
+ * call is therefore mapped before any of them is handed over, and a refusal
+ * anywhere on the bar hands over none of them.
+ *
+ * **Which is why a refusal here discards the bar's rows.** Mapping a call
+ * appends its row, because the calls after it on the same bar are measured
+ * against the rows before them: a cancellation asks whether a tag is working, a
+ * close asks what one tag entered, and pyramiding counts what a position
+ * already holds. So the rows of a bar that is then refused have to be taken
+ * back, or `engine.orders()` reports an order at `placed` that no destination
+ * was ever handed, and a host reconciling after a stopped run sees an order it
+ * never received. The bar's intents and the bar's rows cannot disagree, because
+ * they are made and unmade together.
+ */
+export function routedEffects(
+  ledger: Ledger,
+  applied: readonly PendingEffect[],
+  at: IntentBar,
+  route: EffectRoute | undefined,
+): AppliedOrders {
+  // Where this pass found the ledger, so a refusal can take back exactly the
+  // rows this pass appended and no others: a bar declared `onUnconfirmed`
+  // routes on every execution of itself, and an earlier one really did hand its
+  // orders over.
+  const appended = ledger.rows().length;
+  const effects: RoutedEffect[] = [];
+  for (const effect of applied) {
+    if (effect.effect !== 'order') {
+      effects.push({ ...effect, intents: [] });
+      continue;
+    }
+    const placed = ledger.place(effect.name, effect.params, effect.args, at, effect.at);
+    if (placed.refusal !== undefined) {
+      ledger.discard(appended);
+      return { effects: [], refusal: placed.refusal };
+    }
+    effects.push({ ...effect, intents: placed.intents });
+  }
+  if (route !== undefined) for (const effect of effects) route(effect, at.index);
+  return { effects, refusal: undefined };
+}

package/src/core/engine/registers.ts

@@ -0,0 +1,104 @@
+/**
+ * Series registers: the per-bar history of one value, `compiled-program.md`
+ * 2.10 and 3.2.
+ *
+ * Only a register has history, and `HIST` and `HISTP` are the only way to read
+ * it. A register holds one entry per bar plus a cell for the bar currently
+ * executing; the current cell is set to absent at step 3, `SSTORE` writes it,
+ * `HIST` at offset 0 reads it, and at step 7 it becomes the history entry for
+ * that bar, **replacing whatever a previous execution of the same bar left
+ * there**. That replacement is half of what makes a moving bar idempotent; step
+ * 2's truncation is the other half.
+ *
+ * **Trimming is amortised rather than done per bar.** Step 10 drops entries
+ * older than `limits.history`, and dropping from the front of an array every bar
+ * is quadratic over a long dataset. The registers share one base index, so a
+ * trim is one splice across every register, and it runs only once the stale
+ * entries are worth a pass. Retaining a little more than the declared depth
+ * cannot be observed, because a read past the depth is OS4002 before it ever
+ * reaches the array.
+ */
+import type { Value } from './values/index.js';
+import { ABSENT } from './values/index.js';
+
+export class Registers {
+  private readonly histories: Value[][];
+  private readonly current: Value[];
+  /** The bar index that sits at position 0 of every history. */
+  private base = 0;
+
+  constructor(count: number) {
+    this.histories = [];
+    for (let i = 0; i < count; i += 1) this.histories.push([]);
+    this.current = new Array<Value>(count).fill(ABSENT);
+  }
+
+  count(): number {
+    return this.current.length;
+  }
+
+  /** Step 2: discard any entry a previous execution of bar `bar` wrote. */
+  truncate(bar: number): void {
+    const keep = Math.max(bar - this.base, 0);
+    for (const history of this.histories) {
+      if (history.length > keep) history.length = keep;
+    }
+  }
+
+  /** Step 3: every register's current bar cell starts absent. */
+  clearCurrent(): void {
+    this.current.fill(ABSENT);
+  }
+
+  set(register: number, value: Value): void {
+    this.current[register] = value;
+  }
+
+  /** `SLOAD`: the register's value for the bar being executed. */
+  get(register: number): Value {
+    return this.current[register] ?? ABSENT;
+  }
+
+  /** Step 7: the current bar cell becomes this bar's history entry. */
+  close(bar: number): void {
+    const at = bar - this.base;
+    for (let r = 0; r < this.histories.length; r += 1) {
+      const history = this.histories[r];
+      if (history === undefined) continue;
+      history[at] = this.current[r] ?? ABSENT;
+    }
+  }
+
+  /**
+   * The value a register held `back` bars before `bar`.
+   *
+   * Offset 0 is the bar being executed and reads the current cell, which is why
+   * `close` has not run yet when a script reads `x[0]`.
+   */
+  at(register: number, bar: number, back: number): Value {
+    if (back === 0) return this.current[register] ?? ABSENT;
+    const history = this.histories[register];
+    if (history === undefined) return ABSENT;
+    const at = bar - back - this.base;
+    if (at < 0 || at >= history.length) return ABSENT;
+    return history[at] ?? ABSENT;
+  }
+
+  /** Step 10: drop entries older than the retained depth. */
+  trim(bar: number, depth: number | null): void {
+    if (depth === null) return;
+    const wanted = bar + 1 - depth;
+    const drop = wanted - this.base;
+    // One pass only when the stale entries have paid for it, so a long run
+    // stays linear rather than splicing every register on every bar.
+    if (drop < depth || drop <= 0) return;
+    for (const history of this.histories) history.splice(0, drop);
+    this.base += drop;
+  }
+
+  /** Every value a register holds, for the heap's reachability walk. */
+  walk(visit: (value: Value) => void): void {
+    for (const history of this.histories) for (const value of history) visit(value);
+    for (const value of this.current) visit(value);
+  }
+}