openalgo-script 0.1.0-alpha.1 → 0.4.0

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

@@ -0,0 +1,103 @@
+/**
+ * The engine's library manifest: what a `CALL_LIB` can name, and what each
+ * entry does.
+ *
+ * `compiled-program.md` 2.5 gives this table its job. A compiled program
+ * carries its own copy of every function it calls, with the name, the argument
+ * count, whether the function holds state and what effect it has, and at load
+ * the engine compares each entry against this one. A mismatch is OS6004, and
+ * the entries carry facts the engine already knows precisely so that they can
+ * be disagreed with: it catches a program compiled against a newer library
+ * before it computes a single wrong number.
+ *
+ * **A name this engine does not implement is refused at load, not at the call.**
+ * The alternative, discovering it halfway through bar nine thousand, would give
+ * a user a broken chart and a message about a function rather than a message
+ * before anything was drawn.
+ *
+ * The table is keyed by name and argument count, because the library has names
+ * with more than one signature: `text` takes one value or a value and a digit
+ * count, and `min` takes two numbers or one array. The one pair that shares a
+ * name **and** a count is `clear`, which empties an array or a grid, and the
+ * engine tells those apart by asking the heap what the handle points at.
+ */
+import { ARRAY_ENTRIES } from './arrays.js';
+import { AVERAGE_ENTRIES } from './averages.js';
+import { CHART_ENTRIES } from './chart.js';
+import { COLOUR_ENTRIES } from './colours.js';
+import { DATE_ENTRIES } from './dates.js';
+import { MATHS_ENTRIES } from './maths.js';
+import { OBJECT_ENTRIES } from './objects.js';
+import { OSCILLATOR_ENTRIES } from './oscillators.js';
+import { RANGE_ENTRIES } from './ranges.js';
+import { SERIES_ENTRIES } from './series.js';
+import { STUDY_ENTRIES } from './studies.js';
+import { TEXT_ENTRIES } from './text.js';
+import { TREND_ENTRIES } from './trend.js';
+import { VOLUME_ENTRIES } from './volume.js';
+import type { ManifestEntry } from './binding.js';
+
+const ENTRIES: readonly ManifestEntry[] = [
+  ...COLOUR_ENTRIES,
+  ...MATHS_ENTRIES,
+  ...TEXT_ENTRIES,
+  ...ARRAY_ENTRIES,
+  ...SERIES_ENTRIES,
+  ...AVERAGE_ENTRIES,
+  ...STUDY_ENTRIES,
+  ...TREND_ENTRIES,
+  ...OSCILLATOR_ENTRIES,
+  ...RANGE_ENTRIES,
+  ...VOLUME_ENTRIES,
+  ...OBJECT_ENTRIES,
+  ...CHART_ENTRIES,
+  ...DATE_ENTRIES,
+];
+
+function keyOf(name: string, arity: number): string {
+  return `${name}/${arity}`;
+}
+
+const INDEX = new Map<string, ManifestEntry>();
+const ARITIES = new Map<string, number[]>();
+for (const one of ENTRIES) {
+  INDEX.set(keyOf(one.name, one.arity), one);
+  const known = ARITIES.get(one.name);
+  if (known === undefined) ARITIES.set(one.name, [one.arity]);
+  else known.push(one.arity);
+}
+
+/** The entry for one name and argument count, or nothing when there is none. */
+export function manifestEntry(name: string, arity: number): ManifestEntry | undefined {
+  return INDEX.get(keyOf(name, arity));
+}
+
+/** What this engine has under a name, for OS6004's message. */
+export function manifestSays(name: string): string {
+  const arities = ARITIES.get(name);
+  if (arities === undefined) return `no function called ${name}`;
+  const counts = [...arities].sort((a, b) => a - b).join(' or ');
+  return `${name} with ${counts} argument${arities.length === 1 && arities[0] === 1 ? '' : 's'}`;
+}
+
+/** Every entry, for the test that compares this table with the checker's. */
+export function manifestEntries(): readonly ManifestEntry[] {
+  return ENTRIES;
+}
+
+export type {
+  BarView,
+  CallContext,
+  Effect,
+  Guard,
+  HostFacts,
+  LibraryCall,
+  ManifestEntry,
+  PositionFacts,
+} from './binding.js';
+
+export type { StateRecord, StateSlot } from './state.js';
+export { copyState } from './state.js';
+
+export { COLOUR_NAMES, namedColour } from './colours.js';
+export { spell } from './text.js';

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

@@ -0,0 +1,134 @@
+/**
+ * The arithmetic calls, `stdlib.md` section 8.
+ *
+ * Every one of them is the numeric library's, called through. The numbers are
+ * computed under `src/core/stdlib`, which depends on nothing else in the
+ * repository and is tested against reference vectors on its own, and this file
+ * is the wiring that hands it two engine values and takes one back. A second
+ * implementation here would be a second accumulation order waiting to drift,
+ * and section 8.3 makes that a release blocker rather than a tidiness problem.
+ *
+ * Three calls are not numeric and are here because they are written in the same
+ * place in the library's own tables: `isNone`, `orElse` and `bool` take any
+ * value, so they read the engine's value rather than a number.
+ */
+import {
+  E,
+  PI,
+  abs,
+  acos,
+  asin,
+  atan,
+  atan2,
+  ceil,
+  clamp,
+  cos,
+  exp,
+  floor,
+  hypot,
+  log,
+  log10,
+  log2,
+  max,
+  min,
+  mod,
+  pow,
+  round,
+  roundTo,
+  roundToStep,
+  sign,
+  sin,
+  sqrt,
+  tan,
+  toDegrees,
+  toRadians,
+  trunc,
+} from '../../stdlib/index.js';
+import { isNumber } from '../values/index.js';
+import { entry, numberAt, valueAt, wholeAt } from './binding.js';
+import type { ManifestEntry } from './binding.js';
+
+/** A one argument numeric call. */
+function one(name: string, param: string, of: (x: number | null) => number | null): ManifestEntry {
+  return entry(name, param, (_ctx, args) => of(numberAt(args, 0)));
+}
+
+/** A two argument numeric call. */
+function two(
+  name: string,
+  params: string,
+  of: (a: number | null, b: number | null) => number | null,
+): ManifestEntry {
+  return entry(name, params, (_ctx, args) => of(numberAt(args, 0), numberAt(args, 1)));
+}
+
+/** A constant read bare, which the format still compiles to a call of no arguments. */
+function constant(name: string, value: number): ManifestEntry {
+  return entry(name, '', () => value);
+}
+
+export const MATHS_ENTRIES: readonly ManifestEntry[] = [
+  one('abs', 'x', abs),
+  one('sign', 'x', sign),
+  one('sqrt', 'x', sqrt),
+  one('exp', 'x', exp),
+  one('log', 'x', log),
+  one('log10', 'x', log10),
+  one('floor', 'x', floor),
+  one('ceil', 'x', ceil),
+  one('trunc', 'x', trunc),
+  one('round', 'x', round),
+  two('min', 'a b', min),
+  two('max', 'a b', max),
+  two('mod', 'a b', mod),
+  two('pow', 'x y', pow),
+  two('roundToStep', 'x step', roundToStep),
+
+  entry('clamp', 'x lo hi', (_ctx, args) =>
+    clamp(numberAt(args, 0), numberAt(args, 1), numberAt(args, 2)),
+  ),
+
+  // The digit count is a whole number of zero or more. A fractional one is a
+  // bug in the script rather than a value to round on the script's behalf.
+  entry('round', 'x decimals', (ctx, args) => {
+    const decimals = wholeAt(ctx, 'round', 'decimals', args, 1);
+    return decimals === null ? null : roundTo(numberAt(args, 0), decimals);
+  }),
+
+  /**
+   * `roundToTick(price)`: to the instrument's tick.
+   *
+   * Absent when the host states no tick size, rather than the price unrounded.
+   * An order at a price that is not on a tick is refused by a venue, so a
+   * script that cannot round has to be able to see that it cannot.
+   */
+  entry('roundToTick', 'price', (ctx, args) => {
+    const tick = ctx.host.tickSize();
+    if (!isNumber(tick)) return null;
+    return roundToStep(numberAt(args, 0), tick);
+  }),
+
+  constant('math.pi', PI),
+  constant('math.e', E),
+  one('math.log2', 'x', log2),
+  one('math.sin', 'x', sin),
+  one('math.cos', 'x', cos),
+  one('math.tan', 'x', tan),
+  one('math.asin', 'x', asin),
+  one('math.acos', 'x', acos),
+  one('math.atan', 'x', atan),
+  one('math.toDegrees', 'x', toDegrees),
+  one('math.toRadians', 'x', toRadians),
+  two('math.hypot', 'x y', hypot),
+  two('math.atan2', 'y x', atan2),
+
+  entry('isNone', 'x', (_ctx, args) => valueAt(args, 0) === null),
+  entry('orElse', 'x fallback', (_ctx, args) => {
+    const value = valueAt(args, 0);
+    return value === null ? valueAt(args, 1) : value;
+  }),
+  // `toBool(x)`: absence to false, a bool to itself. A number is a type error
+  // the checker refuses, so an engine that reaches one is looking at a program
+  // its verifier should not have accepted, and absence is the safe reading.
+  entry('toBool', 'x', (_ctx, args) => valueAt(args, 0) === true),
+];

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

@@ -0,0 +1,265 @@
+/**
+ * Drawing objects and grid cells, `stdlib.md` section 14.
+ *
+ * Neither goes through a channel, and `compiled-program.md` 4.11 says why: both
+ * would need an unbounded number of them, and a channel is by definition one
+ * value per bar. A line, label or box is an object in the heap that a script
+ * creates once and mutates over many bars; a grid is a handle the engine puts
+ * in a slot and its cells are a per-bar buffer.
+ *
+ * **A drawing object rolls back with everything else.** A moving bar that
+ * re-executes ten times must leave one box behind rather than ten, and the
+ * object is in the heap, so the heap's undo journal already carries it. Section
+ * 6.1's list of what a checkpoint holds does not name the drawing roster
+ * separately, and it has to be part of it: without that, creation would survive
+ * a rollback and the chart would accumulate a copy per tick.
+ *
+ * **A deleted object stays deleted rather than becoming absent.** OS4005 names
+ * the bar it was deleted on, because a script that mutates a stale handle is
+ * holding a name for something it already threw away, and answering "absent"
+ * would hide that behind a drawing that quietly stopped moving. An *absent*
+ * handle is a different fact and does nothing: a setter given `none` is a gap
+ * like every other absence reaching a drawing surface (`language.md` 6.7), and
+ * it is what the fix for OS4005 asks a script to produce.
+ *
+ * **An object is anchored to a time and a price and to nothing else.** Neither
+ * anchor is read against the bars: an anchor past the newest bar is kept as it
+ * was given, so a projected line reaches into the margin, and an anchor inside
+ * the history does not move when more history loads and every bar index
+ * shifts. A bar index is a position in the data the engine was given
+ * (`language.md` 7.2), and an object that stored one would be somewhere else
+ * on the same chart tomorrow.
+ *
+ * **A polyline holds its own path.** The two arrays it is given are read once,
+ * at the call, and the points are the object's from then on; `draw.setPoints`
+ * is how a path changes. The alternative, keeping the arrays and reading them
+ * when the host draws, would mean a `push` to an array the script kept for its
+ * own bookkeeping silently redrawing a shape, and two engines could then
+ * disagree about when the path was read.
+ */
+import type { DrawingObject, GridCell, Value } from '../values/index.js';
+import { isDrawing, isNumber, reference } from '../values/index.js';
+import { entry, refAt, valueAt, wholeAt } from './binding.js';
+import type { CallContext, ManifestEntry } from './binding.js';
+import { clearArray } from './arrays.js';
+
+/** The drawing object a handle names, refusing one the script already deleted. */
+function drawing(ctx: CallContext, args: readonly Value[], index: number): DrawingObject | undefined {
+  const handle = refAt(args, index);
+  if (handle === null) return undefined;
+  const object = ctx.heap.get(handle.id);
+  if (object === undefined || !isDrawing(object)) return undefined;
+  if (object.deleted) ctx.guard.deleted(ctx.span, object.kind, object.deletedAt);
+  ctx.heap.touch(handle.id);
+  return object;
+}
+
+/**
+ * Creates one object, once the ceiling has been asked.
+ *
+ * The properties arrive as a function rather than as a record so that the
+ * ceiling is charged before any of the work: a polyline copies its whole path
+ * into the heap, and an engine that built that and then refused to keep it
+ * would have spent the memory it was refusing to spend.
+ */
+function make(
+  ctx: CallContext,
+  kind: DrawingObject['kind'],
+  props: () => Record<string, Value>,
+): Value {
+  ctx.guard.drawing(ctx.span, ctx.heap.drawingCount());
+  const id = ctx.heap.allocate({ kind, props: props(), deleted: false, deletedAt: -1 });
+  return reference(id);
+}
+
+/** The numbers one path argument holds, or an empty path when it holds none. */
+function pointsIn(ctx: CallContext, args: readonly Value[], index: number): readonly Value[] {
+  const held = ctx.heap.deref(valueAt(args, index));
+  return held !== undefined && held.kind === 'array' ? held.items : [];
+}
+
+/**
+ * A polyline's path, copied out of the two arrays that describe it.
+ *
+ * The arrays are paired by index over the longer of them, so a script that
+ * supplies more times than prices gets a point with no price rather than a
+ * shorter path: absence reaching a drawing surface is a gap the host draws as a
+ * break (`language.md` 6.7), and dropping the odd points instead would quietly
+ * redraw the shape. A value that is not a number is absent for the same reason.
+ *
+ * The copies are heap arrays, so they are rolled back, swept and counted like
+ * every other object rather than being a second kind of storage.
+ */
+function path(ctx: CallContext, args: readonly Value[], first: number): Record<string, Value> {
+  const times = pointsIn(ctx, args, first);
+  const prices = pointsIn(ctx, args, first + 1);
+  const length = Math.max(times.length, prices.length);
+  const copy = (source: readonly Value[]): Value => {
+    const items: Value[] = [];
+    for (let i = 0; i < length; i += 1) {
+      const one = source[i];
+      items.push(one !== undefined && isNumber(one) ? one : null);
+    }
+    return reference(ctx.heap.allocate({ kind: 'array', items }));
+  };
+  return { times: copy(times), prices: copy(prices) };
+}
+
+/** A mutator that writes named fields onto an existing object. */
+function setter(
+  name: string,
+  params: string,
+  fields: (args: readonly Value[]) => Record<string, Value>,
+): ManifestEntry {
+  return entry(name, params, (ctx, args) => {
+    const object = drawing(ctx, args, 0);
+    if (object === undefined) return null;
+    object.props = { ...object.props, ...fields(args) };
+    return null;
+  });
+}
+
+export const OBJECT_ENTRIES: readonly ManifestEntry[] = [
+  entry('draw.line', 't1 p1 t2 p2 color width style extendLeft extendRight', (ctx, args) =>
+    make(ctx, 'line', () => ({
+      t1: valueAt(args, 0),
+      p1: valueAt(args, 1),
+      t2: valueAt(args, 2),
+      p2: valueAt(args, 3),
+      color: valueAt(args, 4),
+      width: valueAt(args, 5),
+      style: valueAt(args, 6),
+      extendLeft: valueAt(args, 7),
+      extendRight: valueAt(args, 8),
+    })),
+  ),
+
+  entry('draw.label', 't p text color textColor align tooltip', (ctx, args) =>
+    make(ctx, 'label', () => ({
+      t: valueAt(args, 0),
+      p: valueAt(args, 1),
+      text: valueAt(args, 2),
+      color: valueAt(args, 3),
+      textColor: valueAt(args, 4),
+      align: valueAt(args, 5),
+      tooltip: valueAt(args, 6),
+    })),
+  ),
+
+  entry(
+    'draw.box',
+    't1 p1 t2 p2 color fillColor opacity width text textColor tooltip',
+    (ctx, args) =>
+      make(ctx, 'box', () => ({
+        t1: valueAt(args, 0),
+        p1: valueAt(args, 1),
+        t2: valueAt(args, 2),
+        p2: valueAt(args, 3),
+        color: valueAt(args, 4),
+        fillColor: valueAt(args, 5),
+        opacity: valueAt(args, 6),
+        width: valueAt(args, 7),
+        text: valueAt(args, 8),
+        textColor: valueAt(args, 9),
+        tooltip: valueAt(args, 10),
+      })),
+  ),
+
+  entry('draw.polyline', 'times prices color width closed fillColor opacity', (ctx, args) =>
+    make(ctx, 'polyline', () => ({
+      ...path(ctx, args, 0),
+      color: valueAt(args, 2),
+      width: valueAt(args, 3),
+      closed: valueAt(args, 4),
+      fillColor: valueAt(args, 5),
+      opacity: valueAt(args, 6),
+    })),
+  ),
+
+  setter('draw.setFrom', 'obj t p', (args) => ({ t1: valueAt(args, 1), p1: valueAt(args, 2) })),
+  setter('draw.setTo', 'obj t p', (args) => ({ t2: valueAt(args, 1), p2: valueAt(args, 2) })),
+  setter('draw.setAt', 'obj t p', (args) => ({ t: valueAt(args, 1), p: valueAt(args, 2) })),
+  setter('draw.setBounds', 'obj t1 p1 t2 p2', (args) => ({
+    t1: valueAt(args, 1),
+    p1: valueAt(args, 2),
+    t2: valueAt(args, 3),
+    p2: valueAt(args, 4),
+  })),
+  entry('draw.setPoints', 'obj times prices', (ctx, args) => {
+    const object = drawing(ctx, args, 0);
+    if (object === undefined) return null;
+    object.props = { ...object.props, ...path(ctx, args, 1) };
+    return null;
+  }),
+  setter('draw.setText', 'obj text', (args) => ({ text: valueAt(args, 1) })),
+  setter('draw.setColor', 'obj color', (args) => ({ color: valueAt(args, 1) })),
+  setter('draw.setTextColor', 'obj color', (args) => ({ textColor: valueAt(args, 1) })),
+  setter('draw.setFillColor', 'obj color', (args) => ({ fillColor: valueAt(args, 1) })),
+  setter('draw.setWidth', 'obj width', (args) => ({ width: valueAt(args, 1) })),
+  setter('draw.setStyle', 'obj style', (args) => ({ style: valueAt(args, 1) })),
+  setter('draw.setExtend', 'obj left right', (args) => ({
+    extendLeft: valueAt(args, 1),
+    extendRight: valueAt(args, 2),
+  })),
+  setter('draw.setTooltip', 'obj text', (args) => ({ tooltip: valueAt(args, 1) })),
+
+  // Deleting twice is not an error: the script asked for the object to be gone
+  // and it is gone. Only a change to a deleted object is OS4005.
+  entry('draw.delete', 'obj', (ctx, args) => {
+    const handle = refAt(args, 0);
+    if (handle !== null) ctx.heap.deleteDrawing(handle.id, ctx.bar.index);
+    return null;
+  }),
+
+  entry('draw.deleteAll', '', (ctx) => {
+    for (const { id } of ctx.heap.drawings()) ctx.heap.deleteDrawing(id, ctx.bar.index);
+    return null;
+  }),
+
+  entry('draw.count', '', (ctx) => ctx.heap.drawingCount()),
+
+  /**
+   * `cell(t, row, col, text, ...)`: one cell of a grid for this bar.
+   *
+   * The buffer is emptied at step 3 of every execution, so a re-executed bar
+   * rebuilds the whole grid and a checkpoint holds none of it. That is why a
+   * grid needs no rollback of its own while a drawing object does.
+   */
+  entry('cell', 't row col text textColor bgColor align', (ctx, args) => {
+    const handle = refAt(args, 0);
+    if (handle === null) return null;
+    const object = ctx.heap.get(handle.id);
+    if (object === undefined || object.kind !== 'table') return null;
+    const row = wholeAt(ctx, 'cell', 'row', args, 1);
+    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,
+      );
+    }
+    const written: GridCell = {
+      row,
+      col,
+      text: valueAt(args, 3),
+      textColor: valueAt(args, 4),
+      bgColor: valueAt(args, 5),
+      align: valueAt(args, 6),
+    };
+    object.cells.push(written);
+    return null;
+  }),
+
+  entry('clear', 'handle', (ctx, args) => {
+    if (clearArray(ctx, args)) return null;
+    const handle = refAt(args, 0);
+    if (handle === null) return null;
+    const object = ctx.heap.get(handle.id);
+    if (object === undefined || object.kind !== 'table') return null;
+    object.cells = [];
+    return null;
+  }),
+];

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

@@ -0,0 +1,124 @@
+/**
+ * The momentum readings of `stdlib.md` section 5 that are not already wired
+ * beside the studies they share a file with.
+ *
+ * **Every number here is the numeric library's**, for the reason `series.ts`
+ * sets out beside the same wiring. Each entry is a call site and nothing more.
+ *
+ * Five of them read the bar rather than a source, and `stdlib.md` writes them
+ * without one for that reason: `stoch`, `cci`, `williamsR`, `ultimateOsc` and
+ * `awesomeOsc` are readings about the whole bar, so there is no source argument
+ * for a script to pass and none is invented here.
+ */
+import {
+  awesomeOscStep,
+  cciStep,
+  cmoStep,
+  dpoStep,
+  ppoStep,
+  stochRsiStep,
+  stochStep,
+  trixStep,
+  tsiStep,
+  ultimateOscStep,
+  williamsRStep,
+} from '../../stdlib/index.js';
+import { lengthAt, multi, numberAt } from './binding.js';
+import type { ManifestEntry } from './binding.js';
+import { stateful } from './state.js';
+
+export const OSCILLATOR_ENTRIES: readonly ManifestEntry[] = [
+  stateful('stoch', 'len smoothK smoothD', (ctx, args) =>
+    multi(
+      ctx,
+      stochStep(
+        ctx.state,
+        '',
+        ctx.bar,
+        lengthAt(ctx, 'stoch', 'len', args, 0),
+        lengthAt(ctx, 'stoch', 'smoothK', args, 1),
+        lengthAt(ctx, 'stoch', 'smoothD', args, 2),
+      ),
+    ),
+  ),
+
+  stateful('stochRsi', 'src rsiLen stochLen smoothK smoothD', (ctx, args) =>
+    multi(
+      ctx,
+      stochRsiStep(
+        ctx.state,
+        '',
+        numberAt(args, 0),
+        lengthAt(ctx, 'stochRsi', 'rsiLen', args, 1),
+        lengthAt(ctx, 'stochRsi', 'stochLen', args, 2),
+        lengthAt(ctx, 'stochRsi', 'smoothK', args, 3),
+        lengthAt(ctx, 'stochRsi', 'smoothD', args, 4),
+      ),
+    ),
+  ),
+
+  stateful('ppo', 'src fast slow signal', (ctx, args) =>
+    multi(
+      ctx,
+      ppoStep(
+        ctx.state,
+        '',
+        numberAt(args, 0),
+        lengthAt(ctx, 'ppo', 'fast', args, 1),
+        lengthAt(ctx, 'ppo', 'slow', args, 2),
+        lengthAt(ctx, 'ppo', 'signal', args, 3),
+      ),
+    ),
+  ),
+
+  stateful('cci', 'len', (ctx, args) =>
+    cciStep(ctx.state, '', ctx.bar, lengthAt(ctx, 'cci', 'len', args, 0)),
+  ),
+
+  stateful('williamsR', 'len', (ctx, args) =>
+    williamsRStep(ctx.state, '', ctx.bar, lengthAt(ctx, 'williamsR', 'len', args, 0)),
+  ),
+
+  stateful('tsi', 'src longLen shortLen', (ctx, args) =>
+    tsiStep(
+      ctx.state,
+      '',
+      numberAt(args, 0),
+      lengthAt(ctx, 'tsi', 'longLen', args, 1),
+      lengthAt(ctx, 'tsi', 'shortLen', args, 2),
+    ),
+  ),
+
+  stateful('trix', 'src len', (ctx, args) =>
+    trixStep(ctx.state, '', numberAt(args, 0), lengthAt(ctx, 'trix', 'len', args, 1)),
+  ),
+
+  stateful('cmo', 'src len', (ctx, args) =>
+    cmoStep(ctx.state, '', numberAt(args, 0), lengthAt(ctx, 'cmo', 'len', args, 1)),
+  ),
+
+  stateful('dpo', 'src len', (ctx, args) =>
+    dpoStep(ctx.state, '', numberAt(args, 0), lengthAt(ctx, 'dpo', 'len', args, 1)),
+  ),
+
+  stateful('ultimateOsc', 'len1 len2 len3', (ctx, args) =>
+    ultimateOscStep(
+      ctx.state,
+      '',
+      ctx.bar,
+      lengthAt(ctx, 'ultimateOsc', 'len1', args, 0),
+      lengthAt(ctx, 'ultimateOsc', 'len2', args, 1),
+      lengthAt(ctx, 'ultimateOsc', 'len3', args, 2),
+    ),
+  ),
+
+  stateful('awesomeOsc', 'fast slow', (ctx, args) =>
+    awesomeOscStep(
+      ctx.state,
+      '',
+      ctx.bar,
+      lengthAt(ctx, 'awesomeOsc', 'fast', args, 0),
+      lengthAt(ctx, 'awesomeOsc', 'slow', args, 1),
+    ),
+  ),
+];

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

@@ -0,0 +1,51 @@
+/**
+ * The three readings of `stdlib.md` section 6 that are not wired beside the
+ * bands they share a file with: `keltner`, `chop` and `hv`.
+ *
+ * **Every number here is the numeric library's**, for the reason `series.ts`
+ * sets out beside the same wiring.
+ *
+ * `keltner` and `chop` take the gap rather than the bar, because both are built
+ * on a true range and the previous close in one is the host's rather than one
+ * remembered at the call site: `range.ts` gives the reason. `keltner` is also
+ * handed the close and the volume, because its basis is `ma` over the close and
+ * that call can be switched to the volume weighted average.
+ */
+import { chopStep, hvStep, keltnerStep } from '../../stdlib/index.js';
+import { lengthAt, multi, numberAt } from './binding.js';
+import type { ManifestEntry } from './binding.js';
+import { typeAt } from './averages.js';
+import { gapAt, stateful } from './state.js';
+
+export const RANGE_ENTRIES: readonly ManifestEntry[] = [
+  stateful('keltner', 'len mult atrLen maType', (ctx, args) =>
+    multi(
+      ctx,
+      keltnerStep(
+        ctx.state,
+        '',
+        gapAt(ctx),
+        ctx.bar.close,
+        ctx.bar.volume,
+        lengthAt(ctx, 'keltner', 'len', args, 0),
+        numberAt(args, 1),
+        lengthAt(ctx, 'keltner', 'atrLen', args, 2),
+        typeAt(args, 3),
+      ),
+    ),
+  ),
+
+  stateful('chop', 'len', (ctx, args) =>
+    chopStep(ctx.state, '', gapAt(ctx), lengthAt(ctx, 'chop', 'len', args, 0)),
+  ),
+
+  stateful('hv', 'src len periodsPerYear', (ctx, args) =>
+    hvStep(
+      ctx.state,
+      '',
+      numberAt(args, 0),
+      lengthAt(ctx, 'hv', 'len', args, 1),
+      numberAt(args, 2),
+    ),
+  ),
+];