@tangle-network/agent-bench 0.3.7 → 0.4.0

package/src/quant-arena/backtest.test.mts

@@ -0,0 +1,135 @@
+import { describe, expect, it } from 'vitest'
+import { fillSchedule, runBacktest, statsForRange } from './backtest.ts'
+import type { Bar } from './types.ts'
+
+/** Flat-price bar helper. */
+const bar = (date: string, open: number, close = open): Bar => ({
+  date,
+  open,
+  high: Math.max(open, close),
+  low: Math.min(open, close),
+  close,
+  volume: 1000,
+})
+
+const dates = (n: number): string[] =>
+  Array.from({ length: n }, (_, i) => `2020-01-${String(i + 1).padStart(2, '0')}`)
+
+const flatSeries = (n: number, price: number): Bar[] => dates(n).map((d) => bar(d, price))
+
+const NO_COST = { costBps: 0, slippageBps: 0 }
+
+describe('runBacktest hand-computed toy cases', () => {
+  it('all-cash (no signals) stays at equity 1 with zero trades', () => {
+    const result = runBacktest([flatSeries(5, 100)], [], NO_COST)
+    expect(result.equity).toEqual([1, 1, 1, 1, 1])
+    expect(result.stats.tradeCount).toBe(0)
+    expect(result.stats.totalReturn).toBe(0)
+  })
+
+  it('full weight on a flat ticker loses exactly the round-trip-free fee', () => {
+    // 10bps cost + 5bps slippage on 1.0 traded dollars = 15bps once.
+    const result = runBacktest([flatSeries(5, 100)], [{ t: 0, weights: [1] }], { costBps: 10, slippageBps: 5 })
+    expect(result.stats.tradeCount).toBe(1)
+    expect(result.stats.totalReturn).toBeCloseTo(-0.0015, 12)
+    expect(result.equity[4]).toBeCloseTo(1 - 0.0015, 12)
+  })
+
+  it('captures a known move: buy at open, ride to close', () => {
+    // Day1: open 100 -> close 110 with full weight decided at day0 close.
+    const series = [bar('2020-01-01', 100), bar('2020-01-02', 100, 110), bar('2020-01-03', 110)]
+    const result = runBacktest([series], [{ t: 0, weights: [1] }], NO_COST)
+    expect(result.equity[1]).toBeCloseTo(1.1, 12)
+    expect(result.stats.totalReturn).toBeCloseTo(0.1, 12)
+  })
+
+  it('fills at the NEXT open, not the signal-day close (no free look-ahead)', () => {
+    // Price gaps 100 -> 200 overnight after the signal. A same-close fill would
+    // double money on the gap; a next-open fill must NOT.
+    const series = [bar('2020-01-01', 100, 100), bar('2020-01-02', 200, 200), bar('2020-01-03', 300, 300)]
+    const result = runBacktest([series], [{ t: 0, weights: [1] }], NO_COST)
+    // Bought at 200 (day2 open); close day2 = 200 -> equity 1; day3 300/200 = 1.5.
+    expect(result.equity[1]).toBeCloseTo(1, 12)
+    expect(result.equity[2]).toBeCloseTo(1.5, 12)
+  })
+
+  it('max drawdown on a crafted path: peak 1.2 -> trough 0.9 = 25%', () => {
+    const series = [
+      bar('2020-01-01', 100),
+      bar('2020-01-02', 100, 120),
+      bar('2020-01-03', 120, 90),
+      bar('2020-01-04', 90, 100),
+    ]
+    const result = runBacktest([series], [{ t: 0, weights: [1] }], NO_COST)
+    expect(result.equity).toEqual([1, 1.2, 0.9, 1.0].map((v) => expect.closeTo(v, 12) as unknown as number))
+    expect(result.stats.maxDrawdown).toBeCloseTo((1.2 - 0.9) / 1.2, 12)
+  })
+
+  it('splits weights across two tickers and holds cash for the rest', () => {
+    const a = [bar('2020-01-01', 100), bar('2020-01-02', 100, 110)]
+    const b = [bar('2020-01-01', 50), bar('2020-01-02', 50, 45)]
+    const result = runBacktest([a, b], [{ t: 0, weights: [0.5, 0.25] }], NO_COST)
+    // 0.5 * +10% + 0.25 * -10% + 0.25 cash = 1 + 0.05 - 0.025 = 1.025
+    expect(result.equity[1]).toBeCloseTo(1.025, 12)
+    expect(result.stats.tradeCount).toBe(2)
+  })
+
+  it('is deterministic: identical inputs give identical equity paths', () => {
+    const series = [flatSeries(30, 100).map((b, i) => bar(b.date, 100 + i, 101 + i))]
+    const signals = [
+      { t: 0, weights: [0.7] },
+      { t: 10, weights: [0.2] },
+      { t: 20, weights: [1] },
+    ]
+    const r1 = runBacktest(series as Bar[][], signals, { costBps: 10, slippageBps: 5 })
+    const r2 = runBacktest(series as Bar[][], signals, { costBps: 10, slippageBps: 5 })
+    expect(r1.equity).toEqual(r2.equity)
+    expect(r1.stats).toEqual(r2.stats)
+  })
+
+  it('rejects shorting, leverage, and misaligned universes (fail-closed)', () => {
+    const series = [flatSeries(3, 100)]
+    expect(() => runBacktest(series, [{ t: 0, weights: [-0.1] }], NO_COST)).toThrow(/no shorting/)
+    expect(() => runBacktest(series, [{ t: 0, weights: [1.2] }], NO_COST)).toThrow(/no leverage/)
+    expect(() => runBacktest([flatSeries(3, 100), flatSeries(4, 50)], [], NO_COST)).toThrow(/unaligned/)
+    expect(() => runBacktest(series, [{ t: 5, weights: [1] }], NO_COST)).toThrow(/outside/)
+  })
+
+  it('rebalances ONLY on emitted signals — positions drift in between', () => {
+    // One signal at t=0, then a price runup: the winning position is NOT
+    // trimmed back to its target weight on later days (no hidden churn).
+    const a = [bar('2020-01-01', 100), bar('2020-01-02', 100), bar('2020-01-03', 100, 200), bar('2020-01-04', 200)]
+    const result = runBacktest([a], [{ t: 0, weights: [0.5] }], NO_COST)
+    expect(result.stats.tradeCount).toBe(1)
+    // 0.5 in the ticker doubled -> equity 1.5, still only one fill ever.
+    expect(result.equity[3]).toBeCloseTo(1.5, 12)
+    const schedule = fillSchedule([{ t: 1, weights: [0.5] }], 1, 4)
+    expect(schedule.get(1)).toEqual([0.5])
+    expect(schedule.has(0)).toBe(false)
+  })
+})
+
+describe('statsForRange window slicing', () => {
+  it('scores only the window and carries positions in', () => {
+    // Flat first half, +10% single day in the second half.
+    const series = [
+      bar('2020-01-01', 100),
+      bar('2020-01-02', 100),
+      bar('2020-01-03', 100),
+      bar('2020-01-04', 100, 110),
+      bar('2020-01-05', 110),
+    ]
+    const result = runBacktest([series], [{ t: 0, weights: [1] }], NO_COST)
+    const firstHalf = statsForRange(result, 0, 3)
+    const secondHalf = statsForRange(result, 2, 5)
+    expect(firstHalf.totalReturn).toBeCloseTo(0, 12)
+    expect(secondHalf.totalReturn).toBeCloseTo(0.1, 12)
+    expect(secondHalf.days).toBe(3)
+  })
+
+  it('rejects degenerate ranges', () => {
+    const result = runBacktest([flatSeries(5, 100)], [], NO_COST)
+    expect(() => statsForRange(result, 3, 3)).toThrow(/bad range/)
+    expect(() => statsForRange(result, 0, 99)).toThrow(/bad range/)
+  })
+})

package/src/quant-arena/backtest.ts

@@ -0,0 +1,218 @@
+/**
+ * Daily-bar event-loop backtester. Zero dependencies beyond the Node stdlib
+ * (in fact: zero imports at all except the local types) so a reviewer can
+ * audit the whole execution model in one file.
+ *
+ * Execution model (conservative by construction):
+ *  - A signal decided at the close of day t is FILLED at the open of day t+1.
+ *    Nothing trades on the bar that produced the decision.
+ *  - Every rebalance pays `costBps + slippageBps` (basis points, one-way) on
+ *    the dollars traded, deducted from cash at the fill.
+ *  - No shorting, no leverage: weights >= 0, sum <= 1. Violations THROW —
+ *    a strategy that asks for leverage is a broken candidate, not a clamped one.
+ *  - Cash earns 0. A fully-invested target therefore carries a small negative
+ *    cash balance equal to accumulated fees (fees financed at 0% — this only
+ *    ever understates performance, never flatters it).
+ *
+ * Determinism: pure function of (bars, signals, config). No clock, no RNG.
+ */
+
+import type { Bar, Signal } from './types.ts'
+
+export interface BacktestConfig {
+  /** One-way transaction cost, basis points of traded dollars. */
+  costBps: number
+  /** One-way slippage, basis points of traded dollars. */
+  slippageBps: number
+}
+
+export const TRADING_DAYS_PER_YEAR = 252
+
+export interface RangeStats {
+  /** First/last day index of the scored range (inclusive start, exclusive end). */
+  start: number
+  end: number
+  days: number
+  totalReturn: number
+  maxDrawdown: number
+  /** Annualized Sharpe of daily returns (rf = 0). 0 when volatility is 0. */
+  sharpe: number
+  /** Fills with |trade| > 1e-9 × equity, summed over the range. */
+  tradeCount: number
+  /** Σ traded dollars / equity at each rebalance (two-sided turnover). */
+  turnover: number
+}
+
+export interface BacktestResult {
+  dates: string[]
+  /** Equity at each day's close; equity[0] = 1 (all cash at the first close). */
+  equity: number[]
+  /** dailyReturns[i] = equity[i+1] / equity[i] - 1. */
+  dailyReturns: number[]
+  /** Per-day fill count / turnover fraction (index = fill day). */
+  fillsByDay: number[]
+  turnoverByDay: number[]
+  stats: RangeStats
+}
+
+const WEIGHT_EPS = 1e-9
+
+export function assertAligned(bars: Bar[][]): void {
+  if (bars.length === 0) throw new Error('backtest: empty universe')
+  const T = bars[0]!.length
+  if (T < 2) throw new Error('backtest: need at least 2 days of bars')
+  for (let k = 1; k < bars.length; k++) {
+    if (bars[k]!.length !== T) {
+      throw new Error(`backtest: ticker ${k} has ${bars[k]!.length} bars, ticker 0 has ${T} — unaligned`)
+    }
+    for (let t = 0; t < T; t++) {
+      if (bars[k]![t]!.date !== bars[0]![t]!.date) {
+        throw new Error(`backtest: date mismatch at t=${t}: ${bars[k]![t]!.date} vs ${bars[0]![t]!.date}`)
+      }
+    }
+  }
+}
+
+/** Validate one signal against the contract. Throws on violation. */
+export function assertSignal(signal: Signal, tickers: number, totalDays: number): void {
+  if (!Number.isInteger(signal.t) || signal.t < 0 || signal.t >= totalDays) {
+    throw new Error(`backtest: signal.t=${signal.t} outside [0, ${totalDays})`)
+  }
+  if (signal.weights.length !== tickers) {
+    throw new Error(`backtest: signal at t=${signal.t} has ${signal.weights.length} weights, universe has ${tickers}`)
+  }
+  let sum = 0
+  for (const w of signal.weights) {
+    if (!Number.isFinite(w)) throw new Error(`backtest: non-finite weight at t=${signal.t}`)
+    if (w < -WEIGHT_EPS) throw new Error(`backtest: negative weight ${w} at t=${signal.t} — no shorting`)
+    sum += w
+  }
+  if (sum > 1 + 1e-6) throw new Error(`backtest: weights sum ${sum} > 1 at t=${signal.t} — no leverage`)
+}
+
+/** Map of decision day -> target weights. A rebalance is executed ONLY at the
+ *  open following an emitted signal; between signals, positions drift with
+ *  prices (no silent daily re-targeting, no hidden fee drag). */
+export function fillSchedule(signals: Signal[], tickers: number, totalDays: number): Map<number, number[]> {
+  const sorted = [...signals].sort((a, b) => a.t - b.t)
+  for (let i = 1; i < sorted.length; i++) {
+    if (sorted[i]!.t === sorted[i - 1]!.t) {
+      throw new Error(`backtest: two signals share t=${sorted[i]!.t} — a strategy emits at most one target per day`)
+    }
+  }
+  const schedule = new Map<number, number[]>()
+  for (const s of sorted) {
+    assertSignal(s, tickers, totalDays)
+    schedule.set(s.t, s.weights)
+  }
+  return schedule
+}
+
+export function runBacktest(bars: Bar[][], signals: Signal[], config: BacktestConfig): BacktestResult {
+  assertAligned(bars)
+  const N = bars.length
+  const T = bars[0]!.length
+  const fills = fillSchedule(signals, N, T)
+  const feeRate = (config.costBps + config.slippageBps) / 10_000
+
+  const equity: number[] = new Array(T).fill(0)
+  const fillsByDay: number[] = new Array(T).fill(0)
+  const turnoverByDay: number[] = new Array(T).fill(0)
+  let cash = 1
+  const pos: number[] = new Array(N).fill(0)
+  equity[0] = 1
+
+  for (let t = 1; t < T; t++) {
+    // Overnight: yesterday's close -> today's open.
+    for (let k = 0; k < N; k++) {
+      const prevClose = bars[k]![t - 1]!.close
+      if (prevClose <= 0) throw new Error(`backtest: nonpositive close for ticker ${k} at t=${t - 1}`)
+      pos[k] = pos[k]! * (bars[k]![t]!.open / prevClose)
+    }
+    // Fill the target decided at yesterday's close, at today's open.
+    const target = fills.get(t - 1)
+    if (target !== undefined) {
+      let equityOpen = cash
+      for (let k = 0; k < N; k++) equityOpen += pos[k]!
+      if (equityOpen <= 0) throw new Error(`backtest: equity wiped out at t=${t}`)
+      let traded = 0
+      let fills = 0
+      for (let k = 0; k < N; k++) {
+        const desired = target[k]! * equityOpen
+        const delta = desired - pos[k]!
+        traded += Math.abs(delta)
+        if (Math.abs(delta) > WEIGHT_EPS * equityOpen) fills++
+        cash -= delta
+        pos[k] = desired
+      }
+      const fee = traded * feeRate
+      cash -= fee
+      fillsByDay[t] = fills
+      turnoverByDay[t] = traded / equityOpen
+    }
+    // Intraday: today's open -> today's close.
+    for (let k = 0; k < N; k++) {
+      const open = bars[k]![t]!.open
+      if (open <= 0) throw new Error(`backtest: nonpositive open for ticker ${k} at t=${t}`)
+      pos[k] = pos[k]! * (bars[k]![t]!.close / open)
+    }
+    let eq = cash
+    for (let k = 0; k < N; k++) eq += pos[k]!
+    equity[t] = eq
+  }
+
+  const dailyReturns: number[] = new Array(T - 1)
+  for (let i = 0; i < T - 1; i++) dailyReturns[i] = equity[i + 1]! / equity[i]! - 1
+
+  const result: BacktestResult = {
+    dates: bars[0]!.map((b) => b.date),
+    equity,
+    dailyReturns,
+    fillsByDay,
+    turnoverByDay,
+    stats: undefined as unknown as RangeStats,
+  }
+  result.stats = statsForRange(result, 0, T)
+  return result
+}
+
+/** Score a sub-range [start, end) of an existing backtest — the walk-forward
+ *  window view. Positions carried into the window count; nothing after `end`
+ *  leaks in. */
+export function statsForRange(result: BacktestResult, start: number, end: number): RangeStats {
+  const T = result.equity.length
+  if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end > T || end - start < 2) {
+    throw new Error(`statsForRange: bad range [${start}, ${end}) over ${T} days`)
+  }
+  const eq = result.equity.slice(start, end)
+  const totalReturn = eq[eq.length - 1]! / eq[0]! - 1
+  let peak = eq[0]!
+  let maxDrawdown = 0
+  for (const e of eq) {
+    if (e > peak) peak = e
+    const dd = (peak - e) / peak
+    if (dd > maxDrawdown) maxDrawdown = dd
+  }
+  const returns = result.dailyReturns.slice(start, end - 1)
+  const n = returns.length
+  const mean = returns.reduce((s, r) => s + r, 0) / n
+  const variance = n > 1 ? returns.reduce((s, r) => s + (r - mean) ** 2, 0) / (n - 1) : 0
+  const std = Math.sqrt(variance)
+  const sharpe = std > 0 ? (mean / std) * Math.sqrt(TRADING_DAYS_PER_YEAR) : 0
+  let tradeCount = 0
+  let turnover = 0
+  for (let t = start + 1; t < end; t++) {
+    tradeCount += result.fillsByDay[t]!
+    turnover += result.turnoverByDay[t]!
+  }
+  return {
+    start,
+    end,
+    days: end - start,
+    totalReturn,
+    maxDrawdown,
+    sharpe,
+    tradeCount,
+    turnover,
+  }
+}

package/src/quant-arena/data.test.mts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest'
+import { readdir } from 'node:fs/promises'
+import {
+  HOLDOUT_DIR,
+  HOLDOUT_START,
+  IN_SAMPLE_DIR,
+  INDEX_TICKER,
+  loadInSample,
+  parseStooqCsv,
+} from './data.ts'
+
+describe('parseStooqCsv', () => {
+  it('parses the vendored CSV format', () => {
+    const bars = parseStooqCsv('Date,Open,High,Low,Close,Volume\n2020-01-02,10,11,9,10.5,12345\n2020-01-03,10.5,12,10,11,999\n', 'test')
+    expect(bars).toHaveLength(2)
+    expect(bars[0]).toEqual({ date: '2020-01-02', open: 10, high: 11, low: 9, close: 10.5, volume: 12345 })
+  })
+
+  it('fails loud on descending dates, bad prices, and foreign headers', () => {
+    expect(() => parseStooqCsv('Date,Open,High,Low,Close,Volume\n2020-01-03,10,11,9,10,1\n2020-01-02,10,11,9,10,1\n', 't')).toThrow(/ascending/)
+    expect(() => parseStooqCsv('Date,Open,High,Low,Close,Volume\n2020-01-02,0,11,9,10,1\n', 't')).toThrow(/nonpositive/)
+    expect(() => parseStooqCsv('Ticker,Per,Date\nX,D,2020\n', 't')).toThrow(/header/)
+  })
+})
+
+describe('vendored fixture integrity (in-sample side only — the holdout is not read here)', () => {
+  it('in-sample and holdout are physically separate directories with the same tickers', async () => {
+    const inFiles = (await readdir(IN_SAMPLE_DIR)).filter((f) => f.endsWith('.csv')).sort()
+    const outFiles = (await readdir(HOLDOUT_DIR)).filter((f) => f.endsWith('.csv')).sort()
+    expect(inFiles).toEqual(outFiles)
+    expect(inFiles).toContain(`${INDEX_TICKER}.csv`)
+    expect(inFiles.length).toBe(11)
+  })
+
+  it('loadInSample aligns the universe, leads with the index, and never crosses into the holdout era', async () => {
+    const aligned = await loadInSample()
+    expect(aligned.tickers[0]).toBe(INDEX_TICKER)
+    expect(aligned.tickers).toHaveLength(11)
+    expect(aligned.bars).toHaveLength(11)
+    for (const series of aligned.bars) expect(series).toHaveLength(aligned.dates.length)
+    expect(aligned.dates.length).toBeGreaterThan(1800)
+    expect(aligned.dates[aligned.dates.length - 1]! < HOLDOUT_START).toBe(true)
+  })
+})

package/src/quant-arena/data.ts

@@ -0,0 +1,141 @@
+/**
+ * Vendored daily-bar data: Stooq-format CSVs (Date,Open,High,Low,Close,Volume)
+ * committed under fixtures/data/. Two physically separate directories:
+ *
+ *   fixtures/data/insample/  — everything the campaign loop may read.
+ *   fixtures/data/holdout/   — the FINAL 2 years. Loaded ONLY by the
+ *                              certification path (holdout-certify.mts).
+ *                              quant-loop.mts never imports `loadHoldout`.
+ *
+ * See fixtures/data/PROVENANCE.md for where the series come from.
+ */
+
+import { readdir, readFile } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Bar } from './types.ts'
+
+export const DATA_DIR = fileURLToPath(new URL('./fixtures/data', import.meta.url))
+export const IN_SAMPLE_DIR = join(DATA_DIR, 'insample')
+export const HOLDOUT_DIR = join(DATA_DIR, 'holdout')
+/** First holdout date — insample bars must all be strictly before this. */
+export const HOLDOUT_START = '2024-07-01'
+/** The benchmark index ticker; always bars[0] in the aligned universe. */
+export const INDEX_TICKER = 'IDX'
+
+export interface AlignedBars {
+  /** tickers[0] === INDEX_TICKER; the rest sorted alphabetically. */
+  tickers: string[]
+  dates: string[]
+  /** bars[k] belongs to tickers[k]; every series shares the date axis. */
+  bars: Bar[][]
+}
+
+export function parseStooqCsv(text: string, source: string): Bar[] {
+  const lines = text.split('\n').map((l) => l.trim()).filter((l) => l.length > 0)
+  if (lines.length < 2) throw new Error(`${source}: empty CSV`)
+  const header = lines[0]!.toLowerCase()
+  if (!header.startsWith('date,open,high,low,close')) {
+    throw new Error(`${source}: unexpected header '${lines[0]}'`)
+  }
+  const bars: Bar[] = []
+  for (const line of lines.slice(1)) {
+    const cells = line.split(',')
+    if (cells.length < 5) throw new Error(`${source}: bad row '${line}'`)
+    const [date, open, high, low, close, volume] = cells
+    const bar: Bar = {
+      date: date!,
+      open: Number(open),
+      high: Number(high),
+      low: Number(low),
+      close: Number(close),
+      volume: volume !== undefined ? Number(volume) : 0,
+    }
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(bar.date)) throw new Error(`${source}: bad date '${bar.date}'`)
+    for (const v of [bar.open, bar.high, bar.low, bar.close]) {
+      if (!Number.isFinite(v) || v <= 0) throw new Error(`${source}: nonpositive price on ${bar.date}`)
+    }
+    bars.push(bar)
+  }
+  for (let i = 1; i < bars.length; i++) {
+    if (bars[i]!.date <= bars[i - 1]!.date) {
+      throw new Error(`${source}: dates not strictly ascending at ${bars[i]!.date}`)
+    }
+  }
+  return bars
+}
+
+/** Load every `<TICKER>.csv` in a directory and align on the intersection of
+ *  dates. The index ticker leads; the rest follow alphabetically. */
+export async function loadBarsDir(dir: string): Promise<AlignedBars> {
+  const files = (await readdir(dir)).filter((f) => f.endsWith('.csv')).sort()
+  if (files.length === 0) throw new Error(`loadBarsDir: no CSVs in ${dir}`)
+  const byTicker = new Map<string, Bar[]>()
+  for (const file of files) {
+    const ticker = basename(file, '.csv')
+    byTicker.set(ticker, parseStooqCsv(await readFile(join(dir, file), 'utf8'), join(dir, file)))
+  }
+  if (!byTicker.has(INDEX_TICKER)) {
+    throw new Error(`loadBarsDir: ${dir} has no ${INDEX_TICKER}.csv — the universe needs its benchmark index`)
+  }
+  const tickers = [INDEX_TICKER, ...[...byTicker.keys()].filter((t) => t !== INDEX_TICKER).sort()]
+  let shared: Set<string> | null = null
+  for (const ticker of tickers) {
+    const tickerDates = new Set(byTicker.get(ticker)!.map((b) => b.date))
+    if (shared === null) {
+      shared = tickerDates
+    } else {
+      const carried: Set<string> = shared
+      shared = new Set([...carried].filter((d) => tickerDates.has(d)))
+    }
+  }
+  const dates = [...shared!].sort()
+  if (dates.length < 2) throw new Error(`loadBarsDir: fewer than 2 shared dates across ${dir}`)
+  const bars = tickers.map((ticker) => {
+    const wanted = new Set(dates)
+    return byTicker.get(ticker)!.filter((b) => wanted.has(b.date))
+  })
+  return { tickers, dates, bars }
+}
+
+/** The campaign loop's data. Fails loud if any bar strays into the holdout era. */
+export async function loadInSample(): Promise<AlignedBars> {
+  const aligned = await loadBarsDir(IN_SAMPLE_DIR)
+  const last = aligned.dates[aligned.dates.length - 1]!
+  if (last >= HOLDOUT_START) {
+    throw new Error(`loadInSample: in-sample data reaches ${last}, at/past the holdout start ${HOLDOUT_START}`)
+  }
+  return aligned
+}
+
+/** CERTIFICATION PATH ONLY (holdout-certify.mts). The final 2 years. */
+export async function loadHoldout(): Promise<AlignedBars> {
+  const aligned = await loadBarsDir(HOLDOUT_DIR)
+  const first = aligned.dates[0]!
+  if (first < HOLDOUT_START) {
+    throw new Error(`loadHoldout: holdout data starts ${first}, before the holdout start ${HOLDOUT_START}`)
+  }
+  return aligned
+}
+
+/** In-sample followed by holdout on one axis — what the certification run
+ *  backtests so lookback indicators are warm when the holdout period begins.
+ *  Returns the concatenated universe plus the index of the first holdout day. */
+export function concatForCertification(insample: AlignedBars, holdout: AlignedBars): { aligned: AlignedBars; holdoutStartIndex: number } {
+  if (insample.tickers.join(',') !== holdout.tickers.join(',')) {
+    throw new Error('concatForCertification: in-sample and holdout universes differ')
+  }
+  const lastIn = insample.dates[insample.dates.length - 1]!
+  const firstOut = holdout.dates[0]!
+  if (firstOut <= lastIn) {
+    throw new Error(`concatForCertification: holdout starts ${firstOut}, not after in-sample end ${lastIn}`)
+  }
+  return {
+    aligned: {
+      tickers: insample.tickers,
+      dates: [...insample.dates, ...holdout.dates],
+      bars: insample.bars.map((series, k) => [...series, ...holdout.bars[k]!]),
+    },
+    holdoutStartIndex: insample.dates.length,
+  }
+}