openalgo-script 0.2.0 → 0.5.0

package/src/core/backtest/case.ts

@@ -0,0 +1,395 @@
+/**
+ * A run record, turned into the files a conformance case is made of.
+ *
+ * **The suite is harvested rather than written.** A case invented by hand tests
+ * what somebody imagined a run does; a case taken from a run tests what a run
+ * actually did. `conformance.md` section 2 says a case is one directory of named
+ * files, and a record already holds every one of them: the script it ran, the
+ * bars it ran over, the settings it ran with, and what came back. So this is a
+ * projection and not a computation. Nothing here folds money, re-reads a report
+ * or decides anything a run did not already decide.
+ *
+ * **Text out, and no I/O.** Core writes no files, so this returns the bytes and
+ * the caller puts them where it likes. That also makes it testable without a
+ * disk and usable from a browser, which is where most runs happen.
+ *
+ * **What it refuses, it refuses loudly.** A case with a missing file is worse
+ * than no case: it fails on somebody else's engine and the blame lands on them.
+ * So a record that cannot make a whole case does not make a partial one, and a
+ * record that cannot make a faithful file does not guess at one: the script it
+ * has no text for and the instrument fact its host never stated are both
+ * refusals, never a hole and never a default.
+ *
+ * **Every setting of the run has a place in the case, and the table below says
+ * which.** A run once harvested to a case that said nothing about the digit
+ * count its money was rounded to, the charge schedule its host supplied or the
+ * window its report was about, so a second engine ran under other values and
+ * took the blame. `CARRIED` names the file each field of the settings is
+ * carried in, the type refuses to compile when the settings gain a field with
+ * no row, and a record whose settings hold a field the table does not know is
+ * refused by name rather than written into a case that ran under something it
+ * does not state.
+ */
+import { diagnosticFor } from '../diagnostics/index.js';
+import type { Diagnostic } from '../diagnostics/index.js';
+import { canonicalNumber, canonicalise } from '../emit/index.js';
+import type { Instrument } from '../engine/index.js';
+import type { RecordedBar, RecordedFrame, RunRecord } from './record.js';
+import type { BacktestSettings, Tolerance } from './settings.js';
+
+/** The files of one case, keyed by the name `conformance.md` section 2 gives them. */
+export type CaseFiles = Readonly<Record<string, string>>;
+
+/** Why a record could not become a case. */
+export interface CaseRefusal {
+  readonly ok: false;
+  readonly reason: string;
+  /**
+   * The catalogue code the refusal is filed under, or null.
+   *
+   * A refusal about a setting of the run is the catalogue's, OS6021, because
+   * it is the same refusal the run makes of a setting it cannot be carried out
+   * under. The others here are about what the record holds, a text it never
+   * carried, a bar list it only points at, a fact its host never stated, and
+   * no catalogue entry is about those.
+   */
+  readonly code: string | null;
+}
+
+export interface CaseWritten {
+  readonly ok: true;
+  readonly files: CaseFiles;
+}
+
+export type CaseResult = CaseWritten | CaseRefusal;
+
+/** What the caller has to say, because a record cannot know it. */
+export interface CaseIdentity {
+  /**
+   * The directory path under the suite root, which is also the case id.
+   *
+   * The caller's because a record does not know where it will live, and
+   * `case.json` repeats it on purpose so a directory that is moved without its
+   * id being changed is caught by the suite rather than by a confused reader.
+   */
+  readonly id: string;
+  /** One sentence. It is the failure message a runner prints. */
+  readonly description: string;
+  /** Section 7's categories. Defaults to the one a strategy run belongs to. */
+  readonly category?: string;
+}
+
+/**
+ * The channels a strategy run can be held to.
+ *
+ * Only what the record carries folded, and only what another engine could
+ * produce independently. A case asserts the channels it names and no others, so
+ * a change to drawing output cannot break a case about money.
+ */
+const STRATEGY_ASSERTS = ['diagnostics', 'orders', 'trades', 'performance'] as const;
+
+/**
+ * `conformance.md` section 6: the loosest bounds a conformance case may declare.
+ *
+ * Core reads no page, so the two figures are written here, and
+ * `tests/backtest/case-settings.test.ts` reads them out of section 6 and holds
+ * these to the page, which is the arrangement `stdlib.md` section 20's figures
+ * are under. Past either bound a run may still be a useful comparison; what it
+ * is not is a case, so the projection makes no file of it.
+ */
+export const TOLERANCE_CAP: { readonly rel: number; readonly abs: number } = {
+  rel: 1e-9,
+  abs: 1e-12,
+};
+
+/**
+ * Where each setting of a run is carried in a case, sections 2 and 3.
+ *
+ * Every field of the settings has a row and the type makes a field without one
+ * a compile error, so a setting the record gains cannot be left out of a case
+ * by forgetting. `fill` is the simulated destination's policy, and what it
+ * decided is the frames, which are input: an engine handed `frames.csv` folds
+ * them and fills nothing itself.
+ */
+const CARRIED: Readonly<Record<keyof BacktestSettings, string>> = {
+  contract: 'instrument.json, and backtest.json for the digit count',
+  costs: 'backtest.json',
+  range: 'backtest.json',
+  inputs: 'settings.json',
+  now: 'case.json',
+  tolerance: 'case.json',
+  fill: 'frames.csv, as the frames it decided',
+};
+
+/**
+ * Where a refusal about a setting points: nowhere in the script.
+ *
+ * A run setting is what the host stated before the first bar, and a caret
+ * under a line of the strategy would blame the one party that did not choose
+ * it. The run's own settings check states the same position for the same reason.
+ */
+const NO_POSITION: Diagnostic['span'] = { offset: 0, length: 0, line: 0, column: 0 };
+
+/**
+ * The files for one case, or the reason there are none.
+ *
+ * `now` is written only when the run pinned one. A case that names it when the
+ * script never asked pins a clock the run did not depend on, and the next
+ * reader has to work out whether it mattered.
+ */
+export function caseFilesFrom(record: RunRecord, identity: CaseIdentity): CaseResult {
+  if (record.sourceText === null) {
+    return refused(
+      'the record carries no source text, so the case would have no script.os: ' +
+        'record it with sourceText, or re-run the script to record one that has it',
+    );
+  }
+  if (record.bars.form !== 'inline') {
+    return refused(
+      'the record points at its bars instead of holding them, and a case holds every ' +
+        'byte of its own input: record it with form "inline"',
+    );
+  }
+  if (identity.id.trim() === '') return refused('a case needs an id');
+  if (identity.description.trim() === '') {
+    return refused('a case needs a one-sentence description, which is its failure message');
+  }
+  const instrument = instrumentOf(record);
+  if (!instrument.ok) return instrument;
+  const settings = settingsRefusal(record.settings);
+  if (settings !== null) return settings;
+
+  const files: Record<string, string> = {
+    'case.json': json({
+      id: identity.id,
+      category: identity.category ?? 'strategy',
+      profile: 'strategy',
+      languageVersion: Number(record.languageVersion),
+      description: identity.description,
+      asserts: [...STRATEGY_ASSERTS],
+      ...(record.settings.now === null ? {} : { now: record.settings.now }),
+      tolerance: record.settings.tolerance,
+    }),
+    'script.os': endsWithNewline(record.sourceText),
+    'bars.csv': barsCsv(record.bars.rows),
+    // `conformance.md` section 4: performance is a list of one flat object
+    // holding the summary statistics and nothing nested. The trades are their
+    // own channel and are not repeated inside it, because a figure stated
+    // twice in one case is a figure that can disagree with itself. The equity
+    // curve, the monthly table and the markers are not written at all: the
+    // first two are not conformance channels, being derived from fills and
+    // closes the case already fixes, and a marker is a chart output the
+    // `markers` channel owns, which a case about money does not assert.
+    'expected.json': json({
+      diagnostics: record.diagnostics,
+      orders: record.orders,
+      trades: record.report.trades,
+      performance: [record.report.summary],
+    }),
+    // Section 2: the record of `host-interface.md` 4.1, which is what the
+    // engine was handed and not the money layer's contract. The suite's
+    // defaults for an absent file are boring on purpose and are not this run's
+    // instrument, so the file is always written.
+    'instrument.json': json(instrument.value),
+    // Section 3: what the report was folded under and the script never states.
+    // Always written, because every run rounds money to some digit count, and a
+    // strategy case that left it out would be run under whatever count a runner
+    // assumed. `costs` is null for the declaration's own schedule and `range`
+    // carries null for a bound nobody stated, so the file says what the run ran
+    // under in every case rather than leaving a default to a runner.
+    'backtest.json': json({
+      digits: record.settings.contract.digits,
+      costs: record.settings.costs,
+      range: record.settings.range,
+    }),
+  };
+
+  // Without this the case is unpassable, on every engine including the one that
+  // wrote it. `conformance.md` section 3 ends "a case with no `frames.csv` is
+  // handed no frames at all", and what `expected.json` asserts through the
+  // orders channel is what came of the frames: a status, a cumulative quantity,
+  // an average fill price. An engine handed none of them folds nothing and
+  // disagrees with every row, and the failure reads as a defect in that engine.
+  //
+  // Written only when the run had frames, because an empty file and an absent
+  // one mean the same thing here and the absent one says it in fewer bytes.
+  if (record.frames.length > 0) files['frames.csv'] = framesCsv(record.frames);
+
+  // Written only when the run had inputs to write. An empty settings.json says
+  // "these are the values" about nothing, and section 2 reads an absent one as
+  // every input taking its declared default, which is what actually happened.
+  if (Object.keys(record.settings.inputs).length > 0) {
+    files['settings.json'] = json(record.settings.inputs);
+  }
+
+  return { ok: true, files };
+}
+
+/** A refusal about what the record holds, which no catalogue entry is about. */
+function refused(reason: string): CaseRefusal {
+  return { ok: false, reason, code: null };
+}
+
+/**
+ * The instrument record a case can state faithfully, or why there is none.
+ *
+ * Two refusals, and both are the same refusal: the file `conformance.md`
+ * section 2 names is the record of `host-interface.md` 4.1, and a record that
+ * cannot produce that record cannot produce the file.
+ *
+ * A record written before version 3 carries none, because the facts beside
+ * the contract were handed to the engine and written down nowhere. And 4.1
+ * requires one fact of every host, `hasVolume`, which is the one the engine
+ * does not refuse a run without: a run whose host never stated it ran with the
+ * flag absent, so a file stating it would hand a second engine a different
+ * study than the one the expected output came from, and a file omitting it is
+ * not a 4.1 record. The other rules that page states about a record, a session
+ * with no timezone to read it in, are refused at load, so a run that happened
+ * cannot carry one.
+ */
+function instrumentOf(
+  record: RunRecord,
+): { readonly ok: true; readonly value: Instrument } | CaseRefusal {
+  if (record.instrument === null) {
+    return refused(
+      'the record carries no instrument record, so the case would have no instrument.json: ' +
+        'it was written before record version 3, and re-running the script records one',
+    );
+  }
+  if (typeof record.instrument.hasVolume !== 'boolean') {
+    return refused(
+      'the run was handed no hasVolume, which host-interface.md 4.1 requires of every ' +
+        'host, so instrument.json cannot be the record that page defines: run the script ' +
+        'with the instrument facts stated',
+    );
+  }
+  return { ok: true, value: record.instrument };
+}
+
+/**
+ * Whether every setting the run was carried out under has a place in the case,
+ * and whether its tolerance is one the suite accepts.
+ *
+ * The first question is asked of the record rather than of the type, because a
+ * record read back from JSON is whatever was written: a field this projection
+ * has no file for is refused with its name, never passed over into a case that
+ * then ran under a value it does not state.
+ */
+function settingsRefusal(settings: BacktestSettings): CaseRefusal | null {
+  for (const key of Object.keys(settings)) {
+    if (key in CARRIED) continue;
+    return refused(
+      `the record's settings carry ${key}, which no file of conformance.md section 2 has a ` +
+        'place for, so a case written from it would run under a setting it does not state: ' +
+        'give the setting a file on that page and a row in this projection first',
+    );
+  }
+  return toleranceRefusal(settings.tolerance);
+}
+
+/**
+ * A tolerance past the cap is a comparison somebody may find useful and is not
+ * a case, `conformance.md` section 6.
+ *
+ * Refused here, where the case is written, and not only where one is read,
+ * because a directory the suite will not accept fails every runner it meets
+ * and the blame lands on the engine under test. The run's own settings check
+ * refuses a bound with no reason and a bound below zero before a record
+ * exists; the cap is the one rule about a tolerance that is the suite's rather
+ * than the run's, so it is the one asked here.
+ */
+function toleranceRefusal(tolerance: Tolerance): CaseRefusal | null {
+  const { abs, rel } = tolerance;
+  if (!Number.isFinite(abs) || !Number.isFinite(rel)) {
+    return settingRefusal('a bound is not a finite number');
+  }
+  if (abs <= TOLERANCE_CAP.abs && rel <= TOLERANCE_CAP.rel) return null;
+  return settingRefusal(
+    `a bound of ${canonicalNumber(abs)} absolute and ${canonicalNumber(rel)} relative is ` +
+      'past the cap conformance.md section 6 puts on a conformance case, ' +
+      `${canonicalNumber(TOLERANCE_CAP.abs)} absolute and ${canonicalNumber(TOLERANCE_CAP.rel)} ` +
+      'relative, so this run is a comparison and not a case',
+  );
+}
+
+/** A refusal about the comparison tolerance, filed under the run's own code for a setting. */
+function settingRefusal(problem: string): CaseRefusal {
+  const diagnostic = diagnosticFor('OS6021', NO_POSITION, {
+    setting: 'The comparison tolerance',
+    problem,
+  });
+  return { ok: false, reason: diagnostic.message, code: diagnostic.code };
+}
+
+/**
+ * Through the canonical writer, so a case's bytes are the record's bytes.
+ *
+ * There is one canonical writer in this repository and this is not a second
+ * one: key order and number form are fixed for everybody, which is what lets a
+ * case be compared as text at all.
+ */
+function json(value: unknown): string {
+  return `${canonicalise(value)}\n`;
+}
+
+/** `conformance.md` section 3: header, one row per bar, oldest first, `none` for absent. */
+function barsCsv(rows: readonly RecordedBar[]): string {
+  const lines = ['time,open,high,low,close,volume'];
+  for (const bar of rows) {
+    lines.push(
+      [bar.time, bar.open, bar.high, bar.low, bar.close, bar.volume].map(cell).join(','),
+    );
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * `conformance.md` section 3: the fields of a frame, in the order that page names.
+ *
+ * A projection and not a translation. The record already holds an intent as an
+ * ordinal rather than as this engine's own id, for the reason the same section
+ * gives: a case cannot know the id another engine minted and must not depend on
+ * its spelling.
+ *
+ * The instant is written on every row, `none` where the destination stated
+ * none, through the same cell writer as an absent price. A case whose frames
+ * carried instants and whose file did not would assert an `updatedAt` that its
+ * own input cannot reproduce, which is what the column closes.
+ */
+function framesCsv(frames: readonly RecordedFrame[]): string {
+  const lines = ['afterBar,intent,status,filledQty,avgFillPrice,orderRef,text,time'];
+  for (const frame of frames) {
+    lines.push(
+      [
+        canonicalNumber(frame.afterBar),
+        canonicalNumber(frame.intent),
+        frame.status,
+        canonicalNumber(frame.filledQty),
+        cell(frame.avgFillPrice),
+        frame.orderRef ?? '',
+        frame.text ?? '',
+        cell(frame.time),
+      ].join(','),
+    );
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * One cell, through the one number writer.
+ *
+ * An absent field is `none` rather than empty, because an empty cell between two
+ * commas is indistinguishable from a file somebody's editor trimmed, and a
+ * language whose central idea is the absent value cannot be vague about it. A
+ * case is compared as text, so the number is written by the rule of
+ * `language.md` 5.5 and by the same function that writes every other number in
+ * the repository, never by a second spelling that agrees until it does not.
+ */
+function cell(value: number | null): string {
+  return value === null || !Number.isFinite(value) ? 'none' : canonicalNumber(value);
+}
+
+/** A text file ends with a newline, so appending to it never joins two lines. */
+function endsWithNewline(text: string): string {
+  return text.endsWith('\n') ? text : `${text}\n`;
+}

package/src/core/backtest/compare.ts

@@ -0,0 +1,246 @@
+/**
+ * Two runs, and whether the difference between them is a result.
+ *
+ * **Comparable first.** Two runs over different bars or a different contract are
+ * two studies, not a comparison, and a table of deltas between them is a way of
+ * being wrong with a decimal point. So the comparison says whether the pair is
+ * comparable before it says anything about the money, and names what differs.
+ *
+ * **And then separation, which is the figure the difference has to clear.** The
+ * gap between the two expectancies over the combined standard error is what
+ * turns "this one made more" into "this one made more than the noise". It is
+ * analytic: no resampling and no random number generator, so two runs of this
+ * comparison over the same pair give the same number for ever, and a decision
+ * taken on it is a decision anybody can reproduce.
+ */
+import type { Summary } from '../accounting/index.js';
+import { canonicalise } from '../emit/index.js';
+import type { RunRecord } from './record.js';
+
+/** What two runs came to, beside each other. */
+export interface RunComparison {
+  /** False when the bars hash or the contract differ. */
+  readonly comparable: boolean;
+  readonly differences: readonly {
+    readonly what: 'bars' | 'contract' | 'costs' | 'fill' | 'inputs' | 'program' | 'range';
+    readonly detail: string;
+  }[];
+  readonly deltas: readonly {
+    /** A field of Summary. */
+    readonly name: string;
+    readonly before: number;
+    readonly after: number;
+    readonly delta: number;
+  }[];
+  /** (expectancyB - expectancyA) / sqrt(seA^2 + seB^2). */
+  readonly separation: number | null;
+  /** Trades opening on the same bar with the same side in both. */
+  readonly sharedTrades: number;
+}
+
+/** One named difference between two runs' inputs. */
+type Difference = RunComparison['differences'][number];
+
+/**
+ * A Summary field worth a delta, in the order a comparison reports them.
+ *
+ * Written out rather than walked off the object, for two reasons. A key walk
+ * would report a delta for `currency`, which is a string, and for `capital`,
+ * which is an input rather than a result. And the order a comparison prints its
+ * rows in would then be the order a literal happens to be written in, which is
+ * a thing somebody reformats without knowing they changed an output.
+ */
+const COMPARED: readonly string[] = [
+  'netProfit',
+  'returnPercent',
+  'grossProfit',
+  'grossLoss',
+  'charges',
+  'tradeCount',
+  'openTradeCount',
+  'wins',
+  'losses',
+  'scratches',
+  'winRate',
+  'averageWin',
+  'averageLoss',
+  'expectancy',
+  'expectancyStandardError',
+  'profitFactor',
+  'maxDrawdown',
+  'maxDrawdownPercent',
+  'longestDrawdownBars',
+  'maxRunUp',
+  'maxRunUpPercent',
+  'averageBarsHeld',
+  'barsInMarket',
+  'barCount',
+];
+
+/**
+ * Two runs, side by side, and whether the gap between them is a result.
+ *
+ * **Comparable is about the inputs, not about the outputs.** Two runs over
+ * different bars, or on different contracts, are two studies: the money in one
+ * is not the money in the other, and subtracting them is arithmetic with no
+ * meaning behind it. A different program over the same bars is the opposite of
+ * that. It is the comparison somebody actually wants, so a differing program is
+ * reported as a difference and does not make the pair incomparable.
+ *
+ * **Every difference is named even when the pair is comparable**, because the
+ * reason a run improved is as often a setting somebody forgot they had changed
+ * as it is the change they meant to test. A comparison reporting only the money
+ * would let that through, and it would read as a result.
+ */
+export function compareRuns(before: RunRecord, after: RunRecord): RunComparison {
+  const differences = differencesBetween(before, after);
+  const blocking = differences.some((one) => one.what === 'bars' || one.what === 'contract');
+
+  return {
+    comparable: !blocking,
+    differences,
+    deltas: deltasBetween(before.report.summary, after.report.summary),
+    // Withheld rather than computed on an incomparable pair. A separation
+    // between two runs over different bars is a number, and it means nothing.
+    separation: blocking ? null : separationBetween(before.report.summary, after.report.summary),
+    sharedTrades: sharedTradesBetween(before.report.trades, after.report.trades),
+  };
+}
+
+/**
+ * What differs between two runs' inputs, in a fixed order.
+ *
+ * Compared through the repository's one canonical writer rather than field by
+ * field, so a settings shape that grows a field is compared on that field
+ * without this function being edited. Field by field is how a comparison
+ * quietly stops covering whatever was added to the settings last.
+ */
+function differencesBetween(before: RunRecord, after: RunRecord): readonly Difference[] {
+  const found: Difference[] = [];
+
+  if (before.bars.hash !== after.bars.hash) {
+    found.push({
+      what: 'bars',
+      detail: `different bars: ${before.bars.count} rows hashing ${before.bars.hash}, against ${after.bars.count} hashing ${after.bars.hash}`,
+    });
+  }
+  if (canonicalise(before.settings.contract) !== canonicalise(after.settings.contract)) {
+    found.push({ what: 'contract', detail: 'the two runs are on different contracts' });
+  }
+  if (before.programHash !== after.programHash) {
+    found.push({
+      what: 'program',
+      detail: `different program: ${before.programHash}, against ${after.programHash}`,
+    });
+  }
+  if (canonicalise(before.settings.range) !== canonicalise(after.settings.range)) {
+    found.push({ what: 'range', detail: 'the two runs cover different date ranges' });
+  }
+  if (canonicalise(before.settings.costs) !== canonicalise(after.settings.costs)) {
+    found.push({ what: 'costs', detail: 'the two runs were charged under different cost models' });
+  }
+  if (canonicalise(before.settings.fill) !== canonicalise(after.settings.fill)) {
+    found.push({ what: 'fill', detail: 'the two runs were filled under different policies' });
+  }
+  if (canonicalise(before.settings.inputs) !== canonicalise(after.settings.inputs)) {
+    found.push({ what: 'inputs', detail: 'the two scripts ran with different input values' });
+  }
+  return found;
+}
+
+/**
+ * Every compared figure, before and after.
+ *
+ * A summary carries null where a figure has no meaning: no win rate until a
+ * trade closes, no profit factor without a loss. Null on one side and a number
+ * on the other is a real thing to report, and a delta between them is not, so
+ * the row appears with both values and a delta of zero. Subtracting from null
+ * would invent a movement out of a figure that was never there.
+ */
+function deltasBetween(before: Summary, after: Summary): RunComparison['deltas'] {
+  // Widened once, here. COMPARED is a list of names and a summary is a closed
+  // shape, so the lookup is by string either way; doing it in one place keeps
+  // the rest of this file reading the real type.
+  const a0 = before as unknown as Readonly<Record<string, unknown>>;
+  const b0 = after as unknown as Readonly<Record<string, unknown>>;
+  const deltas: { name: string; before: number; after: number; delta: number }[] = [];
+  for (const name of COMPARED) {
+    const a = numberOf(a0[name]);
+    const b = numberOf(b0[name]);
+    // Neither side holds a figure: a field of no summary, which is nothing to
+    // report rather than a row of three zeroes.
+    if (a === null && b === null) continue;
+    deltas.push({
+      name,
+      before: a ?? 0,
+      after: b ?? 0,
+      delta: a === null || b === null ? 0 : (b ?? 0) - (a ?? 0),
+    });
+  }
+  return deltas;
+}
+
+/** A figure, or none where the summary carries null or a string for it. */
+function numberOf(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * How many standard errors apart the two expectancies are.
+ *
+ * Analytic, with no resampling and no random number generator, so two runs of
+ * this comparison over the same pair give the same figure for ever and a
+ * decision taken on it is one anybody can reproduce.
+ *
+ * **Null rather than a large number where there is no noise to measure.** A run
+ * with fewer than two closed trades has a standard error of zero, because one
+ * trade has no spread, and where both are zero the ratio divides by it.
+ * Returning infinity there would read as infinite confidence, which is the
+ * exact opposite of what one trade tells anybody. Null says the question cannot
+ * be answered from these two runs, which is the truth about them.
+ */
+function separationBetween(
+  before: { readonly expectancy: number; readonly expectancyStandardError: number },
+  after: { readonly expectancy: number; readonly expectancyStandardError: number },
+): number | null {
+  const noise = Math.sqrt(
+    before.expectancyStandardError * before.expectancyStandardError +
+      after.expectancyStandardError * after.expectancyStandardError,
+  );
+  if (!Number.isFinite(noise) || noise === 0) return null;
+  const gap = after.expectancy - before.expectancy;
+  return Number.isFinite(gap) ? gap / noise : null;
+}
+
+/**
+ * How many trades the two runs took alike.
+ *
+ * Alike means opened on the same bar on the same side, which is the coarsest
+ * thing two runs can agree about and the only one that survives a change to
+ * sizing or to costs. It is what says whether a change moved the money by
+ * trading differently or by trading the same and paying differently, and those
+ * are not the same result however alike the two totals look.
+ *
+ * Counted as a multiset, so two long trades opening on one bar in one run
+ * against one in the other share one trade rather than two.
+ */
+function sharedTradesBetween(
+  before: readonly { readonly openedOnBar: number; readonly side: string }[],
+  after: readonly { readonly openedOnBar: number; readonly side: string }[],
+): number {
+  const counts = new Map<string, number>();
+  for (const trade of before) {
+    const key = `${trade.openedOnBar}:${trade.side}`;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  let shared = 0;
+  for (const trade of after) {
+    const key = `${trade.openedOnBar}:${trade.side}`;
+    const left = counts.get(key) ?? 0;
+    if (left > 0) {
+      counts.set(key, left - 1);
+      shared += 1;
+    }
+  }
+  return shared;
+}