openalgo-script 0.1.0-alpha.1 → 0.4.0

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

@@ -0,0 +1,328 @@
+/**
+ * A request expression, executed over the requested bars,
+ * `compiled-program.md` 2.16.1.
+ *
+ * **The body is a program the machine already knows how to run.** It holds the
+ * tables a program holds for the machine of section 3 and none of the tables
+ * that describe a chart, so the whole of this file is: build a program-shaped
+ * view whose code, frame, registers, cells, states, functions and loops are the
+ * body's own, keep the constant pool and the library manifest the program's,
+ * and drive the same interpreter over it once per requested bar. Nothing new is
+ * asked of the instruction loop, which is why the body ends in `RET` rather
+ * than in an opcode of its own.
+ *
+ * **Every table is counted from zero and none of them is the program's.** The
+ * registers are the requested instrument's bars and the cells and state regions
+ * step once per requested bar, so an engine that reached into the program's
+ * tables would put this chart's history behind another chart's name. The two
+ * that are shared, `consts` and `lib.functions`, hold nothing that depends on a
+ * bar.
+ *
+ * **A requested bar moves exactly as the chart's newest bar does.** `settle` is
+ * a bar that has closed and `peek` is the one still forming, and `peek` rolls
+ * the state back before it runs so that peeking the same bucket on ten chart
+ * bars gives the same answer as peeking it once. That is the mechanism of
+ * section 6 applied one level down, and it is what makes a `"developing"` read
+ * mean the bucket so far rather than the bucket in full.
+ */
+import type { Span } from '../span/index.js';
+import { barField, factsFor } from './bars.js';
+import type { HostBar } from './bars.js';
+import { Budget, stepBound } from './budget.js';
+import type { Clock, EngineLimits } from './budget.js';
+import { Channels } from './channels.js';
+import { guardFor } from './guard.js';
+import { Machine } from './machine.js';
+import { NO_SESSION } from './session/index.js';
+import { Memory } from './memory.js';
+import { Registers } from './registers.js';
+import type { BarView, HostFacts, ManifestEntry, PositionFacts } from './library/index.js';
+import type { CompiledProgram, Position, Request } from './types.js';
+import { ABSENT, Heap, isRef, reference } from './values/index.js';
+import type { Value } from './values/index.js';
+
+/** One setting the body reads, resolved once at load like every other input. */
+export interface BodyInput {
+  readonly series: number;
+  readonly value: Value;
+}
+
+/**
+ * The reads written inside this one, as the body drives them.
+ *
+ * Declared here rather than imported, so the dependency points one way: the
+ * fold knows about a body and a body knows only the shape of what it has to
+ * step. A nested read folds the bars this body is running on, which are handed
+ * over one requested bar at a time, so a nested `"lookahead"` read sees no
+ * further than the requested bar being executed. That is the same thing the
+ * mode does on a live chart's newest bucket, one level down.
+ */
+export interface NestedRequests {
+  readonly empty: boolean;
+  fill(
+    registers: Registers,
+    bars: readonly HostBar[],
+    index: number,
+    fresh: boolean,
+  ): void;
+}
+
+export interface BodyParts {
+  /** The program-shaped view of the body, built by `bodyProgram`. */
+  readonly program: CompiledProgram;
+  readonly limits: EngineLimits;
+  readonly clock: Clock | undefined;
+  readonly host: HostFacts;
+  readonly position: PositionFacts;
+  readonly library: readonly ManifestEntry[];
+  readonly inputs: readonly BodyInput[];
+  readonly nested: NestedRequests | undefined;
+  spanAt(line: number, column: number): Span;
+}
+
+/**
+ * The body's tables wearing a program's shape.
+ *
+ * A copy of the parent with nine fields replaced, rather than a second
+ * declaration, so that the one thing the two share by design, the constant pool
+ * and the manifest, is shared by construction and cannot drift.
+ */
+export function bodyProgram(parent: CompiledProgram, request: Request): CompiledProgram {
+  const body = request.body;
+  return {
+    ...parent,
+    frame: body.frame,
+    series: body.series,
+    cells: body.cells,
+    states: body.states,
+    functions: body.functions,
+    callSites: body.callSites,
+    loops: body.loops,
+    code: body.code,
+    requests: body.requests,
+    debug: { ...parent.debug, pos: body.pos, fnPos: body.fnPos },
+  };
+}
+
+export class RequestBody {
+  private readonly parts: BodyParts;
+  private readonly registers: Registers;
+  private readonly memory: Memory;
+  private readonly heap = new Heap();
+  private readonly budget: Budget;
+  private readonly machine: Machine;
+
+  /** Requested bars that have closed, which is the index the next one takes. */
+  private settled = 0;
+  /** Executions of the requested bar currently forming, for `bar.updates`. */
+  private touches = 0;
+  /** The previous requested bar's close, which `trueRange` inside a body needs. */
+  private lastClose: number | null = null;
+  /** The requested bars themselves, kept only when a read inside folds them. */
+  private readonly history: HostBar[] = [];
+  /**
+   * The value the last closed requested bar handed back.
+   *
+   * Held so that the sweep does not reclaim it. A confirmed read takes the last
+   * closed bucket's value on every chart bar of the next bucket, so the value
+   * outlives the execution that produced it, and if it is an object the object
+   * has to outlive it too.
+   */
+  private handed: Value = ABSENT;
+
+  constructor(parts: BodyParts) {
+    this.parts = parts;
+    const { program } = parts;
+    this.registers = new Registers(program.series.length);
+    this.memory = new Memory(program.cells, program.states);
+    this.budget = new Budget(
+      parts.limits,
+      parts.limits.steps ?? stepBound(program),
+      program.limits.loops,
+      parts.clock,
+    );
+
+    const fnPositions: (readonly Position[])[] = program.functions.map(() => []);
+    for (const [fn, positions] of program.debug.fnPos) fnPositions[fn] = positions;
+
+    this.machine = new Machine(
+      {
+        program,
+        registers: this.registers,
+        memory: this.memory,
+        // A read carries no channel, no plot and no declaration: those are the
+        // calls the language refuses inside a request expression, so nothing in
+        // a body can write a column and verification refuses an `EMIT` against
+        // an empty table.
+        channels: new Channels([]),
+        heap: this.heap,
+        budget: this.budget,
+        guard: guardFor(this.budget),
+        host: parts.host,
+        position: parts.position,
+        library: parts.library,
+        fnPositions,
+        spanAt: parts.spanAt,
+      },
+      this.viewOf({ open: null, high: null, low: null, close: null, time: null }, 0, false),
+    );
+  }
+
+  /** How many requested bars have closed, which a warmup is counted against. */
+  get closed(): number {
+    return this.settled;
+  }
+
+  /** The body's own heap, which a read written inside it lands its value in. */
+  get objects(): Heap {
+    return this.heap;
+  }
+
+  /**
+   * The requested bar still forming.
+   *
+   * Rolls back to the last closed bar first, so a bucket peeked on every chart
+   * bar inside it costs one execution each and leaves no trace of the previous
+   * one. Nothing is committed: the bucket is still moving.
+   */
+  peek(bar: HostBar): Value {
+    const value = this.execute(bar, false);
+    this.touches += 1;
+    return value;
+  }
+
+  /**
+   * The requested bar has closed.
+   *
+   * The last execution of that bar is the one that counts, and the state it
+   * leaves becomes the checkpoint the next bar starts from. `settle` is
+   * idempotent only in the sense every checkpoint is: it is called once per
+   * requested bar, by the one place that knows a bucket has ended.
+   */
+  settle(bar: HostBar): Value {
+    const value = this.execute(bar, true);
+    this.handed = value;
+    this.memory.commit();
+    this.heap.commit();
+    this.heap.sweep((visit) => {
+      this.memory.walk(visit);
+      this.registers.walk(visit);
+      visit(this.handed);
+    });
+    this.registers.trim(this.settled, this.parts.program.limits.history);
+    this.lastClose = bar.close ?? null;
+    this.settled += 1;
+    this.touches = 0;
+    return value;
+  }
+
+  private execute(bar: HostBar, closed: boolean): Value {
+    const index = this.settled;
+    // Steps 1 and 2 of the bar cycle, one level down: the checkpoint from the
+    // end of the previous requested bar, and the history entry this bar may
+    // already have written.
+    this.memory.rollback();
+    this.heap.rollback();
+    this.registers.truncate(index);
+    this.registers.clearCurrent();
+    this.budget.begin(index);
+
+    const view = this.viewOf(bar, index, closed);
+    this.machine.begin(view, index);
+
+    const facts = factsFor(
+      index,
+      // A bar that has closed is not the last one: something later is what
+      // closed it. The one still forming is.
+      index + (closed ? 2 : 1),
+      { isConfirmed: closed },
+      this.touches === 0,
+      this.touches + 1,
+      NO_SESSION,
+    );
+    for (const register of this.parts.program.series) {
+      if (register.kind !== 'bar' || register.field === null) continue;
+      this.registers.set(register.id, barField(register.field, bar, facts));
+    }
+    // A body is one expression with no statement to write a slot from, so a
+    // setting it reads arrives as a register rather than as a slot (2.16.1).
+    for (const input of this.parts.inputs) this.registers.set(input.series, input.value);
+
+    const nested = this.parts.nested;
+    if (nested !== undefined && !nested.empty) {
+      this.history[index] = bar;
+      nested.fill(this.registers, this.history, index, this.touches === 0);
+    }
+
+    this.machine.run();
+    this.registers.close(index);
+    return this.machine.result();
+  }
+
+  /**
+   * A value the body produced, as a value of the machine that asked for it.
+   *
+   * A number, a string, a colour or absence is the same value in both, and
+   * nothing is copied. An object is not: a reference is an index into one heap,
+   * and the body's heap is its own, so handing the index over would name
+   * whatever the other heap happens to hold at that index. So the object is
+   * copied, and copied again on every bar that reads it, because the copy lives
+   * in a heap whose rollback undoes the bar it was made on.
+   *
+   * Only an array can arrive here. A read that declared a grid or drew an object
+   * is refused at the call (OS3006), so those two kinds cannot exist in a body.
+   */
+  carry(value: Value, into: Heap): Value {
+    return copyInto(value, this.heap, into, new Map<number, number>());
+  }
+
+  private viewOf(bar: HostBar, index: number, closed: boolean): BarView {
+    return {
+      index,
+      open: bar.open ?? null,
+      high: bar.high ?? null,
+      low: bar.low ?? null,
+      close: bar.close ?? null,
+      volume: bar.volume ?? null,
+      time: bar.time ?? null,
+      previousClose: this.lastClose,
+      isConfirmed: closed,
+      isRealtime: false,
+      isNew: this.touches === 0,
+      isLast: !closed,
+      updates: this.touches + 1,
+      // The instrument record describes the chart's instrument, not the one a
+      // read names, and a requested bar is not on the chart's own grid either.
+      // So a body has no session, and it is told absence rather than false: a
+      // false would say this bar closes no session, which is a claim about an
+      // instrument whose hours the engine was never given.
+      isSessionFirst: null,
+      isSessionLast: null,
+    };
+  }
+}
+
+/**
+ * One value copied from one heap into another, sharing what it shared.
+ *
+ * The map is what keeps two references to one array two references to one copy,
+ * and it is what stops a value that refers to itself from recursing forever.
+ */
+function copyInto(
+  value: Value,
+  from: Heap,
+  into: Heap,
+  copied: Map<number, number>,
+): Value {
+  if (!isRef(value)) return value;
+  const already = copied.get(value.id);
+  if (already !== undefined) return reference(already);
+  const object = from.get(value.id);
+  if (object === undefined || object.kind !== 'array') return ABSENT;
+  const items: Value[] = [];
+  const id = into.allocate({ kind: 'array', items });
+  copied.set(value.id, id);
+  for (const item of object.items) items.push(copyInto(item, from, into, copied));
+  into.countElements(items.length);
+  return reference(id);
+}

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

@@ -0,0 +1,270 @@
+/**
+ * What is settled about a read before bar 0, `compiled-program.md` 2.16.
+ *
+ * **A request's identity is fixed before bar 0.** That is what lets the whole
+ * set be known at load, what lets a host fetch in parallel and cache by
+ * instrument and timeframe, and what makes a request that changed afterwards
+ * OS6013. So the three identity fields are resolved here, once, from the value
+ * the script wrote, the setting it named or the chart fact it named, and
+ * nothing below bar 0 ever asks again.
+ *
+ * **Two refusals belong at load and four belong to the host.** A timeframe the
+ * language does not know (OS6001), one finer than the chart's (OS6002) and one
+ * that does not fold into the chart's (OS6015) are facts about the program and
+ * the chart, both known before a bar runs, so they stop the load and name what
+ * was refused. An unknown instrument (OS6007), a range with no bars (OS6008), a
+ * source that refused (OS6009) and an interval the feed does not carry (OS6014)
+ * are the host's answers: they leave the read absent, put the reason in
+ * `req.error(read)` and let the study keep drawing everything else, which is
+ * `stdlib.md` 15.5.
+ */
+import { diagnosticFor } from '../diagnostics/index.js';
+import type { Diagnostic } from '../diagnostics/index.js';
+import { NO_POSITION, failure } from './errors.js';
+import type { EngineHost, RequestAnswer, RequestQuery, RequestRefusal } from './host.js';
+import type { ResolvedInput } from './inputs.js';
+import type { Request, RequestField } from './types.js';
+import { foldRefusal, isIntraday, parseTimeframe } from './timeframe.js';
+import type { Timeframe } from './timeframe.js';
+
+/** What a read holds once its identity, its timeframe and its source are fixed. */
+export interface RequestPlan {
+  readonly request: Request;
+  readonly query: RequestQuery;
+  readonly timeframe: Timeframe;
+  /** The zone a calendar bucket is dated in, or nothing when none was stated. */
+  readonly zone: string | null;
+}
+
+export type PlanResult =
+  | { readonly ok: true; readonly plans: readonly RequestPlan[] }
+  | { readonly ok: false; readonly diagnostic: Diagnostic };
+
+/**
+ * One of the three identity fields, resolved.
+ *
+ * Three forms and no fourth: the string the script wrote, the value of the
+ * setting it named, and one of the three chart facts that identify a chart
+ * rather than describe it.
+ */
+export function identityOf(
+  field: RequestField,
+  inputs: readonly ResolvedInput[],
+  host: EngineHost,
+): string | null {
+  if (typeof field === 'string') return field;
+  if (field === null || typeof field !== 'object' || Array.isArray(field)) return null;
+
+  const named = field as { readonly input?: string; readonly chart?: string };
+  if (typeof named.input === 'string') {
+    const found = inputs.find((one) => one.key === named.input);
+    return typeof found?.value === 'string' ? found.value : null;
+  }
+  if (named.chart === 'symbol') return host.instrument?.symbol ?? null;
+  if (named.chart === 'exchange') return host.instrument?.exchange ?? null;
+  if (named.chart === 'interval') return host.instrument?.interval ?? null;
+  return null;
+}
+
+/**
+ * Every read the program makes, with its identity settled.
+ *
+ * Walks the nested reads as well, because a read written inside another is part
+ * of the program and a host handed a list with one missing would fetch less
+ * than the file asks for.
+ */
+export function planRequests(
+  requests: readonly Request[],
+  inputs: readonly ResolvedInput[],
+  host: EngineHost,
+): PlanResult {
+  const chart = chartTimeframe(host);
+  const plans: RequestPlan[] = [];
+  const problem = collect(requests, inputs, host, chart, plans);
+  if (problem !== undefined) return { ok: false, diagnostic: problem };
+  return { ok: true, plans };
+}
+
+function collect(
+  requests: readonly Request[],
+  inputs: readonly ResolvedInput[],
+  host: EngineHost,
+  chart: Timeframe | undefined,
+  into: RequestPlan[],
+): Diagnostic | undefined {
+  for (const request of requests) {
+    const written = identityOf(request.timeframe, inputs, host);
+    const timeframe = written === null ? undefined : parseTimeframe(written);
+    if (timeframe === undefined) {
+      return failure('OS6001', NO_POSITION, { value: written ?? 'nothing' });
+    }
+    // The chart's interval is a host fact and a host may state none. Without it
+    // there is nothing to compare a request against, so the two comparisons are
+    // skipped rather than answered from a value nobody supplied.
+    const refusal = chart === undefined ? undefined : foldRefusal(timeframe, chart);
+    if (refusal !== undefined && chart !== undefined) {
+      if (refusal.code === 'OS6002') {
+        return failure('OS6002', NO_POSITION, { chart: chart.text, requested: timeframe.text });
+      }
+      return failure('OS6015', NO_POSITION, {
+        requested: timeframe.text,
+        chart: chart.text,
+        suggestion: refusal.suggestion,
+      });
+    }
+
+    into.push({
+      request,
+      timeframe,
+      zone: host.instrument?.timezone ?? null,
+      query: {
+        id: request.id,
+        read: request.read,
+        instrument: instrumentOf(request, inputs, host),
+        exchange: exchangeOf(request, inputs, host),
+        timeframe: timeframe.text,
+        mode: request.mode,
+        warmup: request.warmup,
+      },
+    });
+    const nested = collect(request.body.requests, inputs, host, timeframe, into);
+    if (nested !== undefined) return nested;
+  }
+  return undefined;
+}
+
+/**
+ * The instrument a read asks about, with the format's own default applied.
+ *
+ * 2.16 spells a read of the chart's own instrument as a `null` `symbol`, so
+ * resolving it here is applying the format's rule rather than inventing one:
+ * the host is handed the identity it gave for the chart, which is what
+ * `host-interface.md` 5.2 says a request carries.
+ *
+ * **The default belongs to a `"timeframe"` read and to nothing else.** A
+ * `"symbol"` read whose identity did not resolve, because the setting behind it
+ * holds something that is not an instrument, stays absent. Falling back there
+ * would turn a read of another instrument into a second read of this one, and
+ * the study would draw a line nobody asked for with nothing to say it had
+ * substituted anything.
+ */
+function instrumentOf(
+  request: Request,
+  inputs: readonly ResolvedInput[],
+  host: EngineHost,
+): string | null {
+  const named = identityOf(request.symbol, inputs, host);
+  if (named !== null) return named;
+  return request.read === 'timeframe' ? host.instrument?.symbol ?? null : null;
+}
+
+/**
+ * Where a read's instrument trades, with `stdlib.md` 15.1's default applied.
+ *
+ * `req.symbol`'s signature defaults `exchange` to `chart.exchange`, and 2.16
+ * spells the omission as `null`, "means the chart's exchange". A host handed
+ * that `null` would have to apply the rule against the record it supplied, and
+ * a host that applied it differently, or not at all, would resolve an
+ * instrument on a venue the script never named. So it is applied once, here.
+ */
+function exchangeOf(
+  request: Request,
+  inputs: readonly ResolvedInput[],
+  host: EngineHost,
+): string | null {
+  return identityOf(request.exchange, inputs, host) ?? host.instrument?.exchange ?? null;
+}
+
+/** The chart's own interval as a timeframe, when the host stated a usable one. */
+function chartTimeframe(host: EngineHost): Timeframe | undefined {
+  const interval = host.instrument?.interval;
+  return interval === undefined ? undefined : parseTimeframe(interval);
+}
+
+/**
+ * What the host says about one read.
+ *
+ * A host with no provider is not asked. A read of the chart's own instrument is
+ * then folded from the bars the engine already holds, and a read of another
+ * instrument cannot be: the engine holds none of that instrument's bars, so
+ * nothing to serve is the same answer as an instrument the host does not know.
+ */
+export function askHost(plan: RequestPlan, host: EngineHost): RequestAnswer | undefined {
+  const answer = host.requestBars?.(plan.query);
+  if (answer !== undefined) return answer;
+  if (plan.query.read === 'timeframe') return undefined;
+  return { refused: { code: 'OS6007' } };
+}
+
+/**
+ * Whether this read can date a bucket at all.
+ *
+ * A day, week or month request is folded by the calendar, and a calendar
+ * boundary is a civil date read in a zone (`timeframe.ts`). A host that stated
+ * no timezone leaves the fold with no key for any bar, so the read is absent on
+ * every bar of the run and will be on every future one: nothing that arrives
+ * later supplies a fact the instrument record does not hold.
+ *
+ * That is a dead read, and a dead read a study cannot explain is the worst of
+ * the three: the trader has already looked at the blank pane. So it is answered
+ * here rather than left as absence, and `req.isReady` and `req.error` say it.
+ */
+export function undatable(plan: RequestPlan): boolean {
+  return !isIntraday(plan.timeframe) && plan.zone === null;
+}
+
+/**
+ * What `req.error(read)` says about a read with no zone to date its buckets.
+ *
+ * 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.
+ */
+export function undatableReason(query: RequestQuery): string {
+  return diagnosticFor('OS6012', NO_POSITION, { fact: 'a timezone', symbol: named(query) }).message;
+}
+
+/** The instrument a reason names: the one the read asked for, or the chart's. */
+function named(query: RequestQuery): string {
+  return query.instrument ?? 'the chart\'s instrument';
+}
+
+/**
+ * The reason a refusal reads as through `req.error(read)`.
+ *
+ * The catalogue's own message, filled with the identity the read asked for and
+ * with the host's own words where it gave them. The host's words are carried
+ * and not paraphrased, because "the account's data subscription does not cover
+ * this instrument" is actionable and "the request failed" is not.
+ */
+export function reasonFor(refusal: RequestRefusal, query: RequestQuery): string {
+  const symbol = named(query);
+  const exchange = query.exchange ?? 'the chart\'s exchange';
+  const reason = refusal.reason ?? 'the host gave no reason';
+  switch (refusal.code) {
+    case 'OS6007':
+      return diagnosticFor('OS6007', NO_POSITION, { symbol, exchange }).message;
+    case 'OS6008':
+      return diagnosticFor('OS6008', NO_POSITION, { symbol, timeframe: query.timeframe }).message;
+    case 'OS6014':
+      return diagnosticFor('OS6014', NO_POSITION, {
+        timeframe: query.timeframe,
+        symbol,
+        available: refusal.available ?? 'nothing it named',
+      }).message;
+    case 'OS6015':
+      return diagnosticFor('OS6015', NO_POSITION, {
+        requested: query.timeframe,
+        chart: 'the chart\'s interval',
+        suggestion: refusal.available ?? 'a whole multiple of it',
+      }).message;
+    default:
+      return diagnosticFor('OS6009', NO_POSITION, {
+        symbol,
+        timeframe: query.timeframe,
+        reason,
+      }).message;
+  }
+}