openalgo-script 0.4.0 → 0.6.0

package/src/core/check/deleted.ts

@@ -0,0 +1,135 @@
+/**
+ * OS8019: a name, or an array, still holding an object the script deleted.
+ *
+ * `language.md` 5.4: deleting an object touches neither the name nor the array
+ * element that refers to it, so what is left is stale rather than absent, and
+ * the next setter that reaches it stops the bar with OS4005, usually many bars
+ * after the line that caused it. The warning is about the line that caused it.
+ *
+ * The rule is read on one path, which is the block the delete is written in.
+ * A `draw.delete(name)` is cleared by a later statement of the same block that
+ * assigns the name again, `none` or a new object alike. A
+ * `draw.delete(element(arr, i))`, or `arr[i]`, is cleared by a later statement
+ * of the same block that takes an element out of the array or empties it. Only
+ * a name that outlives the bar is followed: a plain name is recomputed on the
+ * next bar, and a stale value in it cannot reach one.
+ *
+ * What this does not see, and does not claim to: a clearing line in a nested
+ * block, which may not run, and a deletion reached through a function's
+ * parameter, where the name the caller holds is not in view.
+ */
+import type { AstNode, Block, Call, Expression, Script } from '../ast/index.js';
+import { childrenOf, withoutGrouping } from '../ast/index.js';
+import type { Binding } from './checked.js';
+import type { Checker } from './checker.js';
+import { elementOf } from './types.js';
+
+/** The calls that take an element out of an array or empty it, `language.md` 14.1. */
+const REMOVING = new Set(['shift', 'pop', 'remove', 'clear']);
+
+interface Held {
+  readonly binding: Binding;
+  /** Whether the object sits in an element of the array the binding names. */
+  readonly inArray: boolean;
+}
+
+export function reportDeletedStillHeld(checker: Checker): void {
+  // One walk of the whole tree, paid only by a file that deletes something.
+  if (!checker.calls.some((one) => one.name === 'draw.delete')) return;
+  visit(checker, checker.script);
+}
+
+function visit(checker: Checker, node: AstNode): void {
+  if (node.kind === 'script' || node.kind === 'block') {
+    reportList(checker, statementsOf(node));
+  }
+  for (const child of childrenOf(node)) visit(checker, child);
+}
+
+function statementsOf(node: Script | Block): readonly AstNode[] {
+  return node.kind === 'script' ? node.items : node.statements;
+}
+
+function reportList(checker: Checker, statements: readonly AstNode[]): void {
+  statements.forEach((statement, index) => {
+    const call = deleteCall(checker, statement);
+    if (call === undefined) return;
+    const argument = call.args[0]?.value;
+    if (argument === undefined) return;
+    const held = heldBy(checker, argument);
+    if (held === undefined) return;
+    const kind = objectKindOf(checker, argument);
+    if (kind === undefined) return;
+    const later = statements.slice(index + 1);
+    const cleared = held.inArray
+      ? later.some((one) => removesFrom(checker, one, held.binding))
+      : later.some((one) => assigns(one, held.binding.name));
+    if (cleared) return;
+    checker.report('OS8019', argument.span, {
+      name: held.binding.name,
+      kind,
+      line: call.span.line,
+    });
+  });
+}
+
+/** The `draw.delete(...)` a statement is, when it is one. */
+function deleteCall(checker: Checker, statement: AstNode): Call | undefined {
+  if (statement.kind !== 'expressionStatement') return undefined;
+  const expression = withoutGrouping(statement.expression);
+  if (expression.kind !== 'call') return undefined;
+  return checker.callSites.get(expression)?.name === 'draw.delete' ? expression : undefined;
+}
+
+/** The persistent name the deleted object is still reachable through. */
+function heldBy(checker: Checker, argument: Expression): Held | undefined {
+  const written = withoutGrouping(argument);
+  if (written.kind === 'nameReference') {
+    const binding = persistent(checker, written);
+    return binding === undefined ? undefined : { binding, inArray: false };
+  }
+  const array = arrayOf(checker, written);
+  if (array === undefined) return undefined;
+  const binding = persistent(checker, array);
+  return binding === undefined ? undefined : { binding, inArray: true };
+}
+
+/** `element(arr, i)` or `arr[i]`, as the array expression it reads. */
+function arrayOf(checker: Checker, written: Expression): Expression | undefined {
+  if (written.kind === 'index') return withoutGrouping(written.target);
+  if (written.kind === 'call' && checker.callSites.get(written)?.name === 'element') {
+    const first = written.args[0]?.value;
+    return first === undefined ? undefined : withoutGrouping(first);
+  }
+  return undefined;
+}
+
+function persistent(checker: Checker, expression: Expression): Binding | undefined {
+  if (expression.kind !== 'nameReference') return undefined;
+  const binding = checker.references.get(expression);
+  return binding !== undefined && binding.persistence !== 'none' ? binding : undefined;
+}
+
+function objectKindOf(checker: Checker, argument: Expression): string | undefined {
+  const type = checker.types.get(argument);
+  if (type === undefined) return undefined;
+  const element = elementOf(type);
+  return element.kind === 'object' ? element.object : undefined;
+}
+
+function assigns(statement: AstNode, name: string): boolean {
+  return statement.kind === 'assignment' && statement.target.text === name;
+}
+
+/** Whether any call in the statement takes an element out of this array. */
+function removesFrom(checker: Checker, node: AstNode, binding: Binding): boolean {
+  if (node.kind === 'call') {
+    const name = checker.callSites.get(node)?.name;
+    const first = node.args[0]?.value;
+    if (name !== undefined && REMOVING.has(name) && first !== undefined) {
+      const target = withoutGrouping(first);
+      if (target.kind === 'nameReference' && checker.references.get(target) === binding) return true;
+    }
+  }
+  return childrenOf(node).some((child) => removesFrom(checker, child, binding));
+}

package/src/core/check/expressions.ts

@@ -203,7 +203,7 @@ function checkNameReference(checker: Checker, expression: NameReference): Type {
     }
     binding.isRead = true;
     checker.references.set(expression, binding);
-    return checker.record(expression, binding.type, binding.warmup);
+    return checker.record(expression, binding.type, checker.warmupOfRead(binding));
   }
 
   const entries = libraryEntries(expression.name);

package/src/core/check/library-orders.ts

@@ -240,7 +240,7 @@ const legs: readonly LibraryEntry[] = [
   }),
   entry('leg.stop(name: string, price: number) -> nothing', { ...strategyOnly, planned: true }),
   entry('leg.target(name: string, price: number) -> nothing', { ...strategyOnly, planned: true }),
-  entry('leg.trail(name: string, distance: number, arm?: number = none) -> nothing', {
+  entry('leg.trail(name: string, distance: number, activateAt?: number = none) -> nothing', {
     ...strategyOnly,
     planned: true,
   }),
@@ -258,7 +258,7 @@ const book: readonly LibraryEntry[] = [
   entry('book.stop(amount: number) -> nothing', { ...strategyOnly, planned: true }),
   entry('book.target(amount: number) -> nothing', { ...strategyOnly, planned: true }),
   entry(
-    'book.lockProfit(arm: number, lock: number, step?: number = none, advance?: number = none) -> nothing',
+    'book.lockProfit(activateAt: number, lock: number, step?: number = none, advance?: number = none) -> nothing',
     { ...strategyOnly, planned: true },
   ),
   entry('book.trailStopsToEntry(at: number) -> nothing', { ...strategyOnly, planned: true }),

package/src/core/check/library-output.ts

@@ -77,6 +77,7 @@ const declarations: readonly LibraryEntry[] = [
       topLevel: true,
       values: { style: PLOT_STYLES, format: FORMATS, scale: SCALES },
       constant: ['title', 'width', 'style', 'offset', 'overlay', 'precision', 'format', 'scale'],
+      written: ['style'],
       whole: { precision: wholeRange(0, 10), offset: wholeRange() },
     },
   ),

package/src/core/check/library-prose.generated.ts

@@ -49,7 +49,7 @@ export const LIBRARY_PROSE: Readonly<Record<string, LibraryProse>> = {
   "book.exit": {"summary":"Exit the whole book as a unit"},
   "book.exitAt": {"summary":"Square off every leg at this `\"HHMM\"` in the chart's timezone"},
   "book.isOpen": {"summary":"Whether any leg holds a position","warmup":"bar 0"},
-  "book.lockProfit": {"summary":"Arm a floor at a profit, then advance it as profit grows"},
+  "book.lockProfit": {"summary":"Activate a floor at a profit, then advance it as profit grows"},
   "book.profit": {"summary":"The book's profit in money, open and realised since it was last flat","warmup":"bar 0"},
   "book.squareOffAtExpiry": {"summary":"Square off a leg this many minutes before its contract expires"},
   "book.stop": {"summary":"Square off every leg when the book's profit falls to `-amount`"},
@@ -118,24 +118,24 @@ export const LIBRARY_PROSE: Readonly<Record<string, LibraryProse>> = {
   "dpo": {"summary":"Price with its displaced mean removed, to expose a cycle","warmup":"bar `len + floor(len / 2)`"},
   "draw.box": {"summary":"A zone: supply, demand, an opening range"},
   "draw.count": {"summary":"How many objects this script currently holds"},
-  "draw.delete": {"summary":"box"},
+  "draw.delete": {"summary":"Remove one object"},
   "draw.deleteAll": {"summary":"Remove every object this script created"},
   "draw.label": {"summary":"A plate of text at a point"},
   "draw.line": {"summary":"A trendline between two points"},
   "draw.polyline": {"summary":"A path or a closed shape through many points"},
   "draw.setAt": {"summary":"Move a label"},
-  "draw.setBounds": {"summary":"nothing"},
-  "draw.setColor": {"summary":"box"},
+  "draw.setBounds": {"summary":"Move both anchors in one call"},
+  "draw.setColor": {"summary":"Change the line or border colour"},
   "draw.setExtend": {"summary":"Continue a line to the pane edge"},
-  "draw.setFillColor": {"summary":"nothing"},
-  "draw.setFrom": {"summary":"nothing"},
+  "draw.setFillColor": {"summary":"Change a box's or polyline's fill"},
+  "draw.setFrom": {"summary":"Move a line's or box's first anchor"},
   "draw.setPoints": {"summary":"Replace a polyline's path"},
   "draw.setStyle": {"summary":"`\"solid\"`, `\"dashed\"` or `\"dotted\"`"},
-  "draw.setText": {"summary":"nothing"},
-  "draw.setTextColor": {"summary":"nothing"},
-  "draw.setTo": {"summary":"nothing"},
-  "draw.setTooltip": {"summary":"nothing"},
-  "draw.setWidth": {"summary":"polyline, width)`"},
+  "draw.setText": {"summary":"Change a label's or box's caption"},
+  "draw.setTextColor": {"summary":"Change the text colour"},
+  "draw.setTo": {"summary":"Move its second anchor"},
+  "draw.setTooltip": {"summary":"Detail shown while the pointer rests on the object"},
+  "draw.setWidth": {"summary":"Change the line thickness"},
   "element": {"summary":"Read element `i`"},
   "ema": {"summary":"Exponential mean, weight `2 / (len + 1)`, seeded on bar `len - 1` with the simple average of those `len` values","warmup":"bar `len - 1`"},
   "eom": {"summary":"How far price moved per unit of volume","warmup":"bar `len`"},
@@ -332,7 +332,7 @@ export const LIBRARY_PROSE: Readonly<Record<string, LibraryProse>> = {
   "str.split": {"summary":"Split into parts"},
   "str.startsWith": {"summary":"Prefix test"},
   "str.substring": {"summary":"`from` inclusive, `to` exclusive, to the end when `to` is absent"},
-  "str.trim": {"summary":"Leading and trailing spaces removed"},
+  "str.trim": {"summary":"Leading and trailing whitespace removed: the code points listed below"},
   "str.upper": {"summary":"Upper case, invariant, not locale dependent"},
   "sum": {"summary":"Total over the window","warmup":"bar `len - 1`"},
   "sumSkip": {"summary":"Total over the window, ignoring absent bars","warmup":"bar `len - 1`"},

package/src/core/check/library.ts

@@ -156,6 +156,12 @@ export interface LibraryEntry {
   readonly whole: Readonly<Record<string, WholeRange>>;
   /** Arguments read once before bar 0, so a bar-dependent one is OS3003. */
   readonly constant: readonly string[];
+  /**
+   * Arguments the compiled format carries as a plain value, with no input
+   * reference beside it, so a setting written into one is OS3026 rather than
+   * folded to its default with nothing said.
+   */
+  readonly written: readonly string[];
   /** Pairs that set the same thing two ways, so giving both is OS3010. */
   readonly conflicts: readonly (readonly [string, string])[];
 }
@@ -171,6 +177,7 @@ export interface EntryOptions {
   readonly undeclared?: readonly string[];
   readonly whole?: Readonly<Record<string, WholeRange>>;
   readonly constant?: readonly string[];
+  readonly written?: readonly string[];
   readonly conflicts?: readonly (readonly [string, string])[];
 }
 
@@ -327,6 +334,7 @@ export function entry(signature: string, options: EntryOptions = {}): LibraryEnt
     undeclared: options.undeclared ?? [],
     whole: options.whole ?? {},
     constant: options.constant ?? [],
+    written: options.written ?? [],
     conflicts: options.conflicts ?? [],
   };
 }

package/src/core/check/surface.ts

@@ -73,6 +73,22 @@ export function libraryNames(): readonly string[] {
   return [...INDEX.keys()];
 }
 
+/**
+ * Every name the library lets a script call, for OS2010's suggestion.
+ *
+ * OS2010 is a call to something that is not a function, so the name it offers
+ * has to be one that is: offering `blue` for `volume(20)` would hand the reader
+ * a second OS2010. A planned name is left out too, because calling it is OS2020,
+ * and so is an order function outside a strategy, because calling it is OS7001.
+ */
+export function libraryFunctionNames(inStrategy: boolean): readonly string[] {
+  return [...INDEX.entries()]
+    .filter(([, entries]) =>
+      entries.some((one) => one.callable && !one.planned && (inStrategy || !one.strategyOnly)),
+    )
+    .map(([name]) => name);
+}
+
 /** The members of one namespace, spelled bare, for OS2009's suggestion. */
 export function membersOf(namespace: string): readonly string[] {
   const prefix = `${namespace}.`;

package/src/core/emit/canonical.ts

@@ -1,5 +1,5 @@
 /**
- * The canonical encoding, `compiled-program.md` 2.14.
+ * The canonical encoding, `compiled-program.md` 2.14, and the one number writer.
  *
  * It exists so that a hash of a program means something: two compilers, in two
  * languages, handed the same source, produce the same bytes. So none of the
@@ -9,8 +9,8 @@
  * - Object keys sorted ascending by Unicode code point. Sorted rather than in
  *   the specification's listed order, because a sort is a rule an emitter in any
  *   language can follow without a table.
- * - A number is the shortest decimal string that reads back as the same
- *   binary64 value, with an exponent written as `e` and an optional `-`.
+ * - A number is written by the rule of `language.md` 5.5, which is the same
+ *   rule for every number that becomes text anywhere in the language.
  * - A string escapes only the quote, the backslash and the code points below
  *   0x20, the last as `\u00XX` except for `\n`, `\r` and `\t`.
  */
@@ -18,16 +18,74 @@ import type { CompiledProgram } from './program.js';
 import { sha256 } from './sha256.js';
 
 /**
- * A number, shortest round trip.
+ * A number as text: the one writer.
  *
- * The host's own shortest form is already the shortest that reads back
- * identically. What it is not is the spelling the specification asks for: a
- * positive exponent is written with a `+` that the format does not allow, so
- * that one sign is removed and nothing else is touched.
+ * Two engines compare numbers as bits, but they compare text in a case file, an
+ * expected column, a table cell and `text(x)`, so how a number becomes text has
+ * to be one rule that both implement, and in this repository it has to be one
+ * function. This is that function. `scripts/check-number-writer.mjs` reads
+ * every file under `src` and refuses a conversion outside this module, so a
+ * number cannot reach text by a host's default somewhere else and disagree with
+ * this one by a plus sign.
+ *
+ * **The digits are the host's and the layout is not.** The shortest decimal
+ * digit string that reads back as the same binary64 is what every host this
+ * engine runs on produces, and what a second engine's host produces too; that
+ * part is taken from the host's own shortest form. Where the two hosts part
+ * company is the layout, when a value is written positionally and when with an
+ * exponent, and how the exponent is spelled, so that half is written here from
+ * the rule in `language.md` 5.5 and not left to the host. The rule is the one
+ * the first host follows natively, minus the `+` it writes on a positive
+ * exponent, and `spec/vectors/number-text.json` holds the boundary cases a
+ * second engine checks itself against.
  */
 export function canonicalNumber(value: number): string {
   if (!Number.isFinite(value)) throw new Error('a compiled program holds finite numbers only');
-  return String(value === 0 ? 0 : value).replace('e+', 'e');
+  // Zero and negative zero are one value to the language (compiled-program.md
+  // 3.1) and one spelling here.
+  if (value === 0) return '0';
+  const { digits, point } = shortestDigits(Math.abs(value));
+  return (value < 0 ? '-' : '') + layout(digits, point);
+}
+
+/**
+ * The shortest round trip digits of a positive finite magnitude, and where the
+ * decimal point falls: the value is `0.d1d2...dk` times ten to the `point`.
+ *
+ * Read out of the host's own shortest form rather than computed here, because
+ * the search for the shortest digit string is the one part of the conversion
+ * every host already agrees on. Whatever layout the host chose is undone: the
+ * digits and the point are all that is kept.
+ */
+function shortestDigits(magnitude: number): { readonly digits: string; readonly point: number } {
+  const shown = String(magnitude);
+  const e = shown.indexOf('e');
+  const mantissa = e < 0 ? shown : shown.slice(0, e);
+  const exponent = e < 0 ? 0 : Number(shown.slice(e + 1));
+  const dot = mantissa.indexOf('.');
+  const whole = dot < 0 ? mantissa : mantissa.slice(0, dot);
+  const fraction = dot < 0 ? '' : mantissa.slice(dot + 1);
+  let digits = whole + fraction;
+  let point = whole.length + exponent;
+  // A positional form below one carries leading zeros that are not digits of
+  // the value, and a whole number carries trailing zeros that are its layout.
+  while (digits.startsWith('0')) {
+    digits = digits.slice(1);
+    point -= 1;
+  }
+  while (digits.endsWith('0')) digits = digits.slice(0, -1);
+  return { digits, point };
+}
+
+/** `language.md` 5.5: positional between the two thresholds, an exponent outside them. */
+function layout(digits: string, point: number): string {
+  const count = digits.length;
+  if (count <= point && point <= 21) return digits + '0'.repeat(point - count);
+  if (0 < point && point <= 21) return `${digits.slice(0, point)}.${digits.slice(point)}`;
+  if (-6 < point && point <= 0) return `0.${'0'.repeat(-point)}${digits}`;
+  const exponent = point - 1;
+  const lead = count === 1 ? digits : `${digits[0]}.${digits.slice(1)}`;
+  return `${lead}e${exponent < 0 ? '-' : ''}${String(Math.abs(exponent))}`;
 }
 
 export function canonicalString(value: string): string {

package/src/core/engine/arithmetic.ts

@@ -23,6 +23,7 @@
  * what a script wants when it wraps an index. Collapsing them would silently
  * change one of the two.
  */
+import { compareStrings } from './library/index.js';
 import type { Value } from './values/index.js';
 import { ABSENT, numberValue, valuesEqual } from './values/index.js';
 
@@ -99,12 +100,17 @@ function numeric(
  * absence is treated two ways, and it is deliberate: an operator that can
  * itself be absent gives a script no way to ask whether a value is absent at
  * all, so equality is the exception and every other comparison is not.
+ *
+ * **Two strings are ordered by code point** (`language.md` 9.3, `stdlib.md`
+ * section 10), through the one order `sort` uses, and not by the host's own
+ * operator, which orders by sixteen bit unit and puts a symbol outside the
+ * basic plane below the last thousands of the plane. Numbers take the host's
+ * operator, which is the binary64 order every engine shares.
  */
 export function compare(opcode: 'LT' | 'LE' | 'GT' | 'GE', a: Value, b: Value): Value {
   if (a === null || b === null) return ABSENT;
-  const bothNumbers = typeof a === 'number' && typeof b === 'number';
-  const bothStrings = typeof a === 'string' && typeof b === 'string';
-  if (!bothNumbers && !bothStrings) throw new OperandMismatch(opcode);
+  if (typeof a === 'string' && typeof b === 'string') return ordered(opcode, compareStrings(a, b));
+  if (typeof a !== 'number' || typeof b !== 'number') throw new OperandMismatch(opcode);
   switch (opcode) {
     case 'LT':
       return a < b;
@@ -117,6 +123,20 @@ export function compare(opcode: 'LT' | 'LE' | 'GT' | 'GE', a: Value, b: Value):
   }
 }
 
+/** An ordering comparison read off a three way order: negative, zero or positive. */
+function ordered(opcode: 'LT' | 'LE' | 'GT' | 'GE', order: number): boolean {
+  switch (opcode) {
+    case 'LT':
+      return order < 0;
+    case 'LE':
+      return order <= 0;
+    case 'GT':
+      return order > 0;
+    default:
+      return order >= 0;
+  }
+}
+
 /** `EQ` and `NE` are total: they always produce a boolean. */
 export function equals(a: Value, b: Value): boolean {
   return valuesEqual(a, b);

package/src/core/engine/bar-source.ts

@@ -0,0 +1,113 @@
+/**
+ * Where the bars a run reads come from: an array of records, or columns.
+ *
+ * The bar cycle reads one bar at a time and does not care where its fields come
+ * from, so the representation is decided at the door and nowhere else. Two are
+ * accepted (issue 0005):
+ *
+ * - **Records**, one `HostBar` per bar, which is the live path: one bar arrives
+ *   at a time and an array of one is absurd.
+ * - **Columns**, one array per field, owned by the host. A long history held as
+ *   columns costs about a third of the memory of one object per bar and no
+ *   allocation per bar at rest, and a store that already holds bars as columns
+ *   can hand over typed array views with no parse at all. The engine reads
+ *   `open[i]` when bar `i` executes and builds the one record that execution
+ *   needs, which is gone by the next bar.
+ *
+ * **In a column, absence is `null` or `NaN`.** A typed array cannot hold `null`,
+ * and a price the host does not have is absent, never zero (`host-interface.md`
+ * 3.1), so `NaN` is the typed array's spelling of it. A time that is `NaN` is a
+ * bar with no time, which the hand-over refuses with OS6025 exactly as it
+ * refuses a record with none.
+ *
+ * **The number of bars is the length of `time`.** A shorter price, volume or
+ * interest column reads as absent past its end, which is the same thing a hole in
+ * a record is, and nothing is invented to fill it.
+ */
+import type { HostBar } from './bars.js';
+
+/** Numbers by bar index, absent written as `null` or `NaN`. */
+export type BarColumn = ArrayLike<number | null>;
+
+/** A history as columns, one per field of `host-interface.md` 3.1. */
+export interface BarColumns {
+  readonly time: BarColumn;
+  readonly open: BarColumn;
+  readonly high: BarColumn;
+  readonly low: BarColumn;
+  readonly close: BarColumn;
+  readonly volume?: BarColumn;
+  readonly oi?: BarColumn;
+}
+
+/** What the bar cycle and the fold read: how many bars, and bar `i`. */
+export interface BarSource {
+  readonly length: number;
+  at(index: number): HostBar | undefined;
+}
+
+export function isColumns(bars: readonly HostBar[] | BarColumns): bars is BarColumns {
+  return !Array.isArray(bars);
+}
+
+/** Either form, as the bar cycle and the fold read it. */
+export function sourceOf(bars: readonly HostBar[] | BarColumns): BarSource {
+  return isColumns(bars) ? columnSource(bars) : recordSource(bars);
+}
+
+export function recordSource(bars: readonly HostBar[]): BarSource {
+  return { get length() { return bars.length; }, at: (index) => bars[index] };
+}
+
+function cell(column: BarColumn | undefined, index: number): number | null {
+  const value = column === undefined || index >= column.length ? null : column[index];
+  return value === null || value === undefined || Number.isNaN(value) ? null : value;
+}
+
+export function columnSource(columns: BarColumns): BarSource {
+  const length = columns.time.length;
+  return {
+    length,
+    at(index: number): HostBar | undefined {
+      if (index < 0 || index >= length) return undefined;
+      return {
+        time: cell(columns.time, index),
+        open: cell(columns.open, index),
+        high: cell(columns.high, index),
+        low: cell(columns.low, index),
+        close: cell(columns.close, index),
+        volume: cell(columns.volume, index),
+        oi: cell(columns.oi, index),
+      };
+    },
+  };
+}
+
+/**
+ * The bars a run has been handed: a whole history, then whatever arrives live.
+ *
+ * `run` replaces the history; `append` and `update` write one bar over it. A
+ * bar written live is held as the record it arrived as, which is the only form
+ * a live bar has.
+ */
+export class KnownBars implements BarSource {
+  private base: BarSource = recordSource([]);
+  private readonly live: HostBar[] = [];
+
+  get length(): number {
+    return Math.max(this.base.length, this.live.length);
+  }
+
+  at(index: number): HostBar | undefined {
+    return this.live[index] ?? this.base.at(index);
+  }
+
+  set(index: number, bar: HostBar): void {
+    this.live[index] = bar;
+  }
+
+  reset(base: BarSource): void {
+    this.base = base;
+    this.live.length = 0;
+  }
+}