@tangle-network/agent-bench 0.3.6 → 0.3.8

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,
+  }
+}

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

@@ -0,0 +1,253 @@
+import { describe, expect, it } from 'vitest'
+import { runBacktest } from './backtest.ts'
+import { generateSignalsFromStrategy, runIncremental, strategyFromGenerateSignals } from './driver.ts'
+import { truncationInvariance } from './leak-audit.ts'
+import { rebalance, targetsToWeights } from './oms.ts'
+import { generateSignals as buyHold } from './strategies/buy-hold-index/strategy.ts'
+import { generateSignals as equalWeight } from './strategies/equal-weight/strategy.ts'
+import { generateSignals as smaCrossover } from './strategies/sma-crossover/strategy.ts'
+import type { Bar, Signal, Strategy, StrategyContext } from './types.ts'
+
+/** Deterministic wiggly price path (no RNG — reproducible). */
+function syntheticBars(n: number, tickers: number): Bar[][] {
+  return Array.from({ length: tickers }, (_, k) =>
+    Array.from({ length: n }, (_, t) => {
+      const close = 100 + 10 * Math.sin(t / 7 + k) + 0.05 * t
+      const open = 100 + 10 * Math.sin((t - 0.5) / 7 + k) + 0.05 * t
+      return {
+        date: `d${String(t).padStart(4, '0')}`,
+        open,
+        high: Math.max(open, close) + 1,
+        low: Math.min(open, close) - 1,
+        close,
+        volume: 1000,
+      }
+    }),
+  )
+}
+
+const symbolsFor = (bars: Bar[][]): string[] => bars.map((_, k) => (k === 0 ? 'IDX' : `T${k}`))
+const config = (bars: Bar[][]) => ({ costBps: 10, slippageBps: 5, symbols: symbolsFor(bars) })
+
+describe('runIncremental — structural history visibility', () => {
+  const bars = syntheticBars(120, 3)
+
+  it('every onBar call sees exactly bars[0..t] and nothing beyond', () => {
+    let calls = 0
+    const spy: Strategy = {
+      onBar(ctx: StrategyContext) {
+        calls++
+        for (let k = 0; k < ctx.history.length; k++) {
+          expect(ctx.history[k]!.length).toBe(ctx.t + 1)
+          // The future is ABSENT, not merely guarded.
+          expect(ctx.history[k]![ctx.t + 1]).toBeUndefined()
+          expect(ctx.history[k]![ctx.t]!.date).toBe(bars[k]![ctx.t]!.date)
+        }
+        return null
+      },
+    }
+    runIncremental(bars, spy, config(bars))
+    expect(calls).toBe(120)
+  })
+
+  it('driver equity path is bit-identical to runBacktest on the collected decisions', () => {
+    const strategy = strategyFromGenerateSignals(smaCrossover)
+    const run = runIncremental(bars, strategy, config(bars))
+    const reference = runBacktest(bars, run.decisions, { costBps: 10, slippageBps: 5 })
+    expect(run.equityByDay.length).toBe(reference.equity.length)
+    for (let t = 0; t < run.equityByDay.length; t++) {
+      expect(run.equityByDay[t]).toBe(reference.equity[t])
+    }
+  })
+
+  it('ctx.weights and ctx.equity reflect the drifted portfolio', () => {
+    const seen: Array<{ t: number; equity: number; weightSum: number }> = []
+    const holdIndex: Strategy = {
+      onBar(ctx) {
+        seen.push({ t: ctx.t, equity: ctx.equity, weightSum: ctx.weights.reduce((s, w) => s + w, 0) })
+        return ctx.t === 0 ? [{ symbol: 'IDX', weight: 1 }] : null
+      },
+    }
+    const run = runIncremental(bars, holdIndex, config(bars))
+    expect(seen[0]!.equity).toBe(1)
+    expect(seen[0]!.weightSum).toBe(0) // all cash before the first fill
+    // After the t=0 decision fills at t=1's open, the book is ~fully invested.
+    expect(seen[1]!.weightSum).toBeGreaterThan(0.99)
+    expect(run.decisions).toEqual([{ t: 0, weights: [1, 0, 0] }])
+  })
+
+  it('a decision on the final bar is recorded but produces no fill', () => {
+    const lastBarOnly: Strategy = {
+      onBar(ctx) {
+        return ctx.t === bars[0]!.length - 1 ? [{ symbol: 'IDX', weight: 1 }] : null
+      },
+    }
+    const run = runIncremental(bars, lastBarOnly, config(bars))
+    expect(run.decisions.length).toBe(1)
+    expect(run.equityByDay.every((e) => e === 1)).toBe(true) // never traded
+  })
+
+  it('fail-closed on contract violations from onBar', () => {
+    const short: Strategy = { onBar: () => [{ symbol: 'IDX', weight: -0.2 }] }
+    expect(() => runIncremental(bars, short, config(bars))).toThrow(/long-only|negative/)
+    const levered: Strategy = {
+      onBar: () => [
+        { symbol: 'IDX', weight: 0.8 },
+        { symbol: 'T1', weight: 0.5 },
+      ],
+    }
+    expect(() => runIncremental(bars, levered, config(bars))).toThrow(/sum.*> 1/)
+    const unknown: Strategy = { onBar: () => [{ symbol: 'NOPE', weight: 0.5 }] }
+    expect(() => runIncremental(bars, unknown, config(bars))).toThrow(/unknown symbol/)
+  })
+})
+
+describe('batch-compat shim — the 3 pinned baselines run unchanged', () => {
+  const bars = syntheticBars(400, 4)
+
+  for (const [name, generateSignals] of [
+    ['buy-hold-index', buyHold],
+    ['equal-weight', equalWeight],
+    ['sma-crossover', smaCrossover],
+  ] as const) {
+    it(`${name}: incremental drive reproduces the batch signals exactly`, () => {
+      const batch = generateSignals(bars)
+      const incremental = generateSignalsFromStrategy(strategyFromGenerateSignals(generateSignals))(bars)
+      expect(incremental).toEqual(batch)
+    })
+  }
+})
+
+describe('leak audit under the v2 harness', () => {
+  const bars = syntheticBars(400, 3)
+
+  /** Deliberately leaky: sizes today's weight by TOMORROW's return (same
+   *  fixture class as leak-audit.test.mts, which keeps guarding the v1 path). */
+  const peekAhead = (input: Bar[][]): Signal[] => {
+    const T = input[0]!.length
+    const signals: Signal[] = []
+    for (let t = 0; t < T - 1; t++) {
+      const up = input[0]![t + 1]!.close > input[0]![t]!.close
+      signals.push({ t, weights: input.map((_, k) => (k === 0 && up ? 1 : 0)) })
+    }
+    return signals
+  }
+
+  /** Leaky via whole-series statistics over the FULL sample. */
+  const fullSampleMax = (input: Bar[][]): Signal[] => {
+    const maxClose = Math.max(...input[0]!.map((b) => b.close))
+    const T = input[0]!.length
+    const signals: Signal[] = []
+    for (let t = 0; t < T; t++) {
+      signals.push({ t, weights: input.map((_, k) => (k === 0 ? input[0]![t]!.close / maxClose : 0)) })
+    }
+    return signals
+  }
+
+  it('v1 truncation audit still catches both leaky strategies as written', () => {
+    expect(truncationInvariance(peekAhead, bars, { warmupDays: 50 }).clean).toBe(false)
+    expect(truncationInvariance(fullSampleMax, bars, { warmupDays: 50 }).clean).toBe(false)
+  })
+
+  it('the incremental harness neutralizes the batch peek-ahead (its signal can never fire)', () => {
+    // Under the driver the shim hands the strategy TRUNCATED history: the
+    // peek-ahead can only emit a signal for day t once it has seen t+1, so
+    // "today's" signal never exists at decision time — zero trades, leak
+    // structurally neutralized (and still caught as written by the v1 audit).
+    const run = runIncremental(bars, strategyFromGenerateSignals(peekAhead), config(bars))
+    expect(run.decisions).toEqual([])
+    expect(run.orders).toEqual([])
+  })
+
+  it('a v2-native strategy reaching past today crashes on absent data — fail-closed', () => {
+    const v2Peeker: Strategy = {
+      onBar(ctx) {
+        // ctx.history physically ends at today; tomorrow is undefined.
+        const up = ctx.history[0]![ctx.t + 1]!.close > ctx.history[0]![ctx.t]!.close
+        return up ? [{ symbol: 'IDX', weight: 1 }] : null
+      },
+    }
+    expect(() => runIncremental(bars, v2Peeker, config(bars))).toThrow()
+  })
+
+  it('the incremental harness defuses whole-series leaks into causal decisions', () => {
+    // Driven bar-by-bar, "max over the whole series" becomes "max up to
+    // today": different decisions than the batch run, but causal — the
+    // truncation audit on the DRIVEN strategy is clean by construction.
+    const driven = generateSignalsFromStrategy(strategyFromGenerateSignals(fullSampleMax))
+    expect(truncationInvariance(driven, bars, { warmupDays: 50 }).clean).toBe(true)
+    expect(driven(bars)).not.toEqual(fullSampleMax(bars))
+  })
+})
+
+describe('oms — the shared rebalancer', () => {
+  it('targetsToWeights expands sparse targets and enforces the contract', () => {
+    const symbols = ['IDX', 'A', 'B']
+    expect(targetsToWeights([{ symbol: 'A', weight: 0.6 }], symbols)).toEqual([0, 0.6, 0])
+    expect(() => targetsToWeights([{ symbol: 'A', weight: 0.6 }, { symbol: 'A', weight: 0.1 }], symbols)).toThrow(
+      /twice/,
+    )
+    expect(() => targetsToWeights([{ symbol: 'A', weight: Number.NaN }], symbols)).toThrow(/non-finite/)
+  })
+
+  it('sizes orders LEAN-style: qty = (targetWeight * equity - positionValue) / price', () => {
+    const orders = rebalance({
+      targets: [
+        { symbol: 'A', weight: 0.5 },
+        { symbol: 'B', weight: 0 },
+      ],
+      symbols: ['IDX', 'A', 'B'],
+      equity: 2,
+      prices: [100, 50, 20],
+      positionValues: [0, 0.5, 0.5],
+      t: 42,
+      tag: 'cand-x',
+    })
+    expect(orders).toEqual([
+      // buy A: (0.5 * 2 - 0.5) / 50 = 0.01 shares
+      { clientOrderId: 'qa-t42-A', symbol: 'A', side: 'buy', qty: 0.01, type: 'market', tif: 'day', tag: 'cand-x' },
+      // sell B to flat: 0.5 / 20 = 0.025 shares
+      { clientOrderId: 'qa-t42-B', symbol: 'B', side: 'sell', qty: 0.025, type: 'market', tif: 'day', tag: 'cand-x' },
+    ])
+  })
+
+  it('suppresses dust and emits nothing on a no-op rebalance', () => {
+    const orders = rebalance({
+      targets: [{ symbol: 'A', weight: 0.5 }],
+      symbols: ['IDX', 'A'],
+      equity: 1,
+      prices: [100, 50],
+      positionValues: [0, 0.5],
+      t: 7,
+    })
+    expect(orders).toEqual([])
+  })
+
+  it('order ids are deterministic per (t, symbol)', () => {
+    const make = () =>
+      rebalance({
+        targets: [{ symbol: 'A', weight: 0.3 }],
+        symbols: ['IDX', 'A'],
+        equity: 1,
+        prices: [100, 50],
+        positionValues: [0, 0],
+        t: 9,
+      })
+    expect(make()).toEqual(make())
+    expect(make()[0]!.clientOrderId).toBe('qa-t9-A')
+  })
+
+  it('strategies cannot smuggle orders: only weights cross the seam', () => {
+    // The driver hands onBar's return value to targetsToWeights, which
+    // rejects anything that is not {symbol, weight} rows summing sanely.
+    const bars = syntheticBars(30, 2)
+    const smuggler = {
+      onBar: () => [{ symbol: 'IDX', weight: 0.5, side: 'buy', qty: 999 }],
+    } as unknown as Strategy
+    // Extra fields are ignored — the OMS reads ONLY symbol + weight; the
+    // emitted order comes out of the shared sizing rule, not the strategy.
+    const run = runIncremental(bars, smuggler, { costBps: 10, slippageBps: 5, symbols: ['IDX', 'T1'] })
+    expect(run.orders.every((o) => o.qty < 1)).toBe(true)
+    expect(run.orders[0]!.clientOrderId).toMatch(/^qa-t0-IDX$/)
+  })
+})

package/src/quant-arena/driver.ts

@@ -0,0 +1,219 @@
+/**
+ * Incremental strategy driver — the v2 harness. Feeds a `Strategy` one bar
+ * at a time and enforces history visibility STRUCTURALLY: before every
+ * `onBar(ctx)` call the bar arrays are physically sliced to `[0..t]`, so
+ * data after the decision day does not exist in anything the strategy can
+ * reach. (A Proxy that throws on out-of-range reads was the alternative;
+ * slicing was chosen because it is simpler, allocation-cheap at this scale
+ * — slices copy references, not bars — and gives the harder guarantee:
+ * future bars are ABSENT, not merely guarded. The truncation leak audit
+ * stays in place on top of this as defense in depth, and because the v1
+ * batch contract can still leak.)
+ *
+ * Portfolio state shown to the strategy (ctx.weights / ctx.equity) evolves
+ * under EXACTLY the engine's execution model (see backtest.ts): a decision
+ * at the close of day t fills at day t+1's open, fees in bps of traded
+ * dollars, positions drift in between. `driver.test.mts` asserts the
+ * driver's equity path is bit-identical to `runBacktest` on the collected
+ * decisions.
+ *
+ * Outputs per run:
+ *  - `decisions` — the decision record [(t, weights)], one row per rebalance;
+ *    this is what the scorers (vectorbt worker, TS prefilter) consume.
+ *  - `orders` — the OMS order stream produced by the SHARED rebalancer
+ *    (oms.ts) from those decisions. Strategies never emit orders.
+ *  - `equityByDay` — the driver's own equity path (close-marked).
+ */
+
+import { pathToFileURL } from 'node:url'
+import { assertAligned } from './backtest.ts'
+import { rebalance, targetsToWeights } from './oms.ts'
+import type { Bar, GenerateSignals, Order, Signal, Strategy, StrategyContext, TargetPosition } from './types.ts'
+
+export interface DriverConfig {
+  /** One-way transaction cost, basis points of traded dollars. */
+  costBps: number
+  /** One-way slippage, basis points of traded dollars. */
+  slippageBps: number
+  /** Universe tickers; symbols[0] is the index. Length must match bars. */
+  symbols: string[]
+  /** Provenance tag stamped on every order (e.g. the candidate id). */
+  tag?: string
+}
+
+export interface DriverRun {
+  /** The decision record: one Signal per rebalance, in day order. */
+  decisions: Signal[]
+  /** OMS orders from the shared rebalancer, in emission order. */
+  orders: Order[]
+  /** Equity at each day's close under the engine's execution model. */
+  equityByDay: number[]
+}
+
+export function runIncremental(bars: Bar[][], strategy: Strategy, config: DriverConfig): DriverRun {
+  assertAligned(bars)
+  const N = bars.length
+  if (config.symbols.length !== N) {
+    throw new Error(`driver: ${config.symbols.length} symbols for ${N} bar series`)
+  }
+  if (typeof strategy?.onBar !== 'function') {
+    throw new Error('driver: strategy does not implement onBar(ctx)')
+  }
+  const T = bars[0]!.length
+  const feeRate = (config.costBps + config.slippageBps) / 10_000
+
+  const decisions: Signal[] = []
+  const orders: Order[] = []
+  const equityByDay: number[] = new Array(T).fill(0)
+  let cash = 1
+  const pos: number[] = new Array(N).fill(0)
+  /** Weights of the decision made at day t-1, pending its fill at t's open. */
+  let pendingFill: number[] | null = null
+
+  for (let t = 0; t < T; t++) {
+    if (t > 0) {
+      // Overnight: yesterday's close -> today's open (same as backtest.ts).
+      for (let k = 0; k < N; k++) {
+        pos[k] = pos[k]! * (bars[k]![t]!.open / bars[k]![t - 1]!.close)
+      }
+      if (pendingFill !== null) {
+        let equityOpen = cash
+        for (let k = 0; k < N; k++) equityOpen += pos[k]!
+        if (equityOpen <= 0) throw new Error(`driver: equity wiped out at t=${t}`)
+        let traded = 0
+        for (let k = 0; k < N; k++) {
+          const desired = pendingFill[k]! * equityOpen
+          const delta = desired - pos[k]!
+          traded += Math.abs(delta)
+          cash -= delta
+          pos[k] = desired
+        }
+        cash -= traded * feeRate
+        pendingFill = null
+      }
+      // Intraday: today's open -> today's close.
+      for (let k = 0; k < N; k++) {
+        pos[k] = pos[k]! * (bars[k]![t]!.close / bars[k]![t]!.open)
+      }
+    }
+    let equity = cash
+    for (let k = 0; k < N; k++) equity += pos[k]!
+    equityByDay[t] = equity
+
+    // Decision time: the close of day t. History is physically truncated.
+    const ctx: StrategyContext = {
+      symbols: config.symbols,
+      t,
+      history: bars.map((series) => series.slice(0, t + 1)),
+      weights: pos.map((p) => (equity > 0 ? p / equity : 0)),
+      equity,
+    }
+    const targets = strategy.onBar(ctx)
+    if (targets === null || targets === undefined) continue
+    if (!Array.isArray(targets)) {
+      throw new Error(`driver: onBar at t=${t} returned ${typeof targets} — expected TargetPosition[] or null`)
+    }
+    const weights = targetsToWeights(targets, config.symbols)
+    decisions.push({ t, weights })
+    const prices = bars.map((series) => series[t]!.close)
+    orders.push(
+      ...rebalance({
+        targets,
+        symbols: config.symbols,
+        equity,
+        prices,
+        positionValues: [...pos],
+        t,
+        ...(config.tag !== undefined ? { tag: config.tag } : {}),
+      }),
+    )
+    if (t < T - 1) pendingFill = weights
+    // A decision on the final bar is recorded but can never fill — the same
+    // truth the batch engine encodes by never reading fills for t = T-1.
+  }
+
+  return { decisions, orders, equityByDay }
+}
+
+// ---------------------------------------------------------------------------
+// Batch-compat shims.
+// ---------------------------------------------------------------------------
+
+/** Wrap a v1 batch strategy (`generateSignals`) as a v2 `Strategy` so the
+ *  pinned baselines and legacy fixtures run UNCHANGED under the incremental
+ *  harness. At every bar the batch function sees only the truncated history
+ *  (the structural guarantee applies to it too) and the shim emits the
+ *  signal it produced for today, if any.
+ *
+ *  Note the intended consequence: a batch strategy that leaks through
+ *  whole-series statistics computes them over the TRUNCATED history here,
+ *  i.e. the shim converts that leak into a causal (if different) strategy.
+ *  The v1 truncation audit on the raw `generateSignals` remains the guard
+ *  that catches such code as written. */
+export function strategyFromGenerateSignals(generateSignals: GenerateSignals): Strategy {
+  return {
+    onBar(ctx: StrategyContext): TargetPosition[] | null {
+      const signals = generateSignals(ctx.history)
+      const today = signals.filter((s) => s.t === ctx.t)
+      if (today.length === 0) return null
+      if (today.length > 1) throw new Error(`batch shim: ${today.length} signals for t=${ctx.t}`)
+      const weights = today[0]!.weights
+      if (weights.length !== ctx.symbols.length) {
+        throw new Error(`batch shim: ${weights.length} weights for ${ctx.symbols.length} symbols at t=${ctx.t}`)
+      }
+      // Emit every symbol explicitly (zero weight = sell to flat) so the
+      // decision is a complete portfolio statement, exactly like v1.
+      return ctx.symbols.map((symbol, k) => ({ symbol, weight: weights[k]! }))
+    },
+  }
+}
+
+/** Adapt a v2 `Strategy` to the v1 batch shape so the existing scoring and
+ *  leak-audit plumbing (`truncationInvariance`, `runBacktest`) consume it
+ *  unchanged. Fees do not alter decisions unless the strategy conditions on
+ *  its own equity path, so the audit drives with the campaign's default
+ *  costs. */
+export function generateSignalsFromStrategy(
+  strategy: Strategy,
+  opts?: { symbols?: string[]; costBps?: number; slippageBps?: number },
+): GenerateSignals {
+  return (bars: Bar[][]): Signal[] => {
+    const symbols = opts?.symbols ?? bars.map((_, k) => (k === 0 ? 'IDX' : `T${String(k).padStart(2, '0')}`))
+    return runIncremental(bars, strategy, {
+      costBps: opts?.costBps ?? 10,
+      slippageBps: opts?.slippageBps ?? 5,
+      symbols,
+    }).decisions
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Module loading — one entry point for both contract generations.
+// ---------------------------------------------------------------------------
+
+export interface LoadedStrategy {
+  kind: 'v2-onBar' | 'v1-batch'
+  /** Batch view of the strategy; v2 modules are wrapped through the
+   *  incremental driver so the structural history guarantee applies. */
+  generateSignals: GenerateSignals
+}
+
+/** Import a strategy module from disk and normalize it to the batch shape
+ *  the scoring + leak-audit plumbing consumes. v2 (`onBar`) wins when a
+ *  module exports both. Throws when neither contract is implemented. */
+export async function loadStrategyFile(
+  strategyPath: string,
+  opts?: { symbols?: string[]; costBps?: number; slippageBps?: number },
+): Promise<LoadedStrategy> {
+  const mod = (await import(pathToFileURL(strategyPath).href)) as {
+    onBar?: Strategy['onBar']
+    generateSignals?: GenerateSignals
+  }
+  if (typeof mod.onBar === 'function') {
+    return { kind: 'v2-onBar', generateSignals: generateSignalsFromStrategy({ onBar: mod.onBar }, opts) }
+  }
+  if (typeof mod.generateSignals === 'function') {
+    return { kind: 'v1-batch', generateSignals: mod.generateSignals }
+  }
+  throw new Error(`strategy module exports neither onBar(ctx) nor generateSignals(bars): ${strategyPath}`)
+}

package/src/quant-arena/fixtures/data/PROVENANCE.md

@@ -0,0 +1,26 @@
+# Data provenance
+
+Every series in this directory is **synthetic**.
+It was produced by `../../make-fixtures.mts` with fixed seed `20260722`; regenerate and diff at any time with:
+
+```
+tsx src/quant-arena/make-fixtures.mts
+```
+
+## Why not real bars
+
+We wanted ~10 years of real daily bars for ~10 liquid US tickers plus SPY from Stooq (`https://stooq.com/q/d/l/?s=spy.us&i=d`).
+Two blockers, verified on 2026-07-22:
+
+1. Stooq's terms state the data are for personal use; committing their bars to a redistributable repository is not clearly permitted.
+2. The download endpoint sits behind a JavaScript anti-bot challenge and returned `Access denied` to non-browser clients.
+
+So the repo ships clearly-labeled synthetic series instead: an index `IDX` (the buy-and-hold benchmark, SPY's role) and ten stocks `S01`-`S10`, generated by a regime-switching market factor plus per-stock beta, idiosyncratic volatility, and rare jumps.
+The generator's model and parameters are documented in `make-fixtures.mts` itself.
+
+If you have the right to use real data locally, drop your own Stooq-format CSVs (`Date,Open,High,Low,Close,Volume`, one file per ticker, `IDX.csv` = your benchmark) into `insample/` and `holdout/` — every consumer reads only this directory layout.
+
+## Split
+
+- `insample/` — weekdays 2016-07-01 .. 2024-06-28 (2086 days). The only data the research loop can see.
+- `holdout/` — weekdays 2024-07-01 .. 2026-06-30 (522 days, the final 2 years). Read **only** by the certification command (`holdout-certify.mts`), never by the research loop.