openalgo-script 0.4.0 → 0.5.0

package/src/core/backtest/drive.ts

@@ -25,9 +25,16 @@
  * is reported on bar k + 1. A frame answered after the last bar has no boundary
  * left to fold at: it is not delivered, it is not recorded as delivered, and
  * the order it was about is in the ledger at whatever it last said.
+ *
+ * **Two drivers, and the only difference between them is where the frames come
+ * from.** `backtest` runs against the simulated destination, which decides a
+ * fill from the bars and answers frames of its own; `backtestSupplied` is
+ * handed the frames and delivers those. Everything else about the two is one
+ * function below: the same window, the same load, the same refusals, the same
+ * loop and the same record.
  */
 import { reportOf, scheduleFromDeclaration } from '../accounting/index.js';
-import type { ChargeSchedule, RecordedFill } from '../accounting/index.js';
+import type { ChargeSchedule, Contract, RecordedFill } from '../accounting/index.js';
 import type { Diagnostic } from '../diagnostics/index.js';
 import type { CompiledProgram } from '../emit/index.js';
 import { load } from '../engine/index.js';
@@ -37,12 +44,13 @@ import type {
   EngineHost,
   Instrument,
   LedgerRow,
-  OrderFrame,
   OrderIntent,
   RoutedEffect,
 } from '../engine/index.js';
 import { declarationOf } from './declaration.js';
 import type { RunDeclaration } from './declaration.js';
+import { Delivery, framedAs, ordinalsOf } from './deliver.js';
+import type { Delivered, Destination } from './deliver.js';
 import { marksFor, windowFor } from './range.js';
 import type { ReportWindow } from './range.js';
 import { diagnosticIn, orderIn, recordOf } from './record.js';
@@ -62,14 +70,114 @@ export type BacktestResult =
   | { readonly ok: true; readonly record: RunRecord }
   | { readonly ok: false; readonly diagnostic: Diagnostic };
 
+/**
+ * The facts of `host-interface.md` 4.1 that the contract does not hold.
+ *
+ * The contract already states six of the twelve, the ones the money is priced
+ * under, and a fact stated in two places is a fact that can disagree with
+ * itself: a tick size the engine rounds to and a different one the venue
+ * worsens a fill by is a run under two instruments. So the other six are
+ * stated here and the six the contract holds cannot be, which the compiler
+ * enforces rather than a check at run time.
+ */
+export type InstrumentFacts = Omit<
+  Instrument,
+  'symbol' | 'exchange' | 'tickSize' | 'lotSize' | 'pointValue' | 'currency'
+>;
+
 /** The few choices a driver has that are not settings of the run itself. */
 export interface DriveOptions {
   /** Whether the bars travel in the record. Inline is the conformance form. */
   readonly form?: 'inline' | 'referenced';
+  /**
+   * What the host states about the instrument beside the contract, so the
+   * record it produces is a conformance case.
+   *
+   * A case holds `instrument.json`, which `conformance.md` section 2 says is
+   * the record of `host-interface.md` 4.1, and that page requires one fact of
+   * every host: `hasVolume`, because no derivation recovers it (4.2). The
+   * engine reads the record and does not refuse a run without it, so a caller
+   * that leaves this out gets a record that replays and reruns like any other
+   * and cannot become a case, exactly as one without `sourceText` cannot.
+   *
+   * A session stated without a timezone is refused at load, OS6012, by the
+   * same rule that refuses it for any host.
+   */
+  readonly instrument?: InstrumentFacts;
+  /**
+   * The script's own text, so the record it produces is a conformance case.
+   *
+   * A compiled program identifies its source and cannot reproduce it, and a
+   * case has to hold `script.os`. A caller holding only a program leaves this
+   * out and gets a record that replays and reruns like any other; the one
+   * thing it cannot do is be handed to somebody else's engine as a case.
+   *
+   * It is checked against the program's own source hash, so text from a
+   * different revision than the one that was compiled is refused rather than
+   * written into a case that could never make its own expected output.
+   */
+  readonly sourceText?: string;
 }
 
 /**
- * One run, from a compiled program to a record of it.
+ * One run against a simulated destination, from a compiled program to a record.
+ *
+ * The frames are the destination's own: it is handed the orders, it reads the
+ * bars, and what it answers is what the engine folds. A run whose frames
+ * somebody else is supplying is `backtestSupplied` below.
+ */
+export function backtest(
+  program: CompiledProgram,
+  bars: readonly RecordedBar[],
+  settings: BacktestSettings,
+  options: DriveOptions = {},
+): BacktestResult {
+  return drive(program, bars, settings, options, (declared, schedule) =>
+    simulated(
+      new Simulator({
+        bars,
+        contract: settings.contract,
+        fill: settings.fill,
+        slippageTicks: schedule.slippageTicks,
+        fillOn: declared.fillOn,
+        qtyType: declared.qtyType,
+      }),
+    ),
+  );
+}
+
+/**
+ * One run over the frames somebody else supplied, which this engine does not
+ * choose and does not add to.
+ *
+ * `conformance.md` section 3 gives a case a `frames.csv` that supplies order
+ * frames the way `bars.csv` supplies bars, so that a case asserts the fold
+ * against input the engine did not choose. Every other argument is `backtest`'s
+ * and means there what it means here. A row is delivered at the boundary it
+ * names and folded before the next bar, and the record carries the rows it was
+ * handed rather than a second spelling of them.
+ *
+ * **Nothing is invented.** No fill is priced off a bar, no order rests and no
+ * schedule is read, so an order the frames say nothing about stays where its
+ * placement left it, which is what a case saying nothing about it means.
+ *
+ * **A record made here is a record of this run and not of a simulated one.**
+ * `rerun` puts a record's program back on a simulated destination, because a
+ * record does not say which of the two answered it, so a rerun of one of these
+ * reproduces it only where that destination would answer these same frames.
+ */
+export function backtestSupplied(
+  program: CompiledProgram,
+  bars: readonly RecordedBar[],
+  settings: BacktestSettings,
+  frames: readonly RecordedFrame[],
+  options: DriveOptions = {},
+): BacktestResult {
+  return drive(program, bars, settings, options, () => new Delivery(frames));
+}
+
+/**
+ * The run both drivers are, and the one place a record is made.
  *
  * A refusal before the first bar comes back as a refusal and not as a record:
  * a program that would not load, a setting that cannot be applied and a window
@@ -77,24 +185,28 @@ export interface DriveOptions {
  * be a document asserting figures nothing computed. A failure during a bar is
  * the other way round: the run happened, it stopped, and the record carries
  * both what it did and the diagnostic that stopped it.
+ *
+ * **The destination is chosen after the program is loaded**, which is why it
+ * arrives as a function of the declaration and the schedule: the bar a market
+ * order is priced at is the declaration's, and the declaration is resolved at
+ * load. The route is wired first and reaches whatever is chosen through the
+ * binding below, which is what lets one host serve both halves.
  */
-export function backtest(
+function drive(
   program: CompiledProgram,
   bars: readonly RecordedBar[],
   settings: BacktestSettings,
-  options: DriveOptions = {},
+  options: DriveOptions,
+  choose: (declared: RunDeclaration, schedule: ChargeSchedule) => Destination,
 ): BacktestResult {
   const framed = windowFor(bars, settings.range);
   if (!framed.ok) return { ok: false, diagnostic: framed.diagnostic };
 
-  // The venue is built after the program is loaded, because the bar a market
-  // order is priced at is the declaration's and the declaration is resolved at
-  // load. The route is wired first and reaches it through this binding, which
-  // is what lets one host serve both halves.
-  let venue: Simulator | undefined;
+  let sending: Destination | undefined;
+  const instrument = instrumentFor(settings.contract, options.instrument ?? {});
   const loaded = load(program, {
     settings: settings.inputs,
-    host: hostFor(settings, (effect, bar) => venue?.route(effect, bar)),
+    host: hostFor(instrument, settings.now, (effect, bar) => sending?.route(effect, bar)),
   });
   if (!loaded.ok) return { ok: false, diagnostic: loaded.diagnostic };
 
@@ -104,39 +216,42 @@ export function backtest(
   if (problem !== null) return { ok: false, diagnostic: problem };
 
   const schedule = scheduleFor(settings, declared);
-  venue = new Simulator({
-    bars,
-    contract: settings.contract,
-    fill: settings.fill,
-    slippageTicks: schedule.slippageTicks,
-    fillOn: declared.fillOn,
-    qtyType: declared.qtyType,
-  });
+  const destination = choose(declared, schedule);
+  sending = destination;
 
-  const run = walk(engine, venue, bars, framed.covered);
-  const ordinals = ordinalsOf(venue.intents);
+  const run = walk(engine, destination, bars, framed.covered);
+  const ordinals = ordinalsOf(destination.intents);
   const marks = marksFor(bars, framed.covered);
 
   return {
     ok: true,
     record: recordOf({
       program: engine.program,
+      ...(options.sourceText === undefined ? {} : { sourceText: options.sourceText }),
       settings,
+      instrument,
       bars,
       form: options.form ?? 'inline',
-      frames: run.frames.map((one) => framedAs(one.frame, one.afterBar, ordinals)),
+      // The row where a case supplied one, because that row is the input and a
+      // record of a run over it says what it was given rather than what it
+      // would have written down had it decided the frame itself.
+      frames: run.frames.map((one) => one.row ?? framedAs(one.frame, one.afterBar, ordinals)),
       fills: run.fills,
-      orders: ordersOf(engine.orders(), venue.intents, ordinals),
+      orders: ordersOf(engine.orders(), destination.intents, ordinals),
       diagnostics: run.diagnostics,
       report: reportOf(run.fills, marks, schedule, settings.contract, declared.capital),
     }),
   };
 }
 
-/** A frame, and the boundary it was handed over at. */
-interface Delivered {
-  readonly frame: OrderFrame;
-  readonly afterBar: number;
+/** The simulated destination, as a destination the loop below can drive. */
+function simulated(venue: Simulator): Destination {
+  return {
+    route: (effect, barIndex) => venue.route(effect, barIndex),
+    answers: (barIndex) =>
+      venue.framesFor(barIndex).map((frame) => ({ frame, afterBar: barIndex, row: null })),
+    intents: venue.intents,
+  };
 }
 
 /** What one walk of the bars produced. */
@@ -155,7 +270,7 @@ interface Walked {
  */
 function walk(
   engine: Engine,
-  venue: Simulator,
+  destination: Destination,
   bars: readonly RecordedBar[],
   covered: ReportWindow,
 ): Walked {
@@ -196,7 +311,7 @@ function walk(
       break;
     }
 
-    pending = venue.framesFor(index).map((frame) => ({ frame, afterBar: index }));
+    pending = destination.answers(index);
   }
 
   return { fills, frames, diagnostics };
@@ -273,38 +388,6 @@ function intentsIn(result: BarResult): readonly OrderIntent[] {
   return out;
 }
 
-/**
- * The ordinal of every intent, which is how a case names one.
- *
- * One, two, three in the order the run placed them, because no engine can know
- * the id another minted and a case that named one would only ever be readable
- * by the engine that wrote it.
- */
-function ordinalsOf(intents: readonly OrderIntent[]): ReadonlyMap<number, number> {
-  const out = new Map<number, number>();
-  for (const intent of intents) {
-    if (!out.has(intent.intentId)) out.set(intent.intentId, out.size + 1);
-  }
-  return out;
-}
-
-/** One delivered frame, in the columns a case file prints. */
-function framedAs(
-  frame: OrderFrame,
-  afterBar: number,
-  ordinals: ReadonlyMap<number, number>,
-): RecordedFrame {
-  return {
-    afterBar,
-    intent: ordinals.get(frame.intentId) ?? 0,
-    status: frame.status,
-    filledQty: frame.filledQty,
-    avgFillPrice: frame.avgFillPrice ?? null,
-    orderRef: frame.orderRef ?? null,
-    text: frame.text ?? null,
-  };
-}
-
 /** The ledger at the end, copied out of the engine's own array. */
 function ordersOf(
   rows: readonly LedgerRow[],
@@ -336,6 +419,34 @@ function scheduleFor(settings: BacktestSettings, declared: RunDeclaration): Char
   );
 }
 
+/**
+ * The instrument record of `host-interface.md` 4.1 the engine is handed, and
+ * the record carries verbatim.
+ *
+ * Composed once, here, from the contract's six facts and the six stated beside
+ * it, so the engine and the record read one document and there is no second
+ * composition for the two to disagree by. A fact nobody stated is left out
+ * rather than written as undefined: the record travels as JSON, which drops an
+ * undefined member, and a document that changes shape in transit is not the
+ * document the engine read.
+ */
+function instrumentFor(contract: Contract, facts: InstrumentFacts): Instrument {
+  return {
+    ...(contract.symbol === null ? {} : { symbol: contract.symbol }),
+    ...(contract.exchange === null ? {} : { exchange: contract.exchange }),
+    ...(facts.interval === undefined ? {} : { interval: facts.interval }),
+    ...(facts.timezone === undefined ? {} : { timezone: facts.timezone }),
+    ...(contract.tickSize === null ? {} : { tickSize: contract.tickSize }),
+    ...(contract.lotSize === null ? {} : { lotSize: contract.lotSize }),
+    pointValue: contract.pointValue,
+    currency: contract.currency,
+    ...(facts.instrumentType === undefined ? {} : { instrumentType: facts.instrumentType }),
+    ...(facts.hasVolume === undefined ? {} : { hasVolume: facts.hasVolume }),
+    ...(facts.hasOpenInterest === undefined ? {} : { hasOpenInterest: facts.hasOpenInterest }),
+    ...(facts.session === undefined ? {} : { session: facts.session }),
+  };
+}
+
 /**
  * The host a backtest is: an instrument record, a clock and a destination.
  *
@@ -345,20 +456,13 @@ function scheduleFor(settings: BacktestSettings, declared: RunDeclaration): Char
  * with nothing in it.
  */
 function hostFor(
-  settings: BacktestSettings,
+  instrument: Instrument,
+  now: number | null,
   route: (effect: RoutedEffect, bar: number) => void,
 ): EngineHost {
-  const instrument: Instrument = {
-    ...(settings.contract.symbol === null ? {} : { symbol: settings.contract.symbol }),
-    ...(settings.contract.exchange === null ? {} : { exchange: settings.contract.exchange }),
-    ...(settings.contract.tickSize === null ? {} : { tickSize: settings.contract.tickSize }),
-    ...(settings.contract.lotSize === null ? {} : { lotSize: settings.contract.lotSize }),
-    pointValue: settings.contract.pointValue,
-    currency: settings.contract.currency,
-  };
   return {
     instrument,
-    ...(settings.now === null ? {} : { now: settings.now }),
+    ...(now === null ? {} : { now }),
     route,
   };
 }

package/src/core/backtest/index.ts

@@ -14,18 +14,28 @@
  * worsened by a tick and a fill is charged. The engine never adjusts a price and
  * this module never folds one.
  *
- * `backtest` drives one, `replay` folds a stored one's money again from its own
- * fills, and `rerun` executes a stored one again and is held to producing the
- * same bytes. `recordToJson` and `recordFromJson` are the document itself.
- * `compareRuns` puts two records beside each other and says whether the gap
- * between them clears the noise. `caseFilesFrom` is named by the design and is
- * not here yet: it will return text and write nothing, because core does no
- * I/O, and it needs a channel the record does not carry today. `conformance.md`
- * section 2 requires a case to hold `script.os`, the source text, and a record
- * carries only the source's hash, its line count and its file name.
+ * `backtest` drives one against a simulated destination and `backtestSupplied`
+ * drives one over frames somebody else supplied, which is what `conformance.md`
+ * section 3 asks of an engine running a case. `replay` folds a stored one's
+ * money again from its own fills, and `rerun` executes a stored one again and
+ * is held to producing the same bytes. `recordToJson` and `recordFromJson` are
+ * the document itself. `compareRuns` puts two records beside each other and
+ * says whether the gap between them clears the noise. `caseFilesFrom` turns a
+ * record into the files of a conformance case, returning text and writing
+ * nothing because core does no I/O. It needed three channels the record did not
+ * carry. `conformance.md` section 2 requires a case to hold `script.os`, the
+ * source text, and a record carried only the source's hash, its line count and
+ * its file name: record version 2 carries the text, checked against that hash.
+ * The same section says `instrument.json` is the record of `host-interface.md`
+ * 4.1, and a record carried the money layer's contract, which holds six of its
+ * twelve facts: record version 3 carries the record the engine was handed,
+ * whole. And a case is handed frames, which `stdlib.md` 17.7 folds one ledger
+ * field from an instant of: a record carried a frame without the instant it
+ * arrived at, so a case projected from it asserted a field its own input could
+ * not reproduce. Record version 4 carries a frame's time.
  */
-export { backtest } from './drive.js';
-export type { BacktestResult, DriveOptions } from './drive.js';
+export { backtest, backtestSupplied } from './drive.js';
+export type { BacktestResult, DriveOptions, InstrumentFacts } from './drive.js';
 export { declarationOf } from './declaration.js';
 export type { RunDeclaration } from './declaration.js';
 export { marksFor, windowFor } from './range.js';
@@ -35,8 +45,10 @@ export type { ReplayResult } from './replay.js';
 export { testResting } from './resting.js';
 export type { RestOutcome, RestingOrder } from './resting.js';
 export { Simulator } from './simulate.js';
-export type { SimulatorOptions } from './simulate.js';
+export type { SimulatorOptions, VenueAct, VenueDoes, VenuePolicy } from './simulate.js';
 export { DEFAULT_FILL, EXACT, WHOLE_RANGE, checkSettings, settingsFor } from './settings.js';
+export { caseFilesFrom } from './case.js';
+export type { CaseFiles, CaseIdentity, CaseResult } from './case.js';
 export { RECORD_VERSION, barsHash, recordFromJson, recordOf, recordToJson, runBytes } from './record.js';
 export type { RecordParts } from './record.js';
 export type { BacktestSettings, DateRange, FillPolicy, Tolerance } from './settings.js';

package/src/core/backtest/record.ts

@@ -26,9 +26,9 @@
  */
 import type { RecordedFill, Report } from '../accounting/index.js';
 import type { Diagnostic } from '../diagnostics/index.js';
-import { canonicalise, programHash, sha256 } from '../emit/index.js';
+import { canonicalNumber, canonicalise, programHash, sha256, sourceHash } from '../emit/index.js';
 import type { CompiledProgram, SourceStamp } from '../emit/index.js';
-import type { LedgerRow } from '../engine/index.js';
+import type { Instrument, LedgerRow } from '../engine/index.js';
 import { VERSION } from '../version/index.js';
 import type { BacktestSettings } from './settings.js';
 
@@ -75,6 +75,20 @@ export interface RecordedFrame {
   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. */
@@ -121,7 +135,43 @@ export interface RunRecord {
   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[];
@@ -141,7 +191,22 @@ export interface RunRecord {
  * 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 = 1;
+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';
@@ -149,7 +214,18 @@ 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.
@@ -180,11 +256,13 @@ export function recordOf(parts: RecordParts): RunRecord {
   return {
     recordVersion: RECORD_VERSION,
     engine: { name: ENGINE_NAME, version: VERSION },
-    languageVersion: String(parts.program.openscript.language),
+    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,
@@ -194,6 +272,26 @@ export function recordOf(parts: RecordParts): RunRecord {
   };
 }
 
+/**
+ * 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.
  *
@@ -283,7 +381,38 @@ 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;
-  return record.recordVersion === RECORD_VERSION ? record : null;
+  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 }));
 }
 
 /**

package/src/core/backtest/replay.ts

@@ -88,7 +88,17 @@ export function replay(record: RunRecord, bars: readonly RecordedBar[] | null =
 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 };
-  return backtest(record.program, held.bars, record.settings, { form: record.bars.form });
+  // 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 =