openalgo-script 0.2.0 → 0.5.0

package/src/core/backtest/record.ts

@@ -0,0 +1,470 @@
+/**
+ * The run record: a whole run as a plain JSON document.
+ *
+ * **The record is the conformance case.** That is the one decision this module
+ * exists to hold, and everything in it follows from it: no object reference, no
+ * function, no dependence on this implementation's internals, and nothing that
+ * only this engine can read. A record carries the script revision, the compiled
+ * program, the bars, the settings the host chose, the frames the destination
+ * answered in delivery order, the fills the engine folded in fold order, the
+ * ledger the run ended with, the diagnostics and the report.
+ *
+ * **The bars are inline or referenced, and both carry the same hash.** Inline is
+ * the conformance form, because a case has to hold every byte of its own input.
+ * Referenced is the operational form, because the smallest deployment has a one
+ * megabyte request body and nothing that grows with history may travel in one.
+ * A replay whose bars do not hash to the record's hash is OS6022 rather than a
+ * silently different study.
+ *
+ * **The frames name an intent by ordinal and never by an engine's own id**,
+ * because a case cannot know what id another engine minted. The same reason the
+ * ledger rows here are flat words rather than this engine's own types.
+ *
+ * The record is written through the existing canonical encoding, so there is one
+ * canonical writer in the repository and key order and number form are fixed for
+ * everybody.
+ */
+import type { RecordedFill, Report } from '../accounting/index.js';
+import type { Diagnostic } from '../diagnostics/index.js';
+import { canonicalNumber, canonicalise, programHash, sha256, sourceHash } from '../emit/index.js';
+import type { CompiledProgram, SourceStamp } from '../emit/index.js';
+import type { Instrument, LedgerRow } from '../engine/index.js';
+import { VERSION } from '../version/index.js';
+import type { BacktestSettings } from './settings.js';
+
+/** One bar as a record holds it. */
+export interface RecordedBar {
+  readonly time: number | null;
+  readonly open: number | null;
+  readonly high: number | null;
+  readonly low: number | null;
+  readonly close: number | null;
+  readonly volume: number | null;
+  readonly oi: number | null;
+}
+
+/**
+ * The bars, held or pointed at.
+ *
+ * Both forms carry the same hash, computed the same way over the canonical
+ * tuple of each bar, so a referenced record can be turned into an inline one by
+ * whoever holds the bars and the result is the same case.
+ */
+export type BarsInRecord =
+  | {
+      readonly form: 'inline';
+      readonly hash: string;
+      readonly count: number;
+      readonly rows: readonly RecordedBar[];
+    }
+  | {
+      readonly form: 'referenced';
+      readonly hash: string;
+      readonly count: number;
+      readonly firstTime: number | null;
+      readonly lastTime: number | null;
+    };
+
+/** The columns of `conformance.md`'s frames.csv, in its order and with its names. */
+export interface RecordedFrame {
+  readonly afterBar: number;
+  /** An ordinal, 1-based, never an engine's own id. */
+  readonly intent: number;
+  readonly status: string;
+  readonly filledQty: number;
+  readonly avgFillPrice: number | null;
+  readonly orderRef: string | null;
+  readonly text: string | null;
+  /**
+   * The destination's own instant for this frame, or null where it stated none.
+   *
+   * **One field of the ledger is folded from it.** `host-interface.md` 7.2
+   * gives a frame a `time` and `stdlib.md` 17.7 moves `updatedAt` to it, so a
+   * record that dropped it wrote a ledger no engine reading the case back could
+   * fold to: handed frames with no instant, that engine leaves every
+   * `updatedAt` at `placedAt`, and the two disagree on exactly the rows whose
+   * destination answered later than the bar that placed the order.
+   *
+   * Absent rather than substituted, because 7.2 lets a destination state none
+   * and a row whose frame stated none keeps the instant it had.
+   */
+  readonly time: number | null;
+}
+
+/** A ledger row of `stdlib.md` 17.7, flattened: the `orders` channel of expected.json. */
+export interface RecordedOrder {
+  readonly intent: number;
+  readonly orderRef: string;
+  readonly tag: string;
+  readonly leg: string;
+  readonly positionRef: number;
+  readonly symbol: string | null;
+  readonly exchange: string | null;
+  readonly product: string;
+  readonly side: string;
+  readonly qty: number | null;
+  readonly qtyType: string;
+  readonly type: string | null;
+  readonly price: number | null;
+  readonly trigger: number | null;
+  readonly status: string;
+  readonly filledQty: number;
+  readonly avgFillPrice: number | null;
+  readonly rejection: string | null;
+  readonly placedAt: number | null;
+  readonly updatedAt: number | null;
+  readonly units: number | null;
+}
+
+/** A diagnostic as a record holds it: the code, the span and the bar. */
+export interface RecordedDiagnostic {
+  readonly code: string;
+  readonly line: number;
+  readonly column: number;
+  readonly severity: string;
+  readonly barIndex: number | null;
+}
+
+/** One run, whole, and readable by an engine that is not this one. */
+export interface RunRecord {
+  readonly recordVersion: number;
+  readonly engine: { readonly name: string; readonly version: string };
+  readonly languageVersion: string;
+  /** Already plain data. */
+  readonly program: CompiledProgram;
+  readonly programHash: string;
+  /** Hash, lines, file: the script revision. */
+  readonly source: SourceStamp;
+  /**
+   * The source text itself, or null on a record written before version 2.
+   *
+   * **A record is the conformance case, and a case has to hold `script.os`.**
+   * `source` above identifies the script and cannot reproduce it: a hash is a
+   * fingerprint, so it settles whether two files are the same and yields
+   * neither of them. Without the text a stored record could be replayed months
+   * later and still not be handed to anybody else to run, which is the whole
+   * claim the suite exists to test.
+   *
+   * It lives here and not on the compiled program on purpose. A program is
+   * executable data that no engine needs the source to run, and it is the
+   * versioned artefact adopters depend on; putting the text there would send a
+   * script everywhere its program travels and widen the format every engine
+   * has to read. The record is the thing that wants to be self-contained.
+   */
+  readonly sourceText: string | null;
+  readonly settings: BacktestSettings;
+  /**
+   * The instrument record of `host-interface.md` 4.1, as the engine was handed
+   * it, or null on a record written before version 3.
+   *
+   * **A case holds `instrument.json`, and `conformance.md` section 2 says that
+   * file is this record.** The contract in `settings` is the money layer's
+   * snapshot of the same instrument and holds six of the twelve facts; the
+   * ones a script reads and the money never does, the interval, the timezone,
+   * the session and the volume flag, were handed to the engine and written
+   * down nowhere. A case harvested from such a record either omitted a fact
+   * the page requires or stated one the run never had, and either way the
+   * second engine ran a different study than the one the expected output
+   * came from.
+   *
+   * It is the whole record and not the six facts beside the contract, because
+   * what is recorded is what the engine read at load, verbatim, and a reader
+   * should not have to compose it.
+   */
+  readonly instrument: Instrument | null;
+  readonly bars: BarsInRecord;
+  /** What the destination answered, in delivery order. */
+  readonly frames: readonly RecordedFrame[];
+  /** What the engine folded, in fold order. */
+  readonly fills: readonly RecordedFill[];
+  /** The ledger at the end, oldest first. */
+  readonly orders: readonly RecordedOrder[];
+  readonly diagnostics: readonly RecordedDiagnostic[];
+  readonly report: Report;
+}
+
+/**
+ * The revision of this document's own shape.
+ *
+ * A reader is handed a record and has to know what it is looking at before it
+ * reads a field, so the number is first in the document and is written by this
+ * file alone. It moves when a channel is added or a meaning changes, never when
+ * a figure in a report does.
+ */
+export const RECORD_VERSION = 4;
+
+/**
+ * The revision each later channel arrived in.
+ *
+ * A record written before a channel existed reads with that channel absent,
+ * and this table is what `recordFromJson` reads it from: one row per channel
+ * added since version 1, so the rule for an old record is stated once and
+ * grows by a line when the next channel does.
+ *
+ * `frameTime` is a field of a row rather than a channel of the document, and it
+ * is a row here for the same reason the other two are: what a reader has to
+ * know is which revision it arrived in. Where the absence is written differs,
+ * and that is the reader's business below, not this table's.
+ */
+const ADDED_IN = { sourceText: 2, instrument: 3, frameTime: 4 } as const;
+
+/** What this engine calls itself in a record it wrote. */
+const ENGINE_NAME = 'openscript';
+
+/** The parts a run hands over, each already in the shape the record holds. */
+export interface RecordParts {
+  readonly program: CompiledProgram;
+  /**
+   * The script's own text, so the record can become a conformance case.
+   *
+   * Optional because a caller that has only a compiled program cannot invent
+   * it, and a run is still worth recording without it. `caseFilesFrom` is the
+   * one thing that then cannot be served, and it says so rather than writing a
+   * case with a hole in it.
+   */
+  readonly sourceText?: string;
+  readonly settings: BacktestSettings;
+  /** The instrument record the engine was handed, `host-interface.md` 4.1. */
+  readonly instrument: Instrument;
+  readonly bars: readonly RecordedBar[];
+  /**
+   * Whether the bars travel in the record or are pointed at.
+   *
+   * Inline is the conformance form, because a case holds every byte of its own
+   * input. Referenced is the operational form, because nothing that grows with
+   * history may travel in a request body. Both carry the same hash over the
+   * same canonical tuples, so one becomes the other without becoming a
+   * different case.
+   */
+  readonly form: 'inline' | 'referenced';
+  readonly frames: readonly RecordedFrame[];
+  readonly fills: readonly RecordedFill[];
+  readonly orders: readonly RecordedOrder[];
+  readonly diagnostics: readonly RecordedDiagnostic[];
+  readonly report: Report;
+}
+
+/**
+ * One run, as the document another engine is handed.
+ *
+ * Nothing is computed here. Every channel arrives folded, because what a record
+ * says has to be what the run did rather than what a second fold of the same
+ * inputs came to: a record that recomputed its own report would agree with
+ * itself whatever the engine had actually done.
+ */
+export function recordOf(parts: RecordParts): RunRecord {
+  return {
+    recordVersion: RECORD_VERSION,
+    engine: { name: ENGINE_NAME, version: VERSION },
+    languageVersion: canonicalNumber(parts.program.openscript.language),
+    program: parts.program,
+    programHash: programHash(parts.program),
+    source: parts.program.source,
+    sourceText: textFor(parts),
+    settings: parts.settings,
+    instrument: parts.instrument,
+    bars: barsIn(parts.bars, parts.form),
+    frames: parts.frames,
+    fills: parts.fills,
+    orders: parts.orders,
+    diagnostics: parts.diagnostics,
+    report: parts.report,
+  };
+}
+
+/**
+ * The source text, checked against the hash the program already carries.
+ *
+ * A check rather than a promise, and it costs one hash of a few kilobytes. The
+ * failure it exists for is quiet: a caller that passes the text of a different
+ * revision than the one it compiled produces a case whose script does not make
+ * its own expected output, and the engine being tested gets the blame for a
+ * disagreement that was in the case all along.
+ */
+function textFor(parts: RecordParts): string | null {
+  const text = parts.sourceText;
+  if (text === undefined) return null;
+  if (sourceHash(text) !== parts.program.source.hash) {
+    throw new Error(
+      'openscript: the source text does not hash to the source hash the program carries',
+    );
+  }
+  return text;
+}
+
+/**
+ * The bars, held or pointed at, and the same hash either way.
+ *
+ * The referenced form keeps the first and last times so that a reader can say
+ * which bars are wanted without holding them, and the count so that a set of
+ * the wrong length is known to be wrong before it is hashed.
+ */
+export function barsIn(bars: readonly RecordedBar[], form: 'inline' | 'referenced'): BarsInRecord {
+  const hash = barsHash(bars);
+  if (form === 'inline') {
+    return { form: 'inline', hash, count: bars.length, rows: bars };
+  }
+  return {
+    form: 'referenced',
+    hash,
+    count: bars.length,
+    firstTime: bars[0]?.time ?? null,
+    lastTime: bars[bars.length - 1]?.time ?? null,
+  };
+}
+
+/**
+ * The hash a record names its bars by.
+ *
+ * Over the canonical tuple of each bar, in the order they were supplied, and
+ * through the canonical encoding the compiled program is hashed with, so there
+ * is one canonical writer in the repository rather than two that agree until
+ * one of them is changed. A tuple rather than an object, because the field
+ * order is then the specification's and not a sort's.
+ */
+export function barsHash(bars: readonly RecordedBar[]): string {
+  const tuples = bars.map((bar) => [
+    bar.time,
+    bar.open,
+    bar.high,
+    bar.low,
+    bar.close,
+    bar.volume,
+    bar.oi,
+  ]);
+  return 'sha256:' + sha256(canonicalise(tuples));
+}
+
+/**
+ * The record as the bytes another engine reads.
+ *
+ * Through the canonical encoding, so key order is fixed, every number is in the
+ * shortest decimal form that reads back as itself, and two runs of the same
+ * record produce the same bytes on every machine. That is what makes the
+ * reproducibility test a byte comparison rather than a tour of the fields.
+ */
+export function recordToJson(record: RunRecord): string {
+  return canonicalise(record);
+}
+
+/**
+ * The run, without who produced it.
+ *
+ * **`engine` is provenance, and provenance is not part of the run.** The claim
+ * a rerun makes is that the run is a function of the record, and that claim has
+ * to survive the engine it runs on being upgraded: a record stored under
+ * `0.3.0` and rerun under `0.4.0` produces the same trades, the same fills and
+ * the same money, and a document carrying the version stamp inside the bytes
+ * being compared says it does not.
+ *
+ * It was compared as whole bytes until the first version bump would have broken
+ * it, which is a test that passes for exactly as long as nothing changes and
+ * then fails for the one reason that is not a defect. So the stamp stays in the
+ * record, because knowing which engine wrote a run is worth keeping, and the
+ * comparison is made over everything else.
+ */
+export function runBytes(record: RunRecord): string {
+  const { engine: _engine, ...run } = record;
+  return canonicalise(run);
+}
+
+/**
+ * A record read back from those bytes.
+ *
+ * A parse and not a validation: what comes back is the document as it was
+ * written, and a document this engine did not write is the caller's to trust or
+ * not. The one thing asserted is the revision, because reading a later
+ * revision's fields under this one's rules is how a record silently becomes a
+ * different run.
+ */
+export function recordFromJson(text: string): RunRecord | null {
+  const parsed: unknown = JSON.parse(text);
+  if (parsed === null || typeof parsed !== 'object') return null;
+  const record = parsed as RunRecord;
+  const version = record.recordVersion;
+  if (typeof version !== 'number' || version < 1 || version > RECORD_VERSION) return null;
+  // An earlier revision is readable and a later one is not, and the asymmetry
+  // is the point. A later revision may mean something by a field this one
+  // thinks it knows, which is how a record silently becomes a different run. An
+  // earlier one only ever has fewer: every channel it carries means here what
+  // it meant there, and the ones added since are absent rather than wrong. So a
+  // run stored months ago still reads, which is the whole of what it was stored
+  // for, and a channel it never carried reads as absent.
+  if (version === RECORD_VERSION) return record;
+  return {
+    ...record,
+    sourceText: version >= ADDED_IN.sourceText ? record.sourceText : null,
+    instrument: version >= ADDED_IN.instrument ? record.instrument : null,
+    frames: version >= ADDED_IN.frameTime ? record.frames : timeless(record.frames),
+  };
+}
+
+/**
+ * The frames of a record written before a frame carried an instant.
+ *
+ * The absence is written on every frame rather than on the record, because the
+ * channel is a field of a row: a reader that left the field undefined would
+ * hand the case projection an undefined where the column's absent spelling
+ * belongs, and the file would read `undefined` back to the next engine. The
+ * frames are left as they are when they are not an array, because this is a
+ * parse and not a validation and a document this engine did not write is the
+ * caller's to trust or not.
+ */
+function timeless(frames: readonly RecordedFrame[]): readonly RecordedFrame[] {
+  if (!Array.isArray(frames)) return frames;
+  return frames.map((frame) => ({ ...frame, time: null }));
+}
+
+/**
+ * One ledger row, flattened into the words a case file prints.
+ *
+ * The engine's own types do not cross: a second engine has its own, and a
+ * channel written in this one's would be a case only this one could read. The
+ * intent is an ordinal for the same reason, because no engine can know what id
+ * another minted.
+ *
+ * `qtyType` comes from the intent rather than from the row, because the unit a
+ * quantity is counted in is per order and not per leg: an order the engine
+ * sized itself is in units whatever the declaration counts in, and a row that
+ * printed the declaration's unit for it would state a quantity in a unit it was
+ * never measured in.
+ */
+export function orderIn(row: LedgerRow, intent: number, qtyType: string): RecordedOrder {
+  return {
+    intent,
+    orderRef: row.orderRef,
+    tag: row.tag,
+    leg: row.leg,
+    positionRef: row.positionRef,
+    symbol: row.instrument.symbol,
+    exchange: row.instrument.exchange,
+    product: row.product,
+    side: row.side,
+    qty: row.qty,
+    qtyType,
+    type: row.type,
+    price: row.price,
+    trigger: row.trigger,
+    status: row.status,
+    filledQty: row.filledQty,
+    avgFillPrice: row.avgFillPrice,
+    rejection: row.rejection === '' ? null : row.rejection,
+    placedAt: row.placedAt,
+    updatedAt: row.updatedAt,
+    units: row.units,
+  };
+}
+
+/** One diagnostic, as a record holds it: the code, the span and the bar. */
+export function diagnosticIn(
+  diagnostic: Diagnostic,
+  barIndex: number | null,
+): RecordedDiagnostic {
+  return {
+    code: diagnostic.code,
+    line: diagnostic.span.line,
+    column: diagnostic.span.column,
+    severity: diagnostic.severity,
+    barIndex,
+  };
+}

package/src/core/backtest/replay.ts

@@ -0,0 +1,168 @@
+/**
+ * A stored run, reported again and run again.
+ *
+ * Two questions, and they are different questions, which is why they are two
+ * calls:
+ *
+ * - **`replay` asks whether the report is a function of the fills.** It folds
+ *   the money again from the record's own fills and its own bar closes, with no
+ *   bar executed and no order placed, and what comes back has to equal the
+ *   report the record carries. If it does not, the report was reading something
+ *   the engine happened to be holding rather than what the run settled, and
+ *   nobody could reproduce it from the document.
+ * - **`rerun` asks whether the engine still does what it did.** It executes the
+ *   record's program over the record's bars under the record's settings, and
+ *   the two records are compared as bytes. A rerun of one record on this engine
+ *   is bit-identical or it is a defect: the tolerance on the record is for a
+ *   second implementation and is never this one's excuse.
+ *
+ * **The bars are proved before either is attempted.** A record names the bars it
+ * was made from by a hash, and bars are revised: a feed corrects a print, a
+ * session is extended, a split is applied to history. A replay over revised bars
+ * reporting the original figures is the most convincing wrong answer this system
+ * can produce, so a set that does not hash to the record's is OS6022.
+ *
+ * **One engine call is made, and nothing is executed by it.** A declaration
+ * field may be written by an `input()`, and what an input resolved to is the
+ * engine's rule; asking it here rather than resolving a second time is what
+ * keeps the replayed capital and commission the ones the run used. No bar is
+ * appended, so no value is computed and no order is placed: the load is a
+ * question about the program, not a run of it.
+ */
+import { reportOf, scheduleFromDeclaration } from '../accounting/index.js';
+import type { ChargeSchedule, Report } from '../accounting/index.js';
+import { diagnosticFor } from '../diagnostics/index.js';
+import type { Diagnostic } from '../diagnostics/index.js';
+import { load } from '../engine/index.js';
+import { backtest } from './drive.js';
+import type { BacktestResult } from './drive.js';
+import { declarationOf } from './declaration.js';
+import type { RunDeclaration } from './declaration.js';
+import { marksFor, windowFor } from './range.js';
+import { barsHash } from './record.js';
+import type { RecordedBar, RunRecord } from './record.js';
+
+/** The report a record folds to, or why it could not be folded. */
+export type ReplayResult =
+  | { readonly ok: true; readonly report: Report }
+  | { readonly ok: false; readonly diagnostic: Diagnostic };
+
+/**
+ * The record's own report, computed again from its own fills.
+ *
+ * The bars are the record's where it carries them and the caller's where it
+ * points at them, and either way they are hashed against what the record names
+ * before a figure is computed from them.
+ */
+export function replay(record: RunRecord, bars: readonly RecordedBar[] | null = null): ReplayResult {
+  const held = barsOf(record, bars);
+  if (!held.ok) return { ok: false, diagnostic: held.diagnostic };
+
+  const framed = windowFor(held.bars, record.settings.range);
+  if (!framed.ok) return { ok: false, diagnostic: framed.diagnostic };
+
+  const declared = declarationIn(record);
+  if (!declared.ok) return { ok: false, diagnostic: declared.diagnostic };
+
+  return {
+    ok: true,
+    report: reportOf(
+      record.fills,
+      marksFor(held.bars, framed.covered),
+      scheduleIn(record, declared.declaration),
+      record.settings.contract,
+      declared.declaration.capital,
+    ),
+  };
+}
+
+/**
+ * The same run, executed again.
+ *
+ * Everything the run depended on is in the record: the program, the bars, the
+ * settings and the inputs. So a rerun takes no argument the record does not
+ * already hold, except the bars a referenced record points at rather than
+ * carries, and the record it produces is comparable with the original field for
+ * field and byte for byte.
+ */
+export function rerun(record: RunRecord, bars: readonly RecordedBar[] | null = null): BacktestResult {
+  const held = barsOf(record, bars);
+  if (!held.ok) return { ok: false, diagnostic: held.diagnostic };
+  // Everything the run depended on, and that includes the two channels that
+  // arrived after the sentence above was written. The instrument record is what
+  // the engine read at load, so a rerun handed the contract alone runs under
+  // different session facts and does not reproduce the bytes; the text is what
+  // makes the rerun's record harvestable, and dropping it would turn a record
+  // that could become a case into one that cannot, by being rerun.
+  return backtest(record.program, held.bars, record.settings, {
+    form: record.bars.form,
+    ...(record.instrument === null ? {} : { instrument: record.instrument }),
+    ...(record.sourceText === null ? {} : { sourceText: record.sourceText }),
+  });
+}
+
+type BarsResult =
+  | { readonly ok: true; readonly bars: readonly RecordedBar[] }
+  | { readonly ok: false; readonly diagnostic: Diagnostic };
+
+/**
+ * The bars a record was made from, proved to be those bars.
+ *
+ * A record carrying its own bars is still checked against any that are supplied
+ * beside them, because supplying a different set is exactly the mistake worth
+ * catching: the caller believes they are replaying this run and they are
+ * studying another one.
+ */
+export function barsOf(record: RunRecord, supplied: readonly RecordedBar[] | null): BarsResult {
+  if (supplied !== null) {
+    const hash = barsHash(supplied);
+    if (hash !== record.bars.hash) return { ok: false, diagnostic: mismatch(hash, record) };
+    return { ok: true, bars: supplied };
+  }
+  if (record.bars.form === 'inline') return { ok: true, bars: record.bars.rows };
+  // A referenced record points at bars it does not hold, so there is nothing to
+  // replay until whoever holds them supplies them. It is the same refusal as a
+  // wrong set, because the question it answers is the same one: are these the
+  // bars the record was made from.
+  return { ok: false, diagnostic: mismatch('no bars supplied', record) };
+}
+
+function mismatch(found: string, record: RunRecord): Diagnostic {
+  return diagnosticFor('OS6022', NO_POSITION, { found, expected: record.bars.hash });
+}
+
+type DeclarationResult =
+  | { readonly ok: true; readonly declaration: RunDeclaration }
+  | { readonly ok: false; readonly diagnostic: Diagnostic };
+
+/**
+ * What the record's own program declares, after the record's own inputs.
+ *
+ * The destination handed to the load is one that answers nothing, because
+ * nothing is placed: a strategy declares the orders capability and a host that
+ * did not offer it would be refused at load for a reason that has nothing to do
+ * with the record.
+ */
+function declarationIn(record: RunRecord): DeclarationResult {
+  const loaded = load(record.program, {
+    settings: record.settings.inputs,
+    host: { route: () => undefined },
+  });
+  if (!loaded.ok) return { ok: false, diagnostic: loaded.diagnostic };
+  return { ok: true, declaration: declarationOf(loaded.engine.program, loaded.inputs) };
+}
+
+/** The cost model the record was carried out under, derived where it was derived. */
+function scheduleIn(record: RunRecord, declared: RunDeclaration): ChargeSchedule {
+  if (record.settings.costs !== null) return record.settings.costs;
+  return scheduleFromDeclaration(
+    declared.commission,
+    declared.commissionType,
+    declared.slippage,
+    record.settings.contract.currency,
+    record.settings.contract.digits,
+  );
+}
+
+/** Where a refusal about a record points: nowhere in anybody's script. */
+const NO_POSITION: Diagnostic['span'] = { offset: 0, length: 0, line: 0, column: 0 };