@tangle-network/agent-bench 0.3.7 → 0.3.8

package/src/quant-arena/leak-audit.test.mts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import { truncationCutoffs, truncationInvariance } from './leak-audit.ts'
+import { generateSignals as smaCrossover } from './strategies/sma-crossover/strategy.ts'
+import { generateSignals as buyHold } from './strategies/buy-hold-index/strategy.ts'
+import type { Bar, Signal } from './types.ts'
+
+/** Deterministic wiggly price path (no RNG — the test must be 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,
+      }
+    }),
+  )
+}
+
+/** Deliberately leaky: sizes today's weight by TOMORROW's return. Exactly the
+ *  bug class the truncation check exists to kill. */
+const peekAheadStrategy = (bars: Bar[][]): Signal[] => {
+  const T = bars[0]!.length
+  const signals: Signal[] = []
+  for (let t = 0; t < T - 1; t++) {
+    const up = bars[0]![t + 1]!.close > bars[0]![t]!.close
+    signals.push({ t, weights: bars.map((_, k) => (k === 0 && up ? 1 : 0)) })
+  }
+  return signals
+}
+
+/** Leaky via whole-series statistics: normalizes by the FULL-sample max close. */
+const fullSampleMaxStrategy = (bars: Bar[][]): Signal[] => {
+  const maxClose = Math.max(...bars[0]!.map((b) => b.close))
+  const T = bars[0]!.length
+  const signals: Signal[] = []
+  for (let t = 0; t < T; t++) {
+    const w = bars[0]![t]!.close / maxClose
+    signals.push({ t, weights: bars.map((_, k) => (k === 0 ? w : 0)) })
+  }
+  return signals
+}
+
+describe('truncationInvariance — the mechanical look-ahead guard', () => {
+  const bars = syntheticBars(400, 3)
+
+  it('catches a strategy that peeks at tomorrow', () => {
+    const report = truncationInvariance(peekAheadStrategy, bars, { warmupDays: 50 })
+    expect(report.clean).toBe(false)
+    expect(report.divergence).not.toBeNull()
+    expect(report.divergence!.detail).toMatch(/decision changed|exists only/)
+  })
+
+  it('catches a strategy leaking through full-sample statistics', () => {
+    const report = truncationInvariance(fullSampleMaxStrategy, bars, { warmupDays: 50 })
+    expect(report.clean).toBe(false)
+  })
+
+  it('passes the pinned baselines (no look-ahead by construction)', () => {
+    expect(truncationInvariance(smaCrossover, bars, { warmupDays: 120 }).clean).toBe(true)
+    expect(truncationInvariance(buyHold, bars, { warmupDays: 50 }).clean).toBe(true)
+  })
+
+  it('cutoffs are inside (warmup, T-1) and deduplicated ascending', () => {
+    const cutoffs = truncationCutoffs(400, 50)
+    expect(cutoffs.length).toBeGreaterThanOrEqual(2)
+    for (const c of cutoffs) {
+      expect(c).toBeGreaterThan(50)
+      expect(c).toBeLessThan(399)
+    }
+    expect(cutoffs).toEqual([...cutoffs].sort((a, b) => a - b))
+    expect(new Set(cutoffs).size).toBe(cutoffs.length)
+  })
+})

package/src/quant-arena/leak-audit.ts

@@ -0,0 +1,95 @@
+/**
+ * Look-ahead (leak) audit — the deterministic half.
+ *
+ * The strongest guard against look-ahead bias is mechanical: run the strategy
+ * on data truncated at day c and on the full history. Under the contract
+ * ("the signal at t uses only bars[0..t]"), every signal with t <= c must be
+ * BIT-IDENTICAL in both runs. Any divergence proves the strategy read past
+ * its decision day — future closes, whole-series statistics, end-anchored
+ * indexing — regardless of how the leak was written.
+ *
+ * This check is necessary, not sufficient (a strategy hardcoding calendar
+ * dates it memorized survives truncation), which is why the campaign ALSO
+ * runs an adversarial LLM read of the source (see quant-loop.mts). Kill on
+ * either.
+ */
+
+import type { Bar, GenerateSignals, Signal } from './types.ts'
+
+export interface TruncationDivergence {
+  cutoff: number
+  t: number
+  detail: string
+}
+
+export interface TruncationReport {
+  clean: boolean
+  cutoffs: number[]
+  divergence: TruncationDivergence | null
+}
+
+/** Evenly spaced cutoffs across (warmupDays, totalDays - 1). */
+export function truncationCutoffs(totalDays: number, warmupDays: number, count = 6): number[] {
+  const lo = Math.max(warmupDays + 1, 1)
+  const hi = totalDays - 2
+  if (hi <= lo) throw new Error(`truncationCutoffs: no room between warmup ${warmupDays} and ${totalDays} days`)
+  const cutoffs = new Set<number>()
+  for (let i = 0; i < count; i++) {
+    cutoffs.add(Math.round(lo + ((hi - lo) * i) / Math.max(count - 1, 1)))
+  }
+  return [...cutoffs].sort((a, b) => a - b)
+}
+
+const signalMap = (signals: Signal[], maxT: number): Map<number, number[]> => {
+  const map = new Map<number, number[]>()
+  for (const s of signals) if (s.t <= maxT) map.set(s.t, s.weights)
+  return map
+}
+
+function compareAt(cutoff: number, full: Signal[], truncated: Signal[]): TruncationDivergence | null {
+  const fullMap = signalMap(full, cutoff)
+  const truncMap = signalMap(truncated, cutoff)
+  const ts = new Set([...fullMap.keys(), ...truncMap.keys()])
+  for (const t of [...ts].sort((a, b) => a - b)) {
+    const a = fullMap.get(t)
+    const b = truncMap.get(t)
+    if (a === undefined || b === undefined) {
+      return {
+        cutoff,
+        t,
+        detail: `signal at t=${t} exists only in the ${a === undefined ? 'truncated' : 'full'} run`,
+      }
+    }
+    if (a.length !== b.length) {
+      return { cutoff, t, detail: `weight vector length ${a.length} vs ${b.length} at t=${t}` }
+    }
+    for (let k = 0; k < a.length; k++) {
+      if (!Object.is(a[k], b[k])) {
+        return {
+          cutoff,
+          t,
+          detail: `weights[${k}] at t=${t}: full=${a[k]} truncated=${b[k]} — the decision changed when future bars were removed`,
+        }
+      }
+    }
+  }
+  return null
+}
+
+/** Run the truncation-invariance check. Deterministic; throws only if the
+ *  strategy itself throws. */
+export function truncationInvariance(
+  strategy: GenerateSignals,
+  bars: Bar[][],
+  opts: { warmupDays: number; cutoffs?: number[] },
+): TruncationReport {
+  const totalDays = bars[0]?.length ?? 0
+  const cutoffs = opts.cutoffs ?? truncationCutoffs(totalDays, opts.warmupDays)
+  const full = strategy(bars)
+  for (const cutoff of cutoffs) {
+    const truncated = strategy(bars.map((series) => series.slice(0, cutoff + 1)))
+    const divergence = compareAt(cutoff, full, truncated)
+    if (divergence !== null) return { clean: false, cutoffs, divergence }
+  }
+  return { clean: true, cutoffs, divergence: null }
+}

package/src/quant-arena/make-fixtures.mts

@@ -0,0 +1,161 @@
+/**
+ * Deterministic synthetic market generator — writes the vendored fixtures.
+ *
+ *   tsx src/quant-arena/make-fixtures.mts        # regenerates fixtures/data/**
+ *
+ * Why synthetic (see fixtures/data/PROVENANCE.md): the free daily-bar sources
+ * we checked (Stooq) license their data for personal use only and sit behind
+ * an anti-bot wall, so vendoring real bars into a redistributable repo is not
+ * clean. Instead the repo commits 10 years of clearly-labeled synthetic daily
+ * bars for an index (IDX) plus 10 stocks (S01..S10), produced by THIS file
+ * with a fixed seed — anyone can regenerate and diff them.
+ *
+ * The generator aims for realistic structure, not any real market's path:
+ *  - a two-state regime-switching market factor (calm: +9%/yr drift, 13% vol;
+ *    stress: -12%/yr drift, 32% vol; sticky transitions),
+ *  - per-stock beta in [0.6, 1.5], idiosyncratic vol 15-35%/yr, small alpha,
+ *    rare idiosyncratic jumps,
+ *  - OHLC built from overnight gaps + intraday ranges, lognormal volume.
+ *
+ * Split: weekdays 2016-07-01 .. 2026-06-30; the FINAL 2 YEARS (>= 2024-07-01)
+ * go to fixtures/data/holdout/, the rest to fixtures/data/insample/.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { HOLDOUT_DIR, HOLDOUT_START, IN_SAMPLE_DIR, INDEX_TICKER } from './data.ts'
+import { mulberry32 } from './windows.ts'
+
+export const FIXTURE_SEED = 20260722
+
+const START_DATE = '2016-07-01'
+const END_DATE = '2026-06-30'
+const DAYS_PER_YEAR = 252
+
+interface Regime {
+  driftAnnual: number
+  volAnnual: number
+  stayProb: number
+}
+
+const CALM: Regime = { driftAnnual: 0.09, volAnnual: 0.13, stayProb: 0.985 }
+const STRESS: Regime = { driftAnnual: -0.12, volAnnual: 0.32, stayProb: 0.92 }
+
+/** Seeded standard normal via Box-Muller over mulberry32. */
+function gaussian(rand: () => number): () => number {
+  let spare: number | null = null
+  return () => {
+    if (spare !== null) {
+      const v = spare
+      spare = null
+      return v
+    }
+    let u = 0
+    let v = 0
+    while (u === 0) u = rand()
+    while (v === 0) v = rand()
+    const mag = Math.sqrt(-2 * Math.log(u))
+    spare = mag * Math.sin(2 * Math.PI * v)
+    return mag * Math.cos(2 * Math.PI * v)
+  }
+}
+
+export function weekdays(startDate: string, endDate: string): string[] {
+  const dates: string[] = []
+  const d = new Date(`${startDate}T00:00:00Z`)
+  const end = new Date(`${endDate}T00:00:00Z`)
+  while (d.getTime() <= end.getTime()) {
+    const dow = d.getUTCDay()
+    if (dow !== 0 && dow !== 6) dates.push(d.toISOString().slice(0, 10))
+    d.setUTCDate(d.getUTCDate() + 1)
+  }
+  return dates
+}
+
+interface SyntheticSeries {
+  ticker: string
+  rows: Array<{ date: string; open: number; high: number; low: number; close: number; volume: number }>
+}
+
+export function generateUniverse(seed: number): SyntheticSeries[] {
+  const dates = weekdays(START_DATE, END_DATE)
+  const T = dates.length
+  const rand = mulberry32(seed)
+  const norm = gaussian(rand)
+
+  // Market factor daily log-returns under the regime chain.
+  let regime: Regime = CALM
+  const marketLogRet: number[] = new Array(T).fill(0)
+  for (let t = 1; t < T; t++) {
+    if (rand() > regime.stayProb) regime = regime === CALM ? STRESS : CALM
+    marketLogRet[t] = regime.driftAnnual / DAYS_PER_YEAR + (regime.volAnnual / Math.sqrt(DAYS_PER_YEAR)) * norm()
+  }
+
+  const specs = [
+    { ticker: INDEX_TICKER, beta: 1, idioVol: 0.02, alpha: 0, jumpProb: 0, basePrice: 200 },
+    ...Array.from({ length: 10 }, (_, i) => ({
+      ticker: `S${String(i + 1).padStart(2, '0')}`,
+      beta: 0.6 + rand() * 0.9,
+      idioVol: 0.15 + rand() * 0.2,
+      alpha: -0.02 + rand() * 0.08,
+      jumpProb: 0.004,
+      basePrice: 20 + rand() * 180,
+    })),
+  ]
+
+  return specs.map((spec) => {
+    const dailyIdio = spec.idioVol / Math.sqrt(DAYS_PER_YEAR)
+    const closes: number[] = new Array(T).fill(0)
+    closes[0] = spec.basePrice
+    for (let t = 1; t < T; t++) {
+      let logRet = spec.alpha / DAYS_PER_YEAR + spec.beta * marketLogRet[t]! + dailyIdio * norm()
+      if (spec.jumpProb > 0 && rand() < spec.jumpProb) {
+        logRet += (rand() < 0.5 ? -1 : 1) * (3 + rand() * 5) * dailyIdio
+      }
+      closes[t] = closes[t - 1]! * Math.exp(logRet)
+    }
+    const baseVolume = 1e6 * (0.5 + rand() * 4)
+    const rows = dates.map((date, t) => {
+      const prevClose = t === 0 ? closes[0]! : closes[t - 1]!
+      const close = closes[t]!
+      const gap = t === 0 ? 0 : 0.3 * dailyIdio * norm()
+      const open = round4(prevClose * Math.exp(gap))
+      const range = Math.abs(norm()) * 0.5 * dailyIdio
+      const high = round4(Math.max(open, close) * Math.exp(range))
+      const low = round4(Math.min(open, close) * Math.exp(-Math.abs(norm()) * 0.5 * dailyIdio))
+      const ret = t === 0 ? 0 : Math.abs(close / prevClose - 1)
+      const volume = Math.round(baseVolume * (1 + 3 * ret) * Math.exp(0.2 * norm()))
+      return { date, open, high, low, close: round4(close), volume }
+    })
+    return { ticker: spec.ticker, rows }
+  })
+}
+
+const round4 = (x: number): number => Math.round(x * 10_000) / 10_000
+
+function toCsv(series: SyntheticSeries, filter: (date: string) => boolean): string {
+  const lines = ['Date,Open,High,Low,Close,Volume']
+  for (const r of series.rows) {
+    if (!filter(r.date)) continue
+    lines.push(`${r.date},${r.open},${r.high},${r.low},${r.close},${r.volume}`)
+  }
+  return lines.join('\n') + '\n'
+}
+
+const isMain = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href
+
+if (isMain) {
+  const universe = generateUniverse(FIXTURE_SEED)
+  await mkdir(IN_SAMPLE_DIR, { recursive: true })
+  await mkdir(HOLDOUT_DIR, { recursive: true })
+  for (const series of universe) {
+    await writeFile(join(IN_SAMPLE_DIR, `${series.ticker}.csv`), toCsv(series, (d) => d < HOLDOUT_START))
+    await writeFile(join(HOLDOUT_DIR, `${series.ticker}.csv`), toCsv(series, (d) => d >= HOLDOUT_START))
+  }
+  const inDays = universe[0]!.rows.filter((r) => r.date < HOLDOUT_START).length
+  const outDays = universe[0]!.rows.length - inDays
+  console.log(
+    `wrote ${universe.length} tickers: ${inDays} in-sample days (< ${HOLDOUT_START}) + ${outDays} holdout days, seed ${FIXTURE_SEED}`,
+  )
+}

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

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+import {
+  BASE_EXCESS_SHARPE,
+  MULTIPLICITY_SPREAD,
+  decideAcceptance,
+  requiredExcessSharpe,
+} from './multiplicity.ts'
+
+describe('requiredExcessSharpe — the rising bar', () => {
+  it('equals the base floor for the very first candidate', () => {
+    expect(requiredExcessSharpe(1)).toBeCloseTo(BASE_EXCESS_SHARPE, 12)
+  })
+
+  it('matches the documented formula base + spread * sqrt(2 ln n)', () => {
+    for (const n of [2, 4, 10, 50, 200]) {
+      expect(requiredExcessSharpe(n)).toBeCloseTo(BASE_EXCESS_SHARPE + MULTIPLICITY_SPREAD * Math.sqrt(2 * Math.log(n)), 12)
+    }
+    // Spot values so a silent constant change fails a test, not just a diff.
+    expect(requiredExcessSharpe(10)).toBeCloseTo(0.1 + 0.15 * Math.sqrt(2 * Math.log(10)), 12)
+  })
+
+  it('is strictly increasing in candidates tried', () => {
+    let prev = requiredExcessSharpe(1)
+    for (let n = 2; n <= 100; n++) {
+      const cur = requiredExcessSharpe(n)
+      expect(cur).toBeGreaterThan(prev)
+      prev = cur
+    }
+  })
+
+  it('rejects a non-positive or fractional try count', () => {
+    expect(() => requiredExcessSharpe(0)).toThrow(/positive integer/)
+    expect(() => requiredExcessSharpe(2.5)).toThrow(/positive integer/)
+  })
+})
+
+describe('decideAcceptance — consistency AND multiplicity', () => {
+  const goodWindows = [0.9, 0.8, 1.0, 0.7, 0.85, 0.95, 0.6, 0.75]
+
+  it('accepts a consistent, large edge early in the campaign', () => {
+    const d = decideAcceptance({ perWindowExcess: goodWindows, nTried: 1 })
+    expect(d.accepted).toBe(true)
+    expect(d.wins).toBe(8)
+    expect(d.requiredWins).toBe(6)
+  })
+
+  it('rejects on consistency when the edge is one lucky stretch (5/8 wins)', () => {
+    const d = decideAcceptance({ perWindowExcess: [3, 3, 3, -0.1, -0.1, -0.1, 0.5, 0.5], nTried: 1 })
+    expect(d.accepted).toBe(false)
+    expect(d.wins).toBe(5)
+    expect(d.reasons[0]).toMatch(/consistency/)
+  })
+
+  it('the SAME evidence passes at n=1 and fails once enough candidates were tried', () => {
+    // Mean excess 0.30: above the n=1 bar (0.10), below the n=50 bar (~0.52).
+    const marginal = [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]
+    expect(decideAcceptance({ perWindowExcess: marginal, nTried: 1 }).accepted).toBe(true)
+    const late = decideAcceptance({ perWindowExcess: marginal, nTried: 50 })
+    expect(late.accepted).toBe(false)
+    expect(late.reasons[0]).toMatch(/multiplicity/)
+    expect(late.threshold).toBeGreaterThan(0.3)
+  })
+
+  it('fails closed on non-finite evidence and empty windows', () => {
+    expect(() => decideAcceptance({ perWindowExcess: [0.5, Number.NaN], nTried: 1 })).toThrow(/non-finite/)
+    expect(() => decideAcceptance({ perWindowExcess: [], nTried: 1 })).toThrow(/no windows/)
+  })
+})

package/src/quant-arena/multiplicity.ts

@@ -0,0 +1,87 @@
+/**
+ * Multiplicity-adjusted acceptance: the bar RISES with every candidate tried.
+ *
+ * Why: if you test N random strategies against the same data, the best one
+ * looks good by luck alone. Under the null (no skill), the expected maximum
+ * Sharpe across N independent tries grows like sqrt(2 ln N) times the
+ * cross-trial dispersion — that is the term the Deflated Sharpe Ratio of
+ * Bailey & Lopez de Prado ("The Deflated Sharpe Ratio", Journal of Portfolio
+ * Management, 2014) corrects for. We implement the simple, auditable version:
+ *
+ *   requiredExcessSharpe(n) = BASE + SPREAD * sqrt(2 * ln(n))
+ *
+ * where n counts EVERY candidate ever tried this campaign (including ones
+ * killed by the leak audit — they were still draws from the search), BASE is
+ * the floor a single try must clear, and SPREAD calibrates how fast luck
+ * accumulates. Every tried candidate is a permanent notebook row, so n can
+ * never be quietly reset.
+ *
+ * A candidate is accepted only if BOTH hold:
+ *   1. it beats the best pinned baseline's Sharpe in >= ceil(minWinFraction*K)
+ *      of the K in-sample windows (consistency, not one lucky stretch), and
+ *   2. its mean excess Sharpe across the K windows >= requiredExcessSharpe(n).
+ */
+
+/** Annualized excess-Sharpe floor for the very first candidate (n = 1). */
+export const BASE_EXCESS_SHARPE = 0.1
+/** Luck-accumulation rate: how fast the bar rises with tries. */
+export const MULTIPLICITY_SPREAD = 0.15
+
+export function requiredExcessSharpe(nTried: number): number {
+  if (!Number.isInteger(nTried) || nTried < 1) {
+    throw new Error(`requiredExcessSharpe: nTried must be a positive integer, got ${nTried}`)
+  }
+  return BASE_EXCESS_SHARPE + MULTIPLICITY_SPREAD * Math.sqrt(2 * Math.log(nTried))
+}
+
+export interface AcceptanceDecision {
+  accepted: boolean
+  wins: number
+  windows: number
+  requiredWins: number
+  meanExcessSharpe: number
+  threshold: number
+  nTried: number
+  reasons: string[]
+}
+
+export interface AcceptanceInput {
+  /** Candidate Sharpe minus best-baseline Sharpe, one entry per window. */
+  perWindowExcess: number[]
+  /** Total candidates tried this campaign INCLUDING this one. */
+  nTried: number
+  /** Fraction of windows the candidate must win. Default 0.75 (6 of 8). */
+  minWinFraction?: number
+}
+
+export function decideAcceptance(input: AcceptanceInput): AcceptanceDecision {
+  const { perWindowExcess, nTried } = input
+  const windows = perWindowExcess.length
+  if (windows === 0) throw new Error('decideAcceptance: no windows')
+  for (const e of perWindowExcess) {
+    if (!Number.isFinite(e)) throw new Error('decideAcceptance: non-finite excess Sharpe — fail-closed')
+  }
+  const minWinFraction = input.minWinFraction ?? 0.75
+  const requiredWins = Math.ceil(minWinFraction * windows)
+  const wins = perWindowExcess.filter((e) => e > 0).length
+  const meanExcessSharpe = perWindowExcess.reduce((s, e) => s + e, 0) / windows
+  const threshold = requiredExcessSharpe(nTried)
+  const reasons: string[] = []
+  if (wins < requiredWins) {
+    reasons.push(`consistency: beat the best baseline in only ${wins}/${windows} windows (need ${requiredWins})`)
+  }
+  if (meanExcessSharpe < threshold) {
+    reasons.push(
+      `multiplicity: mean excess Sharpe ${meanExcessSharpe.toFixed(3)} < required ${threshold.toFixed(3)} ` +
+        `(bar after ${nTried} tried candidate${nTried === 1 ? '' : 's'})`,
+    )
+  }
+  const accepted = reasons.length === 0
+  if (accepted) {
+    reasons.push(
+      `accepted: won ${wins}/${windows} windows, mean excess Sharpe ${meanExcessSharpe.toFixed(3)} ` +
+        `>= ${threshold.toFixed(3)} at n=${nTried}`,
+    )
+  }
+  return { accepted, wins, windows, requiredWins, meanExcessSharpe, threshold, nTried, reasons }
+}

package/src/quant-arena/nautilus-certify.ts

@@ -0,0 +1,31 @@
+/**
+ * Phase 3 stub — Nautilus Trader certification adapter (NOT IMPLEMENTED).
+ *
+ * Per the quant-arena v2 decision memo, the final certification tier runs a
+ * winning strategy's decision record through Nautilus Trader's event-driven
+ * engine (real OMS semantics: order lifecycle, partial fills, latency
+ * models) as an independent confirmation of the vectorbt score before
+ * anything is promoted. Phases 1-2 (this PR) end at the vectorbt worker;
+ * this seam exists so the campaign plumbing has a stable name to call.
+ *
+ * TODO(phase-3, quant-arena v2 memo): implement as a python worker sibling
+ * of python/vbt-worker.py (same JSONL protocol shape, own pinned uv env),
+ * translating the OMS `Order` stream from driver.ts — not raw weights —
+ * into Nautilus order submissions, and reconciling final equity against the
+ * vectorbt curve within a documented tolerance.
+ */
+
+import type { Order } from './types.ts'
+
+export interface NautilusCertification {
+  finalEquity: number
+  ordersAccepted: number
+  ordersRejected: number
+}
+
+export function certifyWithNautilus(_orders: Order[]): Promise<NautilusCertification> {
+  throw new Error(
+    'quant-arena: Nautilus certification is Phase 3 of the v2 memo and is not implemented yet — ' +
+      'the vectorbt worker (vbt-client.ts) is the current official scorer.',
+  )
+}

package/src/quant-arena/oms.ts

@@ -0,0 +1,90 @@
+/**
+ * The shared OMS rebalancer — the ONLY component that turns a strategy's
+ * target weights into orders. Strategies never construct `Order`s; keeping
+ * sizing in one place means every candidate and baseline trades under the
+ * same rules, and the leak/contract audits only ever have to reason about
+ * weights.
+ *
+ * Sizing (LEAN `CalculateOrderQuantity` style, long-only v2):
+ *   qty = (targetWeight * equity - currentPositionValue) / price
+ * at decision-time (close of day t) prices. Positive -> buy, negative ->
+ * sell. Quantities are fractional: the backtest engines track dollar
+ * positions, so lot rounding would only introduce parity noise between the
+ * TS prefilter and the vectorbt scorer. No fee buffer is reserved (fees are
+ * financed at 0% by the engines — conservative, never flattering).
+ *
+ * Long-only enforcement is fail-closed: a negative target weight, a weight
+ * sum > 1, or an unknown symbol throws rather than clamping.
+ */
+
+import type { Order, Rebalancer, TargetPosition } from './types.ts'
+
+const WEIGHT_EPS = 1e-9
+/** Trades below this fraction of equity are dust — no order is emitted. */
+const MIN_TRADE_FRACTION = 1e-9
+
+/** Validate targets and expand them to a full per-symbol weight vector
+ *  (omitted symbols -> 0). Throws on contract violations. */
+export function targetsToWeights(targets: TargetPosition[], symbols: string[]): number[] {
+  const index = new Map(symbols.map((s, k) => [s, k]))
+  const weights = new Array<number>(symbols.length).fill(0)
+  const seen = new Set<string>()
+  let sum = 0
+  for (const target of targets) {
+    const k = index.get(target.symbol)
+    if (k === undefined) {
+      throw new Error(`oms: target names unknown symbol '${target.symbol}' (universe: ${symbols.join(', ')})`)
+    }
+    if (seen.has(target.symbol)) {
+      throw new Error(`oms: symbol '${target.symbol}' targeted twice in one rebalance`)
+    }
+    seen.add(target.symbol)
+    if (!Number.isFinite(target.weight)) throw new Error(`oms: non-finite weight for '${target.symbol}'`)
+    if (target.weight < -WEIGHT_EPS) {
+      throw new Error(`oms: negative weight ${target.weight} for '${target.symbol}' — long-only, no shorting`)
+    }
+    weights[k] = Math.max(target.weight, 0)
+    sum += weights[k]!
+  }
+  if (sum > 1 + 1e-6) {
+    throw new Error(`oms: target weights sum ${sum} > 1 — no leverage`)
+  }
+  return weights
+}
+
+/** The one shared rebalancer. See module header for the sizing rule. */
+export const rebalance: Rebalancer = ({ targets, symbols, equity, prices, positionValues, t, tag }) => {
+  if (prices.length !== symbols.length || positionValues.length !== symbols.length) {
+    throw new Error(
+      `oms: state arrays disagree with the universe (${symbols.length} symbols, ` +
+        `${prices.length} prices, ${positionValues.length} positions)`,
+    )
+  }
+  if (!Number.isFinite(equity) || equity <= 0) throw new Error(`oms: nonpositive equity ${equity}`)
+  const weights = targetsToWeights(targets, symbols)
+  const orders: Order[] = []
+  for (let k = 0; k < symbols.length; k++) {
+    const price = prices[k]!
+    if (!Number.isFinite(price) || price <= 0) throw new Error(`oms: nonpositive price for '${symbols[k]}'`)
+    const desiredValue = weights[k]! * equity
+    const deltaValue = desiredValue - positionValues[k]!
+    if (Math.abs(deltaValue) <= MIN_TRADE_FRACTION * equity) continue
+    const qty = Math.abs(deltaValue) / price
+    const side = deltaValue > 0 ? 'buy' : 'sell'
+    if (side === 'sell' && deltaValue < -positionValues[k]! - MIN_TRADE_FRACTION * equity) {
+      // Cannot happen when weights >= 0, but keep the invariant explicit:
+      // a sell may never exceed the current long position.
+      throw new Error(`oms: sell of ${qty} '${symbols[k]}' exceeds current position — long-only`)
+    }
+    orders.push({
+      clientOrderId: `qa-t${t}-${symbols[k]}`,
+      symbol: symbols[k]!,
+      side,
+      qty,
+      type: 'market',
+      tif: 'day',
+      ...(tag !== undefined ? { tag } : {}),
+    })
+  }
+  return orders
+}

package/src/quant-arena/profiles/quant-researcher.profile.json

@@ -0,0 +1,7 @@
+{
+  "name": "quant-researcher",
+  "description": "Strategy-author lens that speaks quant language: regimes, turnover, capacity, transaction costs. Same claude harness as default-author; only the system prompt differs, so any performance delta is attributable to the lens.",
+  "prompt": {
+    "systemPrompt": "You are a systematic-trading researcher at a mid-frequency equity desk. You think in regimes (trend vs chop, calm vs stress), you treat turnover as a cost center (every rebalance pays spread + impact), you size positions for capacity, and you are allergic to backtest overfitting — you prefer one robust effect over five fitted parameters. When you write a strategy you state, in comments, the economic rationale the rule is harvesting and why it should survive out-of-sample."
+  }
+}

package/src/quant-arena/python/pyproject.toml

@@ -0,0 +1,8 @@
+[project]
+name = "quant-arena-vbt-worker"
+version = "0.1.0"
+description = "vectorbt scoring worker for bench/src/quant-arena (internal research use)"
+requires-python = ">=3.12"
+dependencies = [
+    "vectorbt==1.1.0",
+]