openalgo-script 0.5.0 → 0.6.0

package/src/core/check/call-sites.ts

@@ -21,7 +21,7 @@ import { bindArguments } from './arguments.js';
 import { remember, resolveLibraryCall, unresolved } from './calls.js';
 import type { Checker, Placement } from './checker.js';
 import type { CheckedCall, InputKind, RequestMode } from './checked.js';
-import { calleeNameOf, isCompileTimeConstant, isSourceName } from './constant.js';
+import { calleeNameOf, isCompileTimeConstant, isSourceName, readsInputInPart } from './constant.js';
 import { checkExpression } from './expressions.js';
 import { ensureChecked } from './functions.js';
 import { allowHandle, refuseHandle } from './handles.js';
@@ -59,7 +59,10 @@ export function resolveCall(checker: Checker, call: Call, placement: Placement):
     checker.report('OS2010', call.span, {
       name: checker.textOf(call.callee.span),
       type: typeText(UNKNOWN),
-      suggestion: checker.suggestionFor(checker.textOf(call.callee.span)),
+      suggestion: checker.callSuggestionFor(
+        checker.textOf(call.callee.span),
+        call.args.map((one) => checker.textOf(one.span)),
+      ),
     });
     return record(checker, call, unresolved(call, 'call'));
   }
@@ -220,8 +223,12 @@ function checkInput(checker: Checker, call: Call, checked: CheckedCall): Checked
   const options = argumentOf(checked, 'options');
   const title = literalOf(checked, 'title');
 
-  if (value !== undefined && !isSourceName(value.value) && !isCompileTimeConstant(checker, value.value)) {
-    checker.report('OS3003', value.span, { option: 'value' });
+  if (value !== undefined && !isSourceName(value.value)) {
+    if (!isCompileTimeConstant(checker, value.value)) {
+      checker.report('OS3003', value.span, { option: 'value' });
+    } else if (readsInputInPart(checker, value.value, false)) {
+      checker.report('OS3025', value.span, { option: 'value' });
+    }
   }
   if (kind !== undefined && PLANNED_KINDS.has(kind)) {
     checker.report('OS2001', call.span, {

package/src/core/check/calls.ts

@@ -19,7 +19,7 @@ import type { ParameterShape } from './arguments.js';
 import type { Checker, Placement } from './checker.js';
 import { reportStrategyOnly } from './checker.js';
 import type { CheckedCall } from './checked.js';
-import { isCompileTimeConstant } from './constant.js';
+import { isCompileTimeConstant, readsInputInPart } from './constant.js';
 import { refuseHandle } from './handles.js';
 import type { LibraryEntry } from './library.js';
 import { literalNumber, literalString } from './literals.js';
@@ -244,8 +244,14 @@ export function validateArguments(
       });
     }
 
-    if (entry.constant.includes(parameter.name) && !isCompileTimeConstant(checker, argument.value)) {
-      checker.report('OS3003', span, { option: parameter.name });
+    if (entry.constant.includes(parameter.name)) {
+      if (!isCompileTimeConstant(checker, argument.value)) {
+        checker.report('OS3003', span, { option: parameter.name });
+      } else if (readsInputInPart(checker, argument.value, entry.name !== 'input')) {
+        checker.report('OS3025', span, { option: parameter.name });
+      } else if (entry.written.includes(parameter.name) && readsInputInPart(checker, argument.value, false)) {
+        checker.report('OS3026', span, { option: parameter.name });
+      }
     }
   }
 
@@ -331,7 +337,10 @@ export function resolveLibraryCall(
     checker.report('OS2010', call.span, {
       name,
       type: held === undefined ? typeText(UNKNOWN) : typeText(held.returns),
-      suggestion: checker.suggestionFor(name),
+      suggestion: checker.callSuggestionFor(
+        name,
+        call.args.map((one) => checker.textOf(one.span)),
+      ),
     });
     return unresolved(call, name);
   }

package/src/core/check/check.ts

@@ -21,11 +21,12 @@ import type { SourceFile } from '../source/index.js';
 import { Checker, TOP_LEVEL, finaliseStorage } from './checker.js';
 import type { CheckedScript } from './checked.js';
 import { checkDeclaration, checkLimits, readHeader } from './declaration.js';
+import { reportDeletedStillHeld } from './deleted.js';
 import { checkFunctionDeclarations, checkRemainingFunctions } from './functions.js';
 import { reportRepeatedAlertIds } from './outputs.js';
 import { checkStatement } from './statements.js';
 import { reportUnplaceableTags } from './tags.js';
-import { elementOf } from './types.js';
+import { elementOf, isHandle } from './types.js';
 
 export function check(file: SourceFile, script: Script, sink: DiagnosticSink): CheckedScript {
   const checker = new Checker(file, script, sink);
@@ -54,6 +55,7 @@ export function check(file: SourceFile, script: Script, sink: DiagnosticSink): C
   finaliseStorage(checker);
   reportUnknownElementTypes(checker);
   reportNamesNeverRead(checker);
+  reportDeletedStillHeld(checker);
   reportRepeatedTitles(checker);
   reportInputKeys(checker);
   reportRepeatedAlertIds(checker);
@@ -78,12 +80,22 @@ function reportUnknownElementTypes(checker: Checker): void {
   }
 }
 
-/** OS8010 and OS8018: a name, or an input, that nothing in the file reads. */
+/**
+ * OS8010 and OS8018: a name, or an input, that nothing in the file reads.
+ *
+ * A name bound to a declaration handle is exempt, as the entry's cause says: a
+ * handle is a compile-time binding, the declaration draws whether or not it is
+ * named, and so nothing is left in the bar loop for the warning to be about.
+ * `language.md` 5.4 gives `plot`, `plotCandles`, `fill` and `level` the one kind
+ * of value, so the exemption is the type rather than a list of the two calls
+ * `stdlib.md` 14.2 happens to name.
+ */
 function reportNamesNeverRead(checker: Checker): void {
   for (const binding of checker.bindings) {
     if (binding.isRead) continue;
     if (binding.kind === 'library' || binding.kind === 'function') continue;
     if (binding.kind === 'parameter' || binding.kind === 'loop') continue;
+    if (isHandle(binding.type)) continue;
 
     if (binding.input !== undefined) {
       const input = checker.inputs[binding.input];

package/src/core/check/checker.ts

@@ -35,13 +35,14 @@ import type {
   Mutable,
   Storage,
 } from './checked.js';
+import { namesGivenAValue } from './assigned.js';
 import { conditionalCalls } from './conditional.js';
-import { libraryNames } from './surface.js';
+import { libraryFunctionNames, libraryNames } from './surface.js';
 import { closestName } from './suggest.js';
 import type { Type } from './types.js';
 import { UNKNOWN } from './types.js';
 import type { Warmup } from './warmup.js';
-import { BAR_ZERO } from './warmup.js';
+import { BAR_ZERO, weaken } from './warmup.js';
 
 /**
  * One nesting of names, `language.md` 12.1.
@@ -143,6 +144,13 @@ export class Checker {
 
   /** Every call site a bar can pass without evaluating, `language.md` 11.4. */
   private readonly conditional: ReadonlySet<Call>;
+  /**
+   * The names some line gives a value, read before a `var` is called never.
+   *
+   * Built the first time it is asked for, because it is one walk of the whole
+   * tree and almost every file never reads a `var` that is still never.
+   */
+  private givenAValue: ReadonlySet<string> | undefined = undefined;
 
   constructor(file: SourceFile, script: Script, sink: DiagnosticSink) {
     this.file = file;
@@ -300,6 +308,21 @@ export class Checker {
     return this.types.get(expression) ?? UNKNOWN;
   }
 
+  /**
+   * The warmup a read of this name sees, here.
+   *
+   * A `var` that is still never at this line but that a later line gives a
+   * value is not never: the later line wrote it on the bar before, or on an
+   * earlier pass of the same loop. The honest answer is a floor of bar 0,
+   * which claims nothing and withdraws the claim OS8009 is built on, where an
+   * exact bar would need the later line's warmup before it has been read.
+   */
+  warmupOfRead(binding: Binding): Warmup {
+    if (binding.warmup.kind !== 'never' || binding.persistence === 'none') return binding.warmup;
+    this.givenAValue ??= namesGivenAValue(this.script);
+    return this.givenAValue.has(binding.name) ? weaken(BAR_ZERO) : binding.warmup;
+  }
+
   warmupOf(expression: Expression): Warmup {
     return this.warmups.get(expression) ?? BAR_ZERO;
   }
@@ -318,6 +341,20 @@ export class Checker {
     return closestName(written, this.namesInScope());
   }
 
+  /**
+   * OS2010's suggestion: the closest function, called with what was written.
+   *
+   * The catalogue documents the slot as the library function whose name is
+   * closest, with its first argument filled in, so `volume(20)` is offered a
+   * function over `volume` and the arguments the reader already wrote,
+   * rather than a name that cannot be called either.
+   */
+  callSuggestionFor(written: string, args: readonly string[]): string {
+    const inStrategy = this.declaration?.form === 'strategy';
+    const name = closestName(written, libraryFunctionNames(inStrategy));
+    return `${name}(${[written, ...args].join(', ')})`;
+  }
+
   /** A state region for one call site, `compiled-program.md` 2.11. */
   takeStateId(): number {
     const id = this.stateCount;

package/src/core/check/constant.ts

@@ -92,6 +92,63 @@ export function isCompileTimeConstant(checker: Checker, expression: Expression):
   }
 }
 
+/**
+ * Whether a constant reads a setting as part of something larger, OS3025.
+ *
+ * `compiled-program.md` 2.3 gives a field fixed before bar 0 two forms: the
+ * effective value, which the compiler folds, and `{ "input": "<key>" }`, one
+ * setting resolved at load. `precision = input(2, "Decimals") + 1` and
+ * `opacity = shade ? 1 : 0` are neither: the compiler cannot fold them, because
+ * the setting's value is not known until the host resolves it, and the program
+ * has no form for an expression evaluated at load. Nothing refused them, so the
+ * emitter met them with no way to write them and reported a defect in itself.
+ *
+ * `wholeOnly` is false for an input's own options: a default, a bound or a
+ * step is what the settings dialog shows before anybody has chosen, and a
+ * setting that took its default from another setting would have none to show.
+ */
+export function readsInputInPart(
+  checker: Checker,
+  expression: Expression,
+  wholeOnly: boolean,
+): boolean {
+  if (!readsInput(checker, expression)) return false;
+  return !wholeOnly || !isWholeInput(checker, expression);
+}
+
+/** Whether a setting is read anywhere inside the expression. */
+function readsInput(checker: Checker, expression: Expression): boolean {
+  if (isWholeInput(checker, expression)) return true;
+  const inner = withoutGrouping(expression);
+  switch (inner.kind) {
+    case 'arrayLiteral':
+      return inner.elements.some((element) => readsInput(checker, element));
+    case 'unary':
+      return readsInput(checker, inner.operand);
+    case 'binary':
+      return readsInput(checker, inner.left) || readsInput(checker, inner.right);
+    case 'ternary':
+      return (
+        readsInput(checker, inner.condition) ||
+        readsInput(checker, inner.whenTrue) ||
+        readsInput(checker, inner.whenFalse)
+      );
+    case 'call':
+      return inner.args.some((argument) => readsInput(checker, argument.value));
+    default:
+      return false;
+  }
+}
+
+/** One setting and nothing else: an `input()` call, or a name that holds one. */
+function isWholeInput(checker: Checker, expression: Expression): boolean {
+  const inner = withoutGrouping(expression);
+  if (inner.kind === 'call') return calleeName(inner.callee) === 'input';
+  if (inner.kind !== 'nameReference') return false;
+  const binding = checker.lookup(inner.name);
+  return binding !== undefined && inputHeldBy(binding) !== undefined;
+}
+
 /**
  * Whether the expression names one of the price series an `input` may default
  * to, `stdlib.md` 13.1.

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-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

@@ -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`"},

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/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;
+  }
+}