openalgo-script 0.1.0-alpha.1 → 0.4.0

package/src/core/accounting/trades.ts

@@ -0,0 +1,313 @@
+/**
+ * What a trade is, which is the definition every statistic is counted over.
+ *
+ * **A trade is one position reference, from the fill that first takes it away
+ * from zero to the fill that returns it to zero.** Nothing else is invented,
+ * because the engine already mints a reference per position, no order crosses
+ * zero, and every fill names the reference it settled however late it arrives.
+ *
+ * Everything awkward falls out of that rather than needing a rule of its own. A
+ * pyramided entry is more entry fills on one trade. A partial close is an exit
+ * fill that does not close the trade. A flip is two references and therefore
+ * two trades, which is what a reversing order already sends. A reference still
+ * holding something at the last bar is an open trade: it is in the list with
+ * `isOpen` true, it is counted in equity, and it is counted in no win rate.
+ *
+ * The definition is written in the specification before it is written here,
+ * because a rule decided in code is a rule two engines decide differently.
+ *
+ * ## What the fold reads, and what it refuses to work out for itself
+ *
+ * A fill carries the signed size of its reference either side of the
+ * settlement, so the fold reads what the position book did rather than
+ * recomputing it from quantities and sides. That is the whole of how a partial
+ * close, a pyramided entry and a reversal tell themselves apart: the move from
+ * one size to the other says how much of the fill closed what was held and how
+ * much of it opened something, and nothing else has to be inferred.
+ *
+ * It also settles the one case the definition does not cover on its face. A
+ * destination that fills more than the order asked takes a reference through
+ * zero rather than to it, and the position book reads the remainder as a
+ * position in the other direction opened at that fill's price. So the fold does
+ * the same: the fill closes the trade that was held and opens a second one on
+ * the same reference, at its own price and on its own bar. A trade that ran
+ * from a size to the other side of zero would report a quantity nothing was
+ * ever entered at.
+ *
+ * **Reducing a position does not move its average**, which is the position
+ * book's rule read here rather than a second one: a reducing fill adds to the
+ * exits and touches neither the entry quantity nor the entry cost. Every figure
+ * measured from the entry, the entry price a reader compares against and the
+ * excursion at each bar close, is measured from the price the units were
+ * actually bought at.
+ *
+ * **A charge lands whole on one trade and is never split.** It was rounded once
+ * for the fill that incurred it, and splitting it between the trade a crossing
+ * fill closed and the trade it opened would round it again and put a residue
+ * somewhere. So it is attributed to the trade the fill closed where it closed
+ * one, and to the trade it opened otherwise, which makes the charges of the
+ * trades add up to the charges of the fills exactly rather than nearly.
+ *
+ * **Gross profit is over the units that have left.** For a closed trade that is
+ * every unit it entered, which is the formula the report is specified with. For
+ * one still open it is what its exits have realised so far, which is a figure
+ * that is true rather than a zero standing in for money the run has already
+ * made.
+ */
+import type { BarMark, Contract, Money, RecordedFill } from './shapes.js';
+
+/** One round trip on one position reference. */
+export interface Trade {
+  /** 1-based, in the order the trade opened. */
+  readonly index: number;
+  readonly positionRef: number;
+  readonly side: 'long' | 'short';
+  readonly openedOnBar: number;
+  readonly openedAt: number | null;
+  readonly closedOnBar: number | null;
+  readonly closedAt: number | null;
+  readonly barsHeld: number | null;
+  /** Total units entered. */
+  readonly units: number;
+  /** Quantity weighted over the entry fills. */
+  readonly entryPrice: number;
+  /** Quantity weighted over the exit fills. */
+  readonly exitPrice: number | null;
+  readonly entries: number;
+  readonly exits: number;
+  readonly grossProfit: Money;
+  readonly charges: Money;
+  readonly netProfit: Money;
+  /**
+   * Excursion at bar closes while open. Favourable is zero or better, adverse
+   * zero or worse, and both are zero for a trade no bar closed on.
+   */
+  readonly maxFavourable: Money;
+  readonly maxAdverse: Money;
+  readonly isOpen: boolean;
+}
+
+/**
+ * The round trips a run's fills make up, in the order they opened.
+ *
+ * `charges[index]` is the money `fills[index]` was charged, rounded once by
+ * whoever computed it, so the two travel as one thing and nothing here rounds
+ * anything a second time. A caller with no cost model supplies no charges at
+ * all and every trade's charges are zero.
+ *
+ * The fills are read in `seq` order whatever order they are handed in, because
+ * `seq` is the order the engine folded them and a report that depended on the
+ * order a caller happened to be holding them in would not be reproducible. The
+ * marks are read in bar order for the same reason, and a bar is marked after
+ * every fill up to it has been folded, because a fill happens during its bar
+ * and the close comes after.
+ */
+export function tradesOf(
+  fills: readonly RecordedFill[],
+  charges: readonly Money[],
+  marks: readonly BarMark[],
+  contract: Contract,
+): readonly Trade[] {
+  const settled = inSeqOrder(fills, charges);
+  const built: Building[] = [];
+  const live: Building[] = [];
+
+  let next = 0;
+  for (const bar of inBarOrder(marks)) {
+    while (next < settled.length) {
+      const one = settled[next];
+      if (one === undefined || one.fill.barIndex > bar.barIndex) break;
+      fold(one, built, live);
+      next += 1;
+    }
+    // A bar with no close is not a price anything can be marked at. It marks
+    // nothing rather than marking zero, which would read as a total loss.
+    if (bar.close !== null) markTo(live, bar.close, contract.pointValue);
+  }
+  for (; next < settled.length; next += 1) {
+    const one = settled[next];
+    if (one !== undefined) fold(one, built, live);
+  }
+
+  return built.map((trade) => finish(trade, contract));
+}
+
+/** A fill and what it cost, kept together so neither can be reordered alone. */
+interface Settled {
+  readonly fill: RecordedFill;
+  readonly charge: Money;
+}
+
+/** A trade while it is still being folded: the totals a round trip is made of. */
+interface Building {
+  readonly index: number;
+  readonly positionRef: number;
+  readonly side: 'long' | 'short';
+  readonly openedOnBar: number;
+  readonly openedAt: number | null;
+  closedOnBar: number | null;
+  closedAt: number | null;
+  entryUnits: number;
+  entryCost: number;
+  exitUnits: number;
+  exitCost: number;
+  entries: number;
+  exits: number;
+  charges: Money;
+  /** Signed, and what the reference holds for this trade right now. */
+  size: number;
+  maxFavourable: Money;
+  maxAdverse: Money;
+}
+
+function inSeqOrder(
+  fills: readonly RecordedFill[],
+  charges: readonly Money[],
+): readonly Settled[] {
+  const paired = fills.map((fill, index) => ({ fill, charge: charges[index] ?? 0 }));
+  return paired.sort((a, b) => a.fill.seq - b.fill.seq);
+}
+
+function inBarOrder(marks: readonly BarMark[]): readonly BarMark[] {
+  return marks.slice().sort((a, b) => a.barIndex - b.barIndex);
+}
+
+/**
+ * How much of a move from one size to another closed what was held.
+ *
+ * Exported to the module and not through its door: `markers.ts` asks the same
+ * question of the same fills, and the rule for what a move closed and what it
+ * opened is one rule. Two folds may read a fill differently and produce a
+ * marker for an entry the trade list calls an exit, so they read it here.
+ *
+ * A move to the other side of zero closed all of it, which is the case a
+ * destination that overfilled produces and the one this has to get right.
+ */
+export function closedBy(before: number, after: number): number {
+  if (before === 0) return 0;
+  const same = Math.sign(after) === Math.sign(before);
+  return same ? Math.max(0, Math.abs(before) - Math.abs(after)) : Math.abs(before);
+}
+
+/** And how much of it opened something, which is the rest of the same move. */
+export function openedBy(before: number, after: number): number {
+  if (after === 0) return 0;
+  if (before === 0 || Math.sign(after) !== Math.sign(before)) return Math.abs(after);
+  return Math.max(0, Math.abs(after) - Math.abs(before));
+}
+
+/** One fill against the trades its reference holds. */
+function fold(one: Settled, built: Building[], live: Building[]): void {
+  const fill = one.fill;
+  const closing = closedBy(fill.refSizeBefore, fill.refSizeAfter);
+  const opening = openedBy(fill.refSizeBefore, fill.refSizeAfter);
+  const at = live.findIndex((trade) => trade.positionRef === fill.positionRef);
+  const held = at < 0 ? null : (live[at] ?? null);
+  let paid = false;
+
+  if (held !== null && closing > 0) {
+    held.exitUnits += closing;
+    held.exitCost += closing * fill.price;
+    held.exits += 1;
+    held.charges += one.charge;
+    paid = true;
+    // What the reference left this trade holding: nothing at all when the fill
+    // carried it through zero, since the other side of zero is the next trade.
+    held.size = opening > 0 ? 0 : fill.refSizeAfter;
+    if (held.size === 0) {
+      held.closedOnBar = fill.barIndex;
+      held.closedAt = fill.barTime;
+      live.splice(at, 1);
+    }
+  }
+
+  if (opening > 0) {
+    // A fill that closed something opens a trade of its own rather than adding
+    // to the one it just finished.
+    const adding = closing > 0 ? null : held;
+    if (adding === null) {
+      const fresh = begin(fill, opening, built.length + 1);
+      built.push(fresh);
+      live.push(fresh);
+      if (!paid) fresh.charges += one.charge;
+    } else {
+      adding.entryUnits += opening;
+      adding.entryCost += opening * fill.price;
+      adding.entries += 1;
+      adding.size = fill.refSizeAfter;
+      if (!paid) adding.charges += one.charge;
+    }
+    return;
+  }
+
+  // A fill that moved nothing still cost something, and it cost it on account
+  // of the trade its reference is holding.
+  if (!paid && held !== null) held.charges += one.charge;
+}
+
+function begin(fill: RecordedFill, units: number, index: number): Building {
+  return {
+    index,
+    positionRef: fill.positionRef,
+    side: fill.refSizeAfter > 0 ? 'long' : 'short',
+    openedOnBar: fill.barIndex,
+    openedAt: fill.barTime,
+    closedOnBar: null,
+    closedAt: null,
+    entryUnits: units,
+    entryCost: units * fill.price,
+    exitUnits: 0,
+    exitCost: 0,
+    entries: 1,
+    exits: 0,
+    charges: 0,
+    size: fill.refSizeAfter,
+    maxFavourable: 0,
+    maxAdverse: 0,
+  };
+}
+
+/** Every open trade against one bar's close. */
+function markTo(live: readonly Building[], close: number, pointValue: number): void {
+  for (const trade of live) {
+    const entry = averageOf(trade.entryCost, trade.entryUnits);
+    const excursion = (close - entry) * trade.size * pointValue;
+    if (excursion > trade.maxFavourable) trade.maxFavourable = excursion;
+    if (excursion < trade.maxAdverse) trade.maxAdverse = excursion;
+  }
+}
+
+function averageOf(cost: number, units: number): number {
+  return units === 0 ? 0 : cost / units;
+}
+
+function finish(trade: Building, contract: Contract): Trade {
+  const entryPrice = averageOf(trade.entryCost, trade.entryUnits);
+  const exitPrice = trade.exitUnits === 0 ? null : trade.exitCost / trade.exitUnits;
+  const way = trade.side === 'long' ? 1 : -1;
+  const gross =
+    exitPrice === null
+      ? 0
+      : (exitPrice - entryPrice) * trade.exitUnits * contract.pointValue * way;
+  return {
+    index: trade.index,
+    positionRef: trade.positionRef,
+    side: trade.side,
+    openedOnBar: trade.openedOnBar,
+    openedAt: trade.openedAt,
+    closedOnBar: trade.closedOnBar,
+    closedAt: trade.closedAt,
+    barsHeld: trade.closedOnBar === null ? null : trade.closedOnBar - trade.openedOnBar,
+    units: trade.entryUnits,
+    entryPrice,
+    exitPrice,
+    entries: trade.entries,
+    exits: trade.exits,
+    grossProfit: gross,
+    charges: trade.charges,
+    netProfit: gross - trade.charges,
+    maxFavourable: trade.maxFavourable,
+    maxAdverse: trade.maxAdverse,
+    isOpen: trade.closedOnBar === null,
+  };
+}

package/src/core/backtest/compare.ts

@@ -0,0 +1,244 @@
+/**
+ * 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',
+  '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;
+}

package/src/core/backtest/declaration.ts

@@ -0,0 +1,97 @@
+/**
+ * The declaration's own half of a run, read once and read here.
+ *
+ * **What the program states is stored once, as the program**, so none of these
+ * figures is a setting a host chooses and none of them travels in the record
+ * beside the settings. They are read back out of the compiled program every
+ * time a run is driven or replayed, which is what makes a replay of a stored
+ * record the same run rather than a run under today's defaults.
+ *
+ * Every field of `meta.strategy` is written into the program with the value it
+ * resolved to, defaults included (`compiled-program.md` 2.3), so nothing here
+ * carries a table of defaults and a default that changes in a later language
+ * version cannot silently change an old program. A field a script wrote with an
+ * `input()` is resolved against the run's own settings, by the engine, at load,
+ * and `fieldValue` reads what that resolution produced: the rule lives in the
+ * engine and is applied here rather than repeated.
+ *
+ * A study has no strategy declaration at all. It places no order and has no
+ * money, and it reads here as the absence it is rather than as a zero capital
+ * somebody would divide by.
+ */
+import type { CompiledProgram } from '../emit/index.js';
+import { fieldValue } from '../engine/index.js';
+import type { ResolvedInput, Value } from '../engine/index.js';
+
+/** The money and the fill the declaration fixed before bar 0. */
+export interface RunDeclaration {
+  /** False for a study, which declares none of this. */
+  readonly isStrategy: boolean;
+  readonly capital: number;
+  readonly currency: string;
+  /** Where a market order is priced, `language.md` 13.3. */
+  readonly fillOn: string;
+  readonly slippage: number;
+  readonly commission: number;
+  readonly commissionType: string;
+  /**
+   * The unit the declaration's quantity is stated in, `language.md` 13.3.
+   *
+   * Read here because the destination is the party that has to convert it, and
+   * a destination that cannot convert the unit a strategy sizes in has to
+   * refuse the run rather than fill a number in the wrong unit.
+   */
+  readonly qtyType: string;
+}
+
+/**
+ * What one program's declaration says about money, after its inputs.
+ *
+ * The inputs are the ones the engine resolved at load, handed back by `load`
+ * for this reader. A caller with none reads the literals, which is every
+ * program that did not write a declaration field with an `input()`.
+ */
+export function declarationOf(
+  program: CompiledProgram,
+  inputs: readonly ResolvedInput[] = [],
+): RunDeclaration {
+  const strategy = program.meta.strategy;
+  if (strategy === undefined) {
+    return {
+      isStrategy: false,
+      capital: 0,
+      currency: '',
+      fillOn: '',
+      slippage: 0,
+      commission: 0,
+      commissionType: '',
+      qtyType: '',
+    };
+  }
+  return {
+    isStrategy: true,
+    capital: numberOf(fieldValue(strategy.capital, inputs)),
+    currency: stringOf(fieldValue(strategy.currency, inputs)),
+    fillOn: stringOf(fieldValue(strategy.fillOn, inputs)),
+    slippage: numberOf(fieldValue(strategy.slippage, inputs)),
+    commission: numberOf(fieldValue(strategy.commission, inputs)),
+    commissionType: stringOf(fieldValue(strategy.commissionType, inputs)),
+    qtyType: stringOf(fieldValue(strategy.qtyType, inputs)),
+  };
+}
+
+/**
+ * A number the declaration states, or zero where it states something else.
+ *
+ * Zero rather than absence, and only here: every one of these fields is written
+ * into the program with a number, so anything else is a program this engine
+ * would already have refused at load. The fallback is what keeps this reader
+ * total rather than a second place a malformed program is diagnosed.
+ */
+function numberOf(value: Value): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+function stringOf(value: Value): string {
+  return typeof value === 'string' ? value : '';
+}