canli-backtest-mcp 0.3.0 → 0.4.0

package/README.md

@@ -40,6 +40,20 @@ Three mistakes make most agent-run backtests look better than they are:
 | `effective_bets` | How many independent bets a set of return series holds (the participation ratio of their correlations), by series and by family |
 | `annotation_packet`, `annotation_agreement`, `annotation_gold` | Blind labelling packets of figures (or of a draft's figures) with guidelines and an answer key; agreement between labellers (Cohen's kappa); and a gold set with its datasheet |
 
+## Size, crises and cross-validation
+
+A backtest that assumes any size fills at the close flatters itself, so:
+
+- **Size.** Give `backtest_signal` a `capital_usd` and a `dollar_volume_file`. An order fills only up to `max_participation` of recent daily volume (10% unless you say otherwise) and pays square-root impact, with volume and volatility read from the days before each trade. The reply shows the Sharpe at $100k to $1B, and no Sharpe for a size the market could not take. Order-book depth is not modelled: it needs paid data.
+- **Crises.** Every reply holds the result against named crises, from the dot-com bust to the 2023 bank run. A crisis its dates do not fully cover is listed as untested, never as passed. `crisis_replay` does this for any returns file.
+- **Cross-validation.** `cpcv` takes every variant's returns and, for each choice of held-out blocks, chooses the best on the rest, with purge and embargo at the edges, then scores it on what was held out. You get a spread of out-of-sample results, not one path. Splits can run as shards on other machines and merge back.
+
+## A record, a league and a paper market
+
+- **Proof ledger.** `proof_filings` writes what companies filed into an append-only file, each line chained to the last and each batch signed, with a line for every figure a later filing changed. `proof_file` adds any file's hash, `proof_verify` checks the whole file and says which line first fails. It shows lines were not altered, not that a figure is right, and no record means only no record. Publish the head somewhere else, or the key holder could rewrite it all. The [published ledger](https://github.com/arhancanli/canlicapital/releases) does that with a public attestation each month.
+- **League.** `league_new`, `league_commit` and `league_score` run a tournament scored after the fact: an entrant signs and commits a hash before a round closes and shows the file afterwards, and anyone with the files can rerun the table. Each record is set against the best luck gives across that many entrants. The top entrants, chosen on earlier rounds only, form a paper book. No prizes, no stakes, nobody's money.
+- **Arena.** `arena_new`, `arena_orders` and `arena_step` are a paper market for agents to trade in, cleared in a call auction, reproducible from a seed. Made-up assets and made-up money: it cannot reach anything real.
+
 ## Quick start
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canli-backtest-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "MCP server for backtests that refuse lookahead: point-in-time factors from SEC filings, cross-sectional backtests of any signal on your own prices, costs on actual trades, and every variant counted in a trial ledger.",
   "private": false,
   "type": "module",

package/src/arena.mjs

@@ -0,0 +1,150 @@
+// The arena: a paper market for AI agents to trade in. Made-up assets and made-up money, cleared in a
+// uniform-price call auction each step, reproducible from a seed. It is here so agents' behaviour
+// together can be studied: who supplies liquidity, who gets picked off, what a crowd does to a price.
+//
+// It touches nothing real. No real security, token or currency is represented, no order leaves the
+// file, and nothing here can be turned into a real market: running one needs registration as an
+// exchange or as a broker-dealer running an alternative trading system.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { z } from "zod";
+
+export const ARENA_LIMITS_TEXT = Object.freeze([
+  "Paper only: made-up assets and made-up money. Nothing here represents or can reach a real security, token or currency.",
+  "A simulated market leaves out most of what moves real ones, so behaviour here is a sketch for study and does not predict results in real markets.",
+]);
+
+const file = z.string().min(1).max(1000);
+const assetId = z.string().regex(/^ART[0-9]{1,2}$/, "an arena asset, such as ART1");
+// Names become keys in the state file, so ones every JavaScript object already answers to are refused.
+const agentId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]{1,39}$/).refine((n) => !(n in {}), "that name is reserved");
+export const arenaNewInput = z.object({
+  arena_file: file.describe("The arena's state file; must not exist yet."),
+  seed: z.number().int().min(0).max(2 ** 31 - 2).optional().describe("The same seed and the same orders give the same market. Default 1."),
+  assets: z.number().int().min(1).max(20).optional().describe("Made-up assets. Default 3."),
+  starting_cash: z.number().positive().max(1e9).optional().describe("Made-up money each agent starts with. Default 100000."),
+  bots: z.number().int().min(0).max(50).optional().describe("Scripted traders that keep the market moving: noise, value and momentum in turn. Default 6."),
+}).strict();
+export const arenaOrdersInput = z.object({
+  arena_file: file,
+  agent: agentId,
+  orders: z.array(z.object({ asset: assetId, side: z.enum(["buy", "sell"]), quantity: z.number().int().positive().max(1e7), limit: z.number().positive().max(1e7) }).strict()).max(50).describe("Replaces this agent's orders for the coming step. No short selling and no borrowing."),
+}).strict();
+export const arenaStepInput = z.object({ arena_file: file, steps: z.number().int().min(1).max(1000).optional().describe("Default 1.") }).strict();
+
+const SHARES_PER_AGENT = 100;
+const load = (f) => { if (!existsSync(f)) throw new RangeError(`${f} is not an arena yet: call arena_new`); const s = JSON.parse(readFileSync(f, "utf8")); if (s.schema !== "canli.arena.v1") throw new RangeError(`${f} is not an arena file`); return s; };
+// Every order in a step comes from an agent in the file, however the file was written.
+const orderLines = (state) => Object.entries(state.orders).filter(([agent]) => Object.hasOwn(state.agents, agent));
+const save = (f, s) => writeFileSync(f, JSON.stringify(s));
+function rng(state) { state.rng = (state.rng * 16807) % 2147483647; return state.rng / 2147483647; }
+const gauss = (s) => Math.sqrt(-2 * Math.log(rng(s))) * Math.cos(2 * Math.PI * rng(s));
+const newAgent = (s) => ({ cash: s.starting_cash, holdings: Object.fromEntries(s.assets.map((x) => [x.id, SHARES_PER_AGENT])), start_worth: s.starting_cash + s.assets.reduce((n, x) => n + SHARES_PER_AGENT * x.last, 0) });
+const round2 = (x) => Math.round(x * 100) / 100;
+
+export function arenaNew(args) {
+  const a = arenaNewInput.parse(args);
+  if (existsSync(a.arena_file)) throw new RangeError(`${a.arena_file} already exists`);
+  const state = { schema: "canli.arena.v1", paper_only: true, step: 0, rng: (a.seed ?? 1) + 1, starting_cash: a.starting_cash ?? 100000, assets: [], agents: {}, orders: {}, history: [] };
+  for (let i = 0; i < (a.assets ?? 3); i += 1) { const value = round2(50 + 100 * rng(state)); state.assets.push({ id: `ART${i + 1}`, value, last: value }); }
+  const kinds = ["noise", "value", "momentum"];
+  state.bots = Array.from({ length: a.bots ?? 6 }, (_, i) => ({ name: `bot-${kinds[i % 3]}-${i}`, kind: kinds[i % 3] }));
+  for (const b of state.bots) state.agents[b.name] = newAgent(state);
+  save(a.arena_file, state);
+  return { arena_file: a.arena_file, assets: state.assets.map((x) => ({ id: x.id, last: x.last })), bots: state.bots.length, plain_reading: "A new paper arena: made-up assets and made-up money. Send orders with arena_orders, then call arena_step.", limits: ARENA_LIMITS_TEXT };
+}
+
+// Refused if the agent could not pay for its buys or deliver its sells even if all of them filled.
+export function checkOrders(state, agent, orders) {
+  const me = Object.hasOwn(state.agents, agent) ? state.agents[agent] : newAgent(state), known = new Set(state.assets.map((x) => x.id));
+  let spend = 0;
+  const selling = {};
+  for (const o of orders) {
+    if (!known.has(o.asset)) throw new RangeError(`no asset ${o.asset} in this arena`);
+    if (o.side === "buy") spend += o.quantity * o.limit; else selling[o.asset] = (selling[o.asset] ?? 0) + o.quantity;
+  }
+  if (spend > me.cash + 1e-9) throw new RangeError(`these buys could cost ${round2(spend)} and ${agent} has ${round2(me.cash)}: no borrowing here`);
+  for (const [k, q] of Object.entries(selling)) if (q > (me.holdings[k] ?? 0)) throw new RangeError(`${agent} holds ${me.holdings[k] ?? 0} ${k} and is selling ${q}: no short selling here`);
+}
+export function arenaOrders(args) {
+  const a = arenaOrdersInput.parse(args), state = load(a.arena_file);
+  if (state.bots.some((b) => b.name === a.agent)) throw new RangeError(`${a.agent} is one of the arena's scripted traders`);
+  checkOrders(state, a.agent, a.orders);
+  if (!Object.hasOwn(state.agents, a.agent)) state.agents[a.agent] = newAgent(state);
+  state.orders[a.agent] = a.orders;
+  save(a.arena_file, state);
+  return { agent: a.agent, orders_waiting: a.orders.length, step: state.step, plain_reading: `${a.orders.length} paper orders wait for step ${state.step + 1}.`, limits: ARENA_LIMITS_TEXT };
+}
+
+// The uniform-price call auction: the price where the most can trade; among those, where the
+// imbalance is smallest, then nearest the last price. Best limits fill first, earliest first at a tie.
+export function clearAuction(orders, last) {
+  const buys = orders.filter((o) => o.side === "buy").sort((a, b) => b.limit - a.limit || a.at - b.at);
+  const sells = orders.filter((o) => o.side === "sell").sort((a, b) => a.limit - b.limit || a.at - b.at);
+  const candidates = [...new Set(orders.map((o) => o.limit))];
+  let best = null;
+  for (const p of candidates) {
+    const demand = buys.filter((o) => o.limit >= p).reduce((n, o) => n + o.quantity, 0), supply = sells.filter((o) => o.limit <= p).reduce((n, o) => n + o.quantity, 0);
+    const volume = Math.min(demand, supply), imbalance = Math.abs(demand - supply), gap = Math.abs(p - last);
+    if (volume > 0 && (!best || volume > best.volume || (volume === best.volume && (imbalance < best.imbalance || (imbalance === best.imbalance && gap < best.gap))))) best = { price: p, volume, imbalance, gap };
+  }
+  if (!best) return { price: null, volume: 0, fills: [] };
+  const fills = [];
+  const take = (list, side) => { let left = best.volume; for (const o of list) { if (left <= 0) break; if (side === "buy" ? o.limit < best.price : o.limit > best.price) continue; const q = Math.min(o.quantity, left); fills.push({ agent: o.agent, side, quantity: q }); left -= q; } };
+  take(buys, "buy");
+  take(sells, "sell");
+  return { price: best.price, volume: best.volume, fills };
+}
+
+function botOrders(state, bot, asset, previous, left) {
+  const me = state.agents[bot.name], qty = 1 + Math.floor(rng(state) * 5), noise = 1 + 0.01 * gauss(state);
+  let side, limit;
+  if (bot.kind === "value") { side = asset.last < asset.value ? "buy" : "sell"; limit = (asset.last + asset.value) / 2; }
+  else if (bot.kind === "momentum") { side = previous !== null && asset.last >= previous ? "buy" : "sell"; limit = asset.last * (side === "buy" ? 1.01 : 0.99); }
+  else { side = rng(state) < 0.5 ? "buy" : "sell"; limit = asset.last * noise; }
+  limit = Math.max(0.01, round2(limit));
+  if (side === "buy") { if (left.cash < qty * limit) return null; left.cash -= qty * limit; }
+  if (side === "sell" && (me.holdings[asset.id] ?? 0) < qty) return null;
+  return { asset: asset.id, side, quantity: qty, limit };
+}
+
+export function stepOnce(state) {
+  state.step += 1;
+  // Buys are held against cash across assets in this step, so no agent can overspend across auctions.
+  const all = [];
+  let at = 0;
+  for (const [agent, orders] of orderLines(state)) for (const o of orders) all.push({ ...o, agent, at: at++ });
+  const previous = state.history.at(-1)?.prices_before ?? {};
+  // What a bot could pay is held across its auctions in a step, as an agent's buys are at arena_orders.
+  for (const bot of state.bots) { const left = { cash: state.agents[bot.name].cash }; for (const asset of state.assets) { const o = botOrders(state, bot, asset, previous[asset.id] ?? null, left); if (o) all.push({ ...o, agent: bot.name, at: at++ }); } }
+  const record = { step: state.step, prices_before: Object.fromEntries(state.assets.map((x) => [x.id, x.last])), auctions: {} };
+  for (const asset of state.assets) {
+    const r = clearAuction(all.filter((o) => o.asset === asset.id), asset.last);
+    record.auctions[asset.id] = { price: r.price, volume: r.volume };
+    if (r.price !== null) {
+      for (const f of r.fills) {
+        const me = state.agents[f.agent], cost = f.quantity * r.price;
+        if (f.side === "buy") { me.cash -= cost; me.holdings[asset.id] = (me.holdings[asset.id] ?? 0) + f.quantity; }
+        else { me.cash += cost; me.holdings[asset.id] -= f.quantity; }
+      }
+      asset.last = r.price;
+    }
+    // The made-up value drifts on its own each step: there is no real company behind it.
+    asset.value = Math.max(1, round2(asset.value * (1 + 0.01 * gauss(state))));
+  }
+  state.orders = {};
+  state.history.push(record);
+  if (state.history.length > 500) state.history.shift();
+}
+
+export function standings(state) {
+  const worth = (me) => me.cash + state.assets.reduce((n, x) => n + (me.holdings[x.id] ?? 0) * x.last, 0);
+  return Object.entries(state.agents).map(([agent, me]) => ({ agent, bot: state.bots.some((b) => b.name === agent), worth: round2(worth(me)), gain: round2(worth(me) - me.start_worth), cash: round2(me.cash), holdings: me.holdings })).sort((a, b) => b.gain - a.gain);
+}
+
+export function arenaStep(args) {
+  const a = arenaStepInput.parse(args), state = load(a.arena_file);
+  for (let i = 0; i < (a.steps ?? 1); i += 1) stepOnce(state);
+  save(a.arena_file, state);
+  const last = state.history.at(-1);
+  return { step: state.step, prices: Object.fromEntries(state.assets.map((x) => [x.id, x.last])), last_auctions: last.auctions, standings: standings(state).slice(0, 25), plain_reading: `Paper step ${state.step} cleared. No real asset or money is involved.`, limits: ARENA_LIMITS_TEXT };
+}

package/src/cpcv.mjs

@@ -0,0 +1,164 @@
+// cpcv: combinatorial purged cross-validation (Lopez de Prado 2018, Advances in Financial Machine
+// Learning, chapter 12) over any set of trial return series. History is cut into N blocks. Every
+// choice of k blocks is a test set; on what remains the best trial is chosen, with days beside the
+// test blocks purged and embargoed so nothing leaks across the edge, and that trial's test returns
+// are kept. The kept pieces stitch into C(N-1, k-1) whole paths, so a search gets a spread of
+// out-of-sample results rather than the one path history happened to take.
+//
+// A split is the unit of work: any machine with the same file can run a shard of them, and a shard
+// carries the hash of the file and settings, so a merge refuses other data, gaps and duplicates.
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { z } from "zod";
+
+import { readPanel } from "./panel-io.mjs";
+
+const filePath = z.string().min(1).max(1000);
+export const cpcvInput = z.object({
+  returns_file: filePath.optional().describe("CSV: a date column and one column of daily returns per trial (breadth_book's out_file, say). At least two trials."),
+  groups: z.number().int().min(3).max(30).optional().describe("Blocks history is cut into. Default 10."),
+  test_groups: z.number().int().min(1).max(29).optional().describe("Blocks in each test set. Default 2."),
+  purge_days: z.number().int().min(0).max(500).optional().describe("Training days dropped before each test block: at least the horizon the trials' returns look ahead over. Default 5."),
+  embargo_days: z.number().int().min(0).max(500).optional().describe("Training days dropped after each test block. Default 5."),
+  periods_per_year: z.number().positive().optional().describe("Default 252."),
+  shard: z.object({ index: z.number().int().min(0), of: z.number().int().min(2).max(1000) }).strict().optional().describe("Run only splits s with s mod of = index, to spread the work over machines."),
+  out_file: filePath.optional().describe("Write the shard as JSON here."),
+  merge_files: z.array(filePath).min(2).max(1000).optional().describe("Instead of running: shard files to merge into one result."),
+}).strict();
+
+export const CPCV_LIMITS_TEXT = Object.freeze([
+  "The trial with the highest training Sharpe is the one chosen in each split; another way of choosing would give other paths.",
+  "Paths share days and data, so their spread is not a confidence interval and they are not independent tests.",
+  "This covers the search you supply. Variants tried and left out of the file are not counted, and survivorship in the data behind the trials passes straight through.",
+]);
+const MAX_SPLITS = 5000, MAX_CELLS = 100_000_000;
+
+export function choose(n, k) {
+  let c = 1;
+  for (let i = 1; i <= k; i += 1) c = (c * (n - k + i)) / i;
+  return Math.round(c);
+}
+export function splitsOf(n, k) {
+  const out = [], pick = [];
+  const walk = (from) => {
+    if (pick.length === k) { out.push([...pick]); return; }
+    for (let g = from; g < n; g += 1) { pick.push(g); walk(g + 1); pick.pop(); }
+  };
+  walk(0);
+  return out;
+}
+// Blocks of whole days, as equal as they can be: [first, last] inclusive.
+export function blocksOf(days, n) {
+  return Array.from({ length: n }, (_, g) => [Math.floor((g * days) / n), Math.floor(((g + 1) * days) / n) - 1]);
+}
+// 1 for a day training may use: outside the test blocks and their purge and embargo margins.
+export function trainMask(days, blocks, test, purge, embargo) {
+  const mask = new Uint8Array(days).fill(1);
+  for (const g of test) {
+    const [a, b] = blocks[g];
+    for (let t = Math.max(0, a - purge); t <= Math.min(days - 1, b + embargo); t += 1) mask[t] = 0;
+  }
+  return mask;
+}
+const sharpeOf = (values, scale) => {
+  let n = 0, mean = 0, s = 0;
+  for (const v of values) { if (!Number.isFinite(v)) continue; n += 1; const d = v - mean; mean += d / n; s += d * (v - mean); }
+  return n > 1 && s > 0 ? (mean / Math.sqrt(s / (n - 1))) * scale : null;
+};
+
+// One split: the best trial on the training days, and its returns on each test block.
+export function runSplit(panel, blocks, test, { purge, embargo, scale }) {
+  const days = panel.dates.length, mask = trainMask(days, blocks, test, purge, embargo);
+  let best = -1, bestSharpe = -Infinity;
+  panel.trials.forEach((name, i) => {
+    const r = panel.values[i];
+    let n = 0, mean = 0, s = 0;
+    for (let t = 0; t < days; t += 1) { if (!mask[t] || !Number.isFinite(r[t])) continue; n += 1; const d = r[t] - mean; mean += d / n; s += d * (r[t] - mean); }
+    const sh = n > 1 && s > 0 ? (mean / Math.sqrt(s / (n - 1))) * scale : -Infinity;
+    if (sh > bestSharpe) { bestSharpe = sh; best = i; }
+  });
+  if (best < 0 || !Number.isFinite(bestSharpe)) throw new RangeError(`no trial has enough training days when blocks ${test.join(",")} are the test set; use fewer groups, a shorter purge, or a longer file`);
+  // A chosen trial with no value on a day held nothing that day: it earns zero, and the day is counted.
+  let missing = 0;
+  const pieces = test.map((g) => {
+    const [a, b] = blocks[g], out = [];
+    for (let t = a; t <= b; t += 1) { const v = panel.values[best][t]; if (Number.isFinite(v)) out.push(v); else { out.push(0); missing += 1; } }
+    return [g, out];
+  });
+  return { chosen: best, train_sharpe: bestSharpe, missing, pieces };
+}
+
+// The kept pieces, whole: for path j, block g comes from the j-th split that tested g.
+export function assemble(results, groups) {
+  const seenByGroup = Array.from({ length: groups }, () => []);
+  for (const r of results.slice().sort((x, y) => x.s - y.s)) for (const [g, piece] of r.pieces) seenByGroup[g].push(piece);
+  const paths = seenByGroup[0].length;
+  for (const list of seenByGroup) if (list.length !== paths) throw new RangeError("the splits do not cover every block the same number of times");
+  return Array.from({ length: paths }, (_, j) => seenByGroup.flatMap((list) => list[j]));
+}
+
+function summarize(results, meta) {
+  const scale = Math.sqrt(meta.periods_per_year), sorted = (a) => a.slice().sort((x, y) => x - y), median = (a) => { const s = sorted(a), m = s.length >> 1; return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2; };
+  const pathReturns = assemble(results, meta.groups);
+  const path_sharpes = pathReturns.map((p) => sharpeOf(p, scale)).filter((x) => x !== null);
+  const train = results.map((r) => r.train_sharpe);
+  const counts = new Map();
+  for (const r of results) counts.set(r.chosen, (counts.get(r.chosen) ?? 0) + 1);
+  const chosen = [...counts].sort((a, b) => b[1] - a[1]).slice(0, 10).map(([i, n]) => ({ trial: meta.trials[i], splits: n }));
+  const lost = path_sharpes.filter((x) => x <= 0).length;
+  const out = {
+    first_date: meta.first_date, last_date: meta.last_date, trials: meta.trials.length,
+    groups: meta.groups, test_groups: meta.test_groups, purge_days: meta.purge_days, embargo_days: meta.embargo_days,
+    splits: results.length, paths: path_sharpes.length, path_sharpes,
+    out_of_sample_sharpe: { median: median(path_sharpes), lowest: Math.min(...path_sharpes), highest: Math.max(...path_sharpes), share_of_paths_at_or_below_zero: lost / path_sharpes.length },
+    in_sample_sharpe_median: median(train),
+    most_chosen: chosen, distinct_trials_chosen: counts.size,
+    missing_test_days: results.reduce((n, r) => n + r.missing, 0),
+  };
+  out.plain_reading = `The best trial chosen on training days showed a median Sharpe of ${out.in_sample_sharpe_median.toFixed(2)} there. On the days held out it showed ${out.out_of_sample_sharpe.median.toFixed(2)}, from ${out.out_of_sample_sharpe.lowest.toFixed(2)} to ${out.out_of_sample_sharpe.highest.toFixed(2)} across ${out.paths} paths, and ${lost} of the paths lost money. ${counts.size} of ${meta.trials.length} trials were chosen at least once.`;
+  out.limits = CPCV_LIMITS_TEXT;
+  return out;
+}
+
+export function loadTrials(file) {
+  const p = readPanel(file, "returns_file");
+  if (p.tickers.length < 2) throw new RangeError("returns_file needs at least two trials: with one there is nothing to choose between");
+  if (p.dates.length * p.tickers.length > MAX_CELLS) throw new RangeError(`returns_file has more than ${MAX_CELLS} values; cut it down`);
+  return { dates: p.dates, trials: p.tickers, values: p.tickers.map((t) => Float64Array.from(p.values[t], (v) => (v === null ? NaN : v))) };
+}
+
+export function cpcv(args) {
+  const a = cpcvInput.parse(args);
+  if (a.merge_files) {
+    const shards = a.merge_files.map((f) => JSON.parse(readFileSync(f, "utf8")));
+    const id = shards[0].cpcv_id;
+    for (const [i, s] of shards.entries()) if (s.schema !== "canli.cpcv-shard.v1" || s.cpcv_id !== id) throw new RangeError(`${a.merge_files[i]} is not a shard of the same run (file or settings differ)`);
+    const results = shards.flatMap((s) => s.results), seen = new Set();
+    for (const r of results) { if (seen.has(r.s)) throw new RangeError(`split ${r.s} appears in two shards`); seen.add(r.s); }
+    const wanted = shards[0].meta.total_splits, missing = Array.from({ length: wanted }, (_, s) => s).filter((s) => !seen.has(s));
+    if (missing.length) throw new RangeError(`shards are missing splits ${missing.slice(0, 10).join(", ")}${missing.length > 10 ? "..." : ""}`);
+    return { cpcv_id: id, merged_from: shards.length, ...summarize(results, shards[0].meta) };
+  }
+  if (!a.returns_file) throw new RangeError("cpcv needs returns_file (or merge_files).");
+  const groups = a.groups ?? 10, k = a.test_groups ?? 2;
+  if (k >= groups) throw new RangeError("test_groups must be fewer than groups: something has to be left to train on");
+  const total = choose(groups, k);
+  if (total > MAX_SPLITS) throw new RangeError(`${groups} groups taken ${k} at a time is ${total} splits; the most is ${MAX_SPLITS}`);
+  const panel = loadTrials(a.returns_file);
+  if (panel.dates.length < groups * 5) throw new RangeError(`${panel.dates.length} days is too short for ${groups} groups`);
+  const meta = { groups, test_groups: k, purge_days: a.purge_days ?? 5, embargo_days: a.embargo_days ?? 5, periods_per_year: a.periods_per_year ?? 252, trials: panel.trials, first_date: panel.dates[0], last_date: panel.dates.at(-1), total_splits: total };
+  const blocks = blocksOf(panel.dates.length, groups), splits = splitsOf(groups, k), scale = Math.sqrt(meta.periods_per_year);
+  const results = [];
+  splits.forEach((test, s) => {
+    if (a.shard && s % a.shard.of !== a.shard.index) return;
+    results.push({ s, ...runSplit(panel, blocks, test, { purge: meta.purge_days, embargo: meta.embargo_days, scale }) });
+  });
+  if (a.shard) {
+    if (a.shard.index >= a.shard.of) throw new RangeError("shard index must be below shard of");
+    const cpcv_id = createHash("sha256").update(readFileSync(a.returns_file)).update(JSON.stringify(meta)).digest("hex").slice(0, 24);
+    const shard = { schema: "canli.cpcv-shard.v1", cpcv_id, shard: a.shard, meta, results };
+    if (a.out_file) writeFileSync(a.out_file, JSON.stringify(shard));
+    return { cpcv_id, shard: a.shard, ran: results.length, of: total, ...(a.out_file ? { shard_file: a.out_file } : { shard_data: shard }), next: "Run the other shards with the same file and settings, then call cpcv with merge_files." };
+  }
+  return summarize(results, meta);
+}

package/src/engine.mjs

@@ -15,9 +15,65 @@
 export const ENGINE_LIMITS_TEXT = Object.freeze([
   "Prices are the caller's: survivorship, splits, dividends and data errors in them pass straight into the result.",
   "A backtest measures one path of history under these costs; it does not establish that the signal will keep working.",
-  "Costs are a flat rate per unit traded; market impact, borrow fees for shorts and financing are not charged unless included in cost_bps.",
+  "Costs are a flat rate per unit traded; market impact is charged only when capital and dollar volume are given, and borrow fees for shorts and financing are not charged unless included in cost_bps.",
 ]);
 
+// With capital and dollar volume, size meets the market. Average daily dollar volume and daily
+// volatility are read from the days before each trade, never the trade day. An order fills only up
+// to max participation of that volume (the rest stays unfilled and the old position stays open), and
+// pays square-root impact, the same law check_feasibility uses: Y x daily volatility x sqrt(participation)
+// (Toth et al. 2011). A name with too little volume history cannot trade at all: nothing is assumed.
+const LIQUIDITY_DAYS = 20, MIN_LIQUIDITY_DAYS = 10;
+export const FILL_RATIO_TRADABLE = 0.95;
+
+function liquidityAt(prices, volumes, t) {
+  let dollars = 0, days = 0;
+  const rets = [];
+  for (let i = Math.max(1, t - LIQUIDITY_DAYS); i < t; i += 1) {
+    if (finite(volumes[i]) && volumes[i] > 0) { dollars += volumes[i]; days += 1; }
+    const a = prices[i - 1], b = prices[i];
+    if (finite(a) && finite(b) && a > 0) rets.push(b / a - 1);
+  }
+  if (days < MIN_LIQUIDITY_DAYS || rets.length < MIN_LIQUIDITY_DAYS) return null;
+  const mean = rets.reduce((x, y) => x + y, 0) / rets.length;
+  return { adv: dollars / days, vol: Math.sqrt(rets.reduce((x, y) => x + (y - mean) ** 2, 0) / (rets.length - 1)) };
+}
+
+// Whole stretches of market history a strategy can be held against. Dates are peak to trough or the
+// episode's usual bounds; the first eight are the ones stress_worlds drops into its worlds.
+export const CRISES = Object.freeze({
+  dotcom_bust: { from: "2000-03-24", to: "2002-10-09", what: "the 2000-02 dot-com bust" },
+  bank_crisis: { from: "2008-09-02", to: "2009-03-09", what: "the 2008-09 bank crisis" },
+  debt_ceiling_2011: { from: "2011-04-29", to: "2011-10-03", what: "the 2011 US downgrade and euro debt scare" },
+  taper_tantrum: { from: "2013-05-22", to: "2013-09-05", what: "the 2013 taper tantrum in bonds" },
+  oil_collapse: { from: "2014-06-20", to: "2016-02-11", what: "the 2014-16 oil collapse" },
+  dollar_surge: { from: "2014-07-01", to: "2015-03-13", what: "the 2014-15 surge in the dollar" },
+  q4_2018: { from: "2018-09-20", to: "2018-12-24", what: "the late 2018 sell-off" },
+  pandemic_crash: { from: "2020-02-19", to: "2020-03-23", what: "the February-March 2020 crash" },
+  inflation_shock: { from: "2022-01-03", to: "2022-06-16", what: "the 2022 inflation and rate shock" },
+  compute_bust: { from: "2022-01-03", to: "2022-10-14", what: "the 2022 fall in chip and compute stocks" },
+  regional_bank_run: { from: "2023-03-01", to: "2023-03-24", what: "the March 2023 regional bank run" },
+});
+export const CRISIS_DRAWDOWN_LIMIT = 0.5;
+
+// The strategy's own returns inside every crisis its dates fully cover. A crisis the run does not
+// fully cover is listed as untested: not having been there is not the same as having survived it.
+export function crisisReplay({ dates, returns, limit = CRISIS_DRAWDOWN_LIMIT }) {
+  if (!(limit > 0 && limit <= 1)) throw new RangeError("the crisis drawdown limit must be above 0 and at most 1");
+  const tested = [], untested = [];
+  for (const [id, c] of Object.entries(CRISES)) {
+    if (!(dates[0] <= c.from && dates.at(-1) >= c.to)) { untested.push({ id, what: c.what, from: c.from, to: c.to }); continue; }
+    let wealth = 1, peak = 1, drawdown = 0, days = 0, worst = 0;
+    for (let i = 0; i < dates.length; i += 1) {
+      if (dates[i] < c.from || dates[i] > c.to) continue;
+      wealth *= 1 + returns[i]; peak = Math.max(peak, wealth); drawdown = Math.max(drawdown, 1 - wealth / peak); worst = Math.min(worst, returns[i]); days += 1;
+    }
+    tested.push({ id, what: c.what, from: c.from, to: c.to, days, return: wealth - 1, drawdown, worst_day: worst, ruptured: drawdown > limit });
+  }
+  const verdict = !tested.length ? "untested" : tested.some((c) => c.ruptured) ? "ruptured" : "survived_tested";
+  return { verdict, drawdown_limit: limit, tested, untested };
+}
+
 const REBALANCE = Object.freeze({ weekly: "week", monthly: "month", quarterly: "quarter" });
 const periodKey = (date, every) => {
   const [y, m] = date.split("-").map(Number);
@@ -70,12 +126,20 @@ function lastRowOnOrBefore(signalDates, bound) {
   return found;
 }
 
-export function runBacktest({ dates, tickers, prices, signalDates, signals, rebalance = "monthly", lagDays = 1, side = "long_short", quantile = 0.2, costBps = 10, minNames = 5, periodsPerYear = 252 }) {
+export function runBacktest({ dates, tickers, prices, signalDates, signals, rebalance = "monthly", lagDays = 1, side = "long_short", quantile = 0.2, costBps = 10, minNames = 5, periodsPerYear = 252, capital = null, dollarVolumes = null, maxParticipation = 0.1, impactCoefficient = 1 }) {
   checkInputs({ dates, tickers, prices, signalDates, signals });
   if (!Number.isInteger(lagDays) || lagDays < 1) throw new RangeError("lag_days must be a whole number of at least 1: a signal cannot trade on the day it becomes known");
   if (!(quantile > 0 && quantile <= 0.5)) throw new RangeError("quantile must be in (0, 0.5]");
   if (!["long_short", "long_only"].includes(side)) throw new RangeError("side must be long_short or long_only");
   if (!(costBps >= 0)) throw new RangeError("cost_bps cannot be negative");
+  const sized = capital !== null;
+  if (sized) {
+    if (!(capital > 0)) throw new RangeError("capital must be above zero");
+    if (!dollarVolumes) throw new RangeError("capital needs dollar volume: without it nothing says how much the market can take");
+    if (!(maxParticipation > 0 && maxParticipation <= 1)) throw new RangeError("max participation must be above 0 and at most 1");
+    if (!(impactCoefficient >= 0)) throw new RangeError("the impact coefficient cannot be negative");
+  }
+  const liq = { impact: 0, orders: 0, clipped: 0, blocked: 0, wanted: 0, filled: 0, maxFilled: 0, worst: null };
 
   const n = dates.length;
   const rebal = new Set(rebalanceIndices(dates, rebalance, lagDays));
@@ -116,9 +180,26 @@ export function runBacktest({ dates, tickers, prices, signalDates, signals, reba
     const long = ranked.slice(0, k), short = side === "long_short" ? ranked.slice(-k) : [];
     for (const tk of long) target.set(tk, nav / long.length);
     for (const tk of short) target.set(tk, (target.get(tk) ?? 0) - nav / short.length);
-    let traded = 0;
-    for (const tk of new Set([...pos.keys(), ...target.keys()])) traded += Math.abs((target.get(tk) ?? 0) - (pos.get(tk) ?? 0));
-    const cost = traded * costBps / 1e4;
+    let traded = 0, impact = 0;
+    for (const tk of new Set([...pos.keys(), ...target.keys()])) {
+      const held = pos.get(tk) ?? 0, want = (target.get(tk) ?? 0) - held;
+      if (!sized) { traded += Math.abs(want); continue; }
+      if (want === 0) continue;
+      const l = liquidityAt(prices[tk], dollarVolumes[tk] ?? [], t);
+      const wanted = Math.abs(want);
+      liq.orders += 1; liq.wanted += wanted;
+      if (!l) { liq.blocked += 1; target.set(tk, held); continue; }
+      const room = maxParticipation * l.adv / capital;
+      const wantedShare = wanted * capital / l.adv;
+      if (!liq.worst || wantedShare > liq.worst.wanted_participation) liq.worst = { ticker: tk, date: dates[t], wanted_participation: wantedShare, average_daily_dollars: l.adv };
+      const fill = Math.min(wanted, room);
+      if (fill < wanted) { liq.clipped += 1; target.set(tk, held + Math.sign(want) * fill); }
+      const share = fill * capital / l.adv;
+      impact += fill * impactCoefficient * l.vol * Math.sqrt(share);
+      traded += fill; liq.filled += fill; liq.maxFilled = Math.max(liq.maxFilled, share);
+    }
+    liq.impact += impact;
+    const cost = traded * costBps / 1e4 + impact;
     nav -= cost;
     const factor = 1 - cost / (nav + cost);
     if (started && out.returns.length) {
@@ -133,7 +214,14 @@ export function runBacktest({ dates, tickers, prices, signalDates, signals, reba
     started = true;
   }
   if (!rebalances) throw new RangeError("no rebalance had enough names with both a known signal and a price; check the dates overlap and min_names");
-  return { ...out, used, nav, rebalances, turnoverSum, costSum, missingDays, longNames, shortNames, periodsPerYear };
+  const fillRatio = liq.wanted > 0 ? liq.filled / liq.wanted : 1;
+  const liquidity = sized ? {
+    capital_usd: capital, max_participation: maxParticipation, impact_coefficient: impactCoefficient,
+    impact_paid: liq.impact, orders: liq.orders, clipped_orders: liq.clipped, blocked_orders: liq.blocked,
+    fill_ratio: fillRatio, filled_participation_max: liq.maxFilled, worst: liq.worst,
+    verdict: fillRatio >= FILL_RATIO_TRADABLE ? "tradable" : "too_big",
+  } : undefined;
+  return { ...out, used, nav, rebalances, turnoverSum, costSum, missingDays, longNames, shortNames, periodsPerYear, ...(sized ? { liquidity } : {}) };
 }
 
 // Plain statistics of a return series, in the same Sharpe convention as the validators (sample sd).

package/src/league.mjs

@@ -0,0 +1,243 @@
+// The league: anyone's model, scored on what happens after it committed. An entrant commits the hash
+// of a CSV of scores before a round closes, the hash goes in a proof ledger, and the file is shown
+// only after the round. Scoring is open: the same files and prices give the same table on any
+// machine. An entry's rank correlation with what followed is its score, the table sets each
+// entrant's record against the best that luck gives across that many entrants, and the top entrants
+// are combined into a paper book, so the league shows what a pool of them would have done.
+//
+// Paper only. There are no prizes, no stakes and nobody's money in it.
+import { createHash, createPublicKey, sign, verify } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+
+import { readPanel } from "./panel-io.mjs";
+import { appendRecords, loadKey, readLines, verifyLedger } from "./proof.mjs";
+
+export const LEAGUE_LIMITS_TEXT = Object.freeze([
+  "Paper only: no prizes, no stakes, and nobody's money is in the league or its paper book.",
+  "A commit's time is the clock of the machine that wrote the ledger. For a public round, keep the ledger in a public repository or service so the time can be checked from outside.",
+  "A place in the table is a record over these rounds, not a forecast. With few rounds, luck and skill cannot be told apart, which the deflated figure tries to show.",
+  "One person can enter under many names and nothing here stops it. Every name counts toward the luck bar, so that raises the bar for everyone including them.",
+]);
+
+const sha256 = (b) => createHash("sha256").update(b).digest("hex");
+const date = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
+const dir = z.string().min(1).max(1000);
+
+export const leagueNewInput = z.object({
+  league_dir: dir.describe("A folder for the league's rules, ledger and entries."),
+  name: z.string().min(1).max(120),
+  first_close: date.describe("When entries for the first round close; scoring starts the next trading day."),
+  rounds: z.number().int().min(1).max(520).describe("Number of rounds."),
+  days_per_round: z.number().int().min(1).max(90).optional().describe("Calendar days from one close to the next, and each round's scoring span. Default 7."),
+  min_names: z.number().int().min(5).max(5000).optional().describe("Fewest scored names an entry needs. Default 20."),
+}).strict();
+export function leagueNew(args) {
+  const a = leagueNewInput.parse(args);
+  const file = join(a.league_dir, "league.json");
+  const step = a.days_per_round ?? 7, day = (d, n) => { const x = new Date(`${d}T00:00:00Z`); x.setUTCDate(x.getUTCDate() + n); return x.toISOString().slice(0, 10); };
+  const rounds = Array.from({ length: a.rounds }, (_, i) => { const closes = day(a.first_close, i * step); return { id: `r${String(i + 1).padStart(3, "0")}`, closes, ends: day(closes, step) }; });
+  mkdirSync(a.league_dir, { recursive: true });
+  const rules = { schema: "canli.league.v1", name: a.name, min_names: a.min_names ?? 20, rounds };
+  try { writeFileSync(file, `${JSON.stringify(rules, null, 1)}\n`, { flag: "wx" }); } catch (err) {
+    if (err.code === "EEXIST") throw new RangeError(`${file} already exists; a league's rules do not change after it starts`);
+    throw err;
+  }
+  return { league_dir: a.league_dir, rules_sha256: sha256(readFileSync(file)), rounds: rounds.length, first_round: rounds[0], last_round: rounds.at(-1), plain_reading: `${a.name}: ${rounds.length} rounds. Publish the rules' hash before the first close, so the schedule cannot quietly change.`, limits: LEAGUE_LIMITS_TEXT };
+}
+
+const readRules = (leagueDir) => {
+  const file = join(leagueDir, "league.json");
+  if (!existsSync(file)) throw new RangeError(`${leagueDir} is not a league: no league.json`);
+  return JSON.parse(readFileSync(file, "utf8"));
+};
+// An entry: rows of ticker,score. Every score a finite number, no ticker twice.
+export function parseEntry(text, minNames = 20) {
+  const lines = text.replace(/^/, "").split(/\r?\n/).filter((l) => l.trim());
+  const scores = new Map();
+  for (const [i, line] of lines.entries()) {
+    const [t, s] = line.split(",").map((x) => x.trim());
+    if (i === 0 && /^ticker$/i.test(t)) continue;
+    if (!t || s === undefined || s === "" || !Number.isFinite(Number(s))) throw new RangeError(`entry line ${i + 1}: expected ticker,score with a number`);
+    if (scores.has(t)) throw new RangeError(`entry line ${i + 1}: ${t} appears twice`);
+    scores.set(t, Number(s));
+  }
+  if (scores.size < minNames) throw new RangeError(`an entry needs at least ${minNames} names; this has ${scores.size}`);
+  return scores;
+}
+
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{1,39}$/;
+const entrantName = z.string().regex(NAME, "2 to 40 letters, digits, _ or -");
+export const leagueCommitInput = z.object({
+  league_dir: dir,
+  round: z.string().regex(/^r\d{3}$/),
+  entrant: entrantName,
+  file: dir.describe("The entry: a CSV of ticker,score, higher meaning expected to do better. Only its hash is recorded now."),
+  entrant_key_file: dir.describe("The entrant's own signing key (PEM), created if new. A name belongs to the key that first committed under it, so nobody else can replace an entrant's entry."),
+  key_file: dir.optional().describe("The league's signing key for its ledger (PEM); created if new."),
+}).strict();
+// What an entrant signs: which round, which name, which file, so a signature cannot be replayed elsewhere.
+const commitMessage = (round, entrant, digest) => Buffer.from(`canli.league.commit.v1|${round}|${entrant}|${digest}`);
+function commitIsSigned(c) {
+  try { return verify(null, commitMessage(c.round, c.entrant, c.sha256), createPublicKey(c.entrant_public_key), Buffer.from(c.entrant_signature, "base64")); } catch { return false; }
+}
+export function leagueCommit(args, now = () => new Date()) {
+  const a = leagueCommitInput.parse(args);
+  const rules = readRules(a.league_dir), round = rules.rounds.find((r) => r.id === a.round);
+  if (!round) throw new RangeError(`no round ${a.round} in this league`);
+  const today = now().toISOString().slice(0, 10);
+  if (today >= round.closes) throw new RangeError(`round ${a.round} closed on ${round.closes}: an entry must be committed before the day it closes`);
+  const bytes = readFileSync(a.file);
+  parseEntry(bytes.toString("utf8"), rules.min_names);
+  const digest = sha256(bytes);
+  const ledger = join(a.league_dir, "ledger.jsonl"), { key, publicPem } = loadKey(a.entrant_key_file);
+  const holder = existsSync(ledger) ? readLines(ledger).find((e) => e.kind === "file" && e.body?.kind === "league_entry" && e.body.entrant === a.entrant) : null;
+  if (holder && holder.body.entrant_public_key !== publicPem) throw new RangeError(`the name ${a.entrant} belongs to the key that first committed under it; this is another key`);
+  const r = appendRecords(ledger, [{ kind: "file", body: { id: `league|${a.round}|${a.entrant}|${digest}`, sha256: digest, label: `league entry ${a.round} ${a.entrant}`, kind: "league_entry", round: a.round, entrant: a.entrant, entrant_public_key: publicPem, entrant_signature: sign(null, commitMessage(a.round, a.entrant, digest), key).toString("base64") } }], { keyFile: a.key_file, now });
+  return { round: a.round, entrant: a.entrant, sha256: digest, ...r, plain_reading: `Committed ${a.entrant}'s entry for ${a.round}. Keep the file unchanged and reveal it after ${round.ends}: put it at ${join(a.league_dir, a.round, `${a.entrant}.csv`)}.`, limits: LEAGUE_LIMITS_TEXT };
+}
+
+// Average ranks, ties shared, for Spearman's correlation.
+export function ranks(values) {
+  const order = values.map((v, i) => [v, i]).sort((x, y) => x[0] - y[0]), out = new Array(values.length);
+  for (let i = 0; i < order.length;) {
+    let j = i;
+    while (j + 1 < order.length && order[j + 1][0] === order[i][0]) j += 1;
+    for (let k = i; k <= j; k += 1) out[order[k][1]] = (i + j) / 2;
+    i = j + 1;
+  }
+  return out;
+}
+export function pearson(x, y) {
+  const n = x.length, mx = x.reduce((a, b) => a + b, 0) / n, my = y.reduce((a, b) => a + b, 0) / n;
+  let sxy = 0, sxx = 0, syy = 0;
+  for (let i = 0; i < n; i += 1) { sxy += (x[i] - mx) * (y[i] - my); sxx += (x[i] - mx) ** 2; syy += (y[i] - my) ** 2; }
+  return sxx > 0 && syy > 0 ? sxy / Math.sqrt(sxx * syy) : null;
+}
+export const spearman = (x, y) => pearson(ranks(x), ranks(y));
+
+// The return of each name from the last close on or before `from` to the last close on or before `to`.
+function forwardReturns(prices, from, to) {
+  const last = (d) => { let k = -1; for (let i = 0; i < prices.dates.length && prices.dates[i] <= d; i += 1) k = i; return k; };
+  const a = last(from), b = last(to), out = new Map();
+  if (a < 0 || b <= a) return out;
+  for (const t of prices.tickers) { const p0 = prices.values[t][a], p1 = prices.values[t][b]; if (p0 > 0 && p1 > 0) out.set(t, p1 / p0 - 1); }
+  return out;
+}
+function scoreEntry(scores, returns, minNames) {
+  const names = [...scores.keys()].filter((t) => returns.has(t));
+  if (names.length < minNames) return null;
+  const s = names.map((t) => scores.get(t)), r = names.map((t) => returns.get(t));
+  const corr = spearman(s, r);
+  if (corr === null) return null;
+  const k = Math.floor(names.length / 5), sorted = names.map((_, i) => i).sort((p, q) => s[q] - s[p]);
+  const mean = (idx) => idx.reduce((n, i) => n + r[i], 0) / idx.length;
+  return { names: names.length, corr, top_minus_bottom: mean(sorted.slice(0, k)) - mean(sorted.slice(-k)) };
+}
+
+const GAMMA = 0.5772156649015329;
+function normInv(p) {
+  // Acklam's rational approximation, enough for a table's luck bar.
+  const a = [-39.69683028665376, 220.9460984245205, -275.9285104469687, 138.357751867269, -30.66479806614716, 2.506628277459239], b = [-54.47609879822406, 161.5858368580409, -155.6989798598866, 66.80131188771972, -13.28068155288572], c = [-0.007784894002430293, -0.3223964580411365, -2.400758277161838, -2.549732539343734, 4.374664141464968, 2.938163982698783], d = [0.007784695709041462, 0.3224671290700398, 2.445134137142996, 3.754408661907416];
+  const tail = (q) => (((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) / ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1);
+  if (p < 0.02425) return tail(Math.sqrt(-2 * Math.log(p)));
+  if (p > 1 - 0.02425) return -tail(Math.sqrt(-2 * Math.log(1 - p)));
+  const q = p - 0.5, r = q * q;
+  return ((((((a[0] * r + a[1]) * r + a[2]) * r + a[3]) * r + a[4]) * r + a[5]) * q) / (((((b[0] * r + b[1]) * r + b[2]) * r + b[3]) * r + b[4]) * r + 1);
+}
+const normCdf = (x) => { const z = Math.abs(x) / Math.SQRT2, t = 1 / (1 + 0.5 * z), e = t * Math.exp(-z * z - 1.26551223 + t * (1.00002368 + t * (0.37409196 + t * (0.09678418 + t * (-0.18628806 + t * (0.27886807 + t * (-1.13520398 + t * (1.48851587 + t * (-0.82215223 + t * 0.17087277))))))))); return x >= 0 ? 1 - e / 2 : e / 2; };
+// The t-statistic the best of n entrants reaches by luck alone (expected maximum of n standard normals).
+export const luckT = (n) => (n < 2 ? 0 : (1 - GAMMA) * normInv(1 - 1 / n) + GAMMA * normInv(1 - 1 / (n * Math.E)));
+
+export const leagueScoreInput = z.object({
+  league_dir: dir,
+  prices_file: dir.describe("CSV: a date column and one column of closing prices per ticker. Everyone re-running the table needs the same file."),
+  book_size: z.number().int().min(1).max(100).optional().describe("How many top entrants the paper book combines. Default 5."),
+}).strict();
+export function leagueScore(args) {
+  const a = leagueScoreInput.parse(args);
+  const rules = readRules(a.league_dir), prices = readPanel(a.prices_file, "prices_file");
+  const ledger = join(a.league_dir, "ledger.jsonl"), lastDate = prices.dates.at(-1);
+  const results = [], problems = [], perRound = new Map();
+  const check = existsSync(ledger) ? verifyLedger(ledger) : null;
+  if (check && !check.valid) throw new RangeError(`the league's ledger does not verify: ${check.problems[0]}`);
+  const commitLines = existsSync(ledger) ? readLines(ledger).filter((e) => e.kind === "file" && e.body?.kind === "league_entry").map((e) => ({ ...e.body, at: e.at })) : [];
+  // A name belongs to the first validly signed commit's key.
+  const owners = new Map();
+  for (const c of commitLines) if (commitIsSigned(c) && !owners.has(c.entrant)) owners.set(c.entrant, c.entrant_public_key);
+  let open = 0;
+  for (const round of rules.rounds) {
+    if (round.ends > lastDate) { open += 1; continue; }
+    const returns = forwardReturns(prices, round.closes, round.ends);
+    // Only an entrant's latest commit before the close counts, so committing several files and
+    // revealing whichever did best is refused: a reveal must match that one.
+    const latest = new Map();
+    for (const c of commitLines) {
+      if (c.round !== round.id) continue;
+      if (!NAME.test(c.entrant ?? "")) { problems.push(`A commit for ${round.id} has an unusable entrant name, not scored.`); continue; }
+      if (!commitIsSigned(c) || owners.get(c.entrant) !== c.entrant_public_key) { problems.push(`${c.entrant} ${round.id}: a commit not signed by the key that holds this name, not scored.`); continue; }
+      if (String(c.at).slice(0, 10) >= round.closes) { problems.push(`${c.entrant} ${round.id}: committed on or after the close, not scored.`); continue; }
+      latest.set(c.entrant, c);
+    }
+    const entries = new Map();
+    for (const c of latest.values()) {
+      const file = join(a.league_dir, round.id, `${c.entrant}.csv`);
+      if (!existsSync(file)) { problems.push(`${c.entrant} ${round.id}: committed but not revealed, not scored.`); continue; }
+      const bytes = readFileSync(file);
+      if (sha256(bytes) !== c.sha256) { problems.push(`${c.entrant} ${round.id}: the revealed file is not the one committed, not scored.`); continue; }
+      entries.set(c.entrant, parseEntry(bytes.toString("utf8"), rules.min_names));
+    }
+    perRound.set(round.id, { round, returns, entries });
+    for (const [entrant, scores] of entries) {
+      const s = scoreEntry(scores, returns, rules.min_names);
+      if (s) results.push({ round: round.id, entrant, ...s }); else problems.push(`${entrant} ${round.id}: too few of its names have prices for the round, not scored.`);
+    }
+  }
+  const byEntrant = new Map();
+  for (const r of results) (byEntrant.get(r.entrant) ?? byEntrant.set(r.entrant, []).get(r.entrant)).push(r);
+  const bar = luckT(byEntrant.size);
+  const table = [...byEntrant].map(([entrant, list]) => {
+    const n = list.length, mean = list.reduce((x, r) => x + r.corr, 0) / n, sd = n > 1 ? Math.sqrt(list.reduce((x, r) => x + (r.corr - mean) ** 2, 0) / (n - 1)) : null;
+    const t = sd > 0 ? mean / (sd / Math.sqrt(n)) : null;
+    return { entrant, rounds: n, mean_score: mean, score_sd: sd, t_stat: t, chance_it_beats_luck: t === null ? null : normCdf(t - bar) };
+  }).sort((x, y) => (y.chance_it_beats_luck ?? -1) - (x.chance_it_beats_luck ?? -1) || y.mean_score - x.mean_score);
+  // How different each entrant is from the rest: its average correlation with the others' scores.
+  for (const row of table) {
+    const cs = [];
+    for (const { entries } of perRound.values()) {
+      const mine = entries.get(row.entrant);
+      if (!mine) continue;
+      for (const [other, theirs] of entries) {
+        if (other === row.entrant) continue;
+        const names = [...mine.keys()].filter((t) => theirs.has(t));
+        if (names.length >= 5) { const c = spearman(names.map((t) => mine.get(t)), names.map((t) => theirs.get(t))); if (c !== null) cs.push(c); }
+      }
+    }
+    row.average_correlation_with_others = cs.length ? cs.reduce((x, y) => x + y, 0) / cs.length : null;
+  }
+  // The paper book: in each round, the entrants ranked best on rounds before it only, their ranks averaged.
+  const size = a.book_size ?? 5, book = [];
+  for (const { round, returns, entries } of perRound.values()) {
+    const before = results.filter((r) => r.round < round.id), tally = new Map();
+    for (const r of before) { const t = tally.get(r.entrant) ?? { sum: 0, n: 0 }; t.sum += r.corr; t.n += 1; tally.set(r.entrant, t); }
+    const chosen = [...tally].filter(([e]) => entries.has(e)).sort((x, y) => y[1].sum / y[1].n - x[1].sum / x[1].n).slice(0, size).map(([e]) => e);
+    if (!chosen.length) continue;
+    const combined = new Map();
+    for (const e of chosen) {
+      const s = entries.get(e), names = [...s.keys()], rk = ranks(names.map((t) => s.get(t)));
+      names.forEach((t, i) => { const c = combined.get(t) ?? { sum: 0, n: 0 }; c.sum += rk[i] / (names.length - 1 || 1); c.n += 1; combined.set(t, c); });
+    }
+    const scores = new Map([...combined].map(([t, c]) => [t, c.sum / c.n]));
+    const s = scoreEntry(scores, returns, rules.min_names);
+    if (s) book.push({ round: round.id, entrants: chosen, ...s });
+  }
+  const bookMean = book.length ? book.reduce((x, r) => x + r.top_minus_bottom, 0) / book.length : null;
+  const inputs = { rules_sha256: sha256(readFileSync(join(a.league_dir, "league.json"))), prices_sha256: sha256(readFileSync(a.prices_file)), ledger_head: check?.head ?? null };
+  return {
+    name: rules.name, rounds_scored: perRound.size, rounds_still_open: open, entrants: table.length, luck_bar_t: bar, table,
+    paper_book: { rounds: book.length, average_round_return: bookMean, chosen_on_earlier_rounds_only: true, by_round: book.slice(-52) }, problems, inputs,
+    plain_reading: table.length ? `${table.length} ${table.length === 1 ? "entrant" : "entrants"} over ${perRound.size} rounds. With this many entrants the best reaches a t of about ${bar.toFixed(2)} by luck alone; ${table.filter((r) => (r.chance_it_beats_luck ?? 0) > 0.95).length} clear that with more than 95%.${book.length ? ` The paper book of the top ${size} made ${(100 * bookMean).toFixed(2)}% a round, top fifth minus bottom fifth, before costs.` : ""}` : "No entry has been scored yet.",
+    limits: LEAGUE_LIMITS_TEXT,
+  };
+}

package/src/proof.mjs

@@ -0,0 +1,200 @@
+// The proof ledger: an append-only file where each line carries the hash of the line before it and
+// each batch ends in a seal signed with Ed25519. Into it go what companies filed (each figure with
+// its filing, and a restatement line whenever a later filing changes one) and the hash of any file,
+// a backtest's result or a league entry, so anyone can later check it existed unchanged.
+//
+// What this proves is narrow and worth stating: the lines have not been altered since they were
+// sealed. It does not prove a figure is right or a strategy is good, and an absent record proves
+// nothing about whatever is missing. Whoever holds the key could rewrite the whole chain, unless a
+// head was copied somewhere else first, so heads should be published and passed back as anchors.
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+
+import { getJson, pad10, resolveEntity } from "canli-markets-mcp/src/sources.mjs";
+
+export const SCHEMA = "canli.proof-ledger.v1";
+export const PROOF_LIMITS_TEXT = Object.freeze([
+  "A ledger shows these lines have not changed since they were sealed. It does not show a figure is right or a strategy is any good.",
+  "No record means no record. It says nothing about the filing, file or strategy that is missing.",
+  "Whoever holds the signing key could rewrite the whole chain unless a head was copied elsewhere first: publish heads, and check them with anchors.",
+]);
+
+export const canonical = (v) => (v === null || typeof v !== "object" ? JSON.stringify(v) : Array.isArray(v) ? `[${v.map(canonical).join(",")}]` : `{${Object.keys(v).sort().filter((k) => v[k] !== undefined).map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`).join(",")}}`);
+const sha256 = (b) => createHash("sha256").update(b).digest("hex");
+export const entryHash = (e) => sha256(canonical({ seq: e.seq, at: e.at, kind: e.kind, body: e.body, prev: e.prev }));
+const defaultKeyFile = () => join(process.env.CANLI_HOME || join(homedir(), ".canli"), "proof-key.pem");
+
+export function loadKey(file = defaultKeyFile()) {
+  let pem;
+  try { pem = readFileSync(file, "utf8"); } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    pem = generateKeyPairSync("ed25519").privateKey.export({ type: "pkcs8", format: "pem" });
+    // wx: if another process made the key first, that one is the key, and this one is dropped.
+    try { writeFileSync(file, pem, { flag: "wx", mode: 0o600 }); } catch (e) { if (e.code !== "EEXIST") throw e; pem = readFileSync(file, "utf8"); }
+  }
+  const key = createPrivateKey(pem);
+  return { key, publicPem: createPublicKey(key).export({ type: "spki", format: "pem" }) };
+}
+
+export function readLines(file) {
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8").split("\n").filter((l) => l.trim()).map((l, i) => {
+    try { return JSON.parse(l); } catch { throw new RangeError(`line ${i + 1} of the ledger is not JSON`); }
+  });
+}
+
+// Add records to the ledger and seal them. Records already there (by their id) are left out.
+export function appendRecords(file, records, { keyFile, now = () => new Date() } = {}) {
+  const { key, publicPem } = loadKey(keyFile);
+  const lines = readLines(file), at = now().toISOString();
+  mkdirSync(dirname(file), { recursive: true });
+  let head = lines.at(-1) ?? null;
+  const add = (kind, body) => {
+    const e = { seq: head ? head.seq + 1 : 0, at, kind, body, prev: head ? head.hash : null };
+    e.hash = entryHash(e);
+    head = e;
+    return e;
+  };
+  const out = [];
+  if (!lines.length) out.push(add("header", { schema: SCHEMA, public_key: publicPem }));
+  else if (lines[0].body?.public_key !== publicPem) throw new RangeError("this key did not start this ledger; use the key it was started with");
+  const known = new Set(lines.filter((l) => l.body?.id).map((l) => l.body.id));
+  let added = 0;
+  for (const r of records) {
+    if (r.body.id && known.has(r.body.id)) continue;
+    if (r.body.id) known.add(r.body.id);
+    out.push(add(r.kind, r.body));
+    added += 1;
+  }
+  if (added) {
+    const seal = add("seal", { over: head.hash });
+    seal.signature = sign(null, Buffer.from(seal.hash, "hex"), key).toString("base64");
+    out.push(seal);
+  }
+  if (out.length) appendFileSync(file, `${out.map((e) => JSON.stringify(e)).join("\n")}\n`);
+  return { added, skipped: records.length - added, head: head ? { seq: head.seq, hash: head.hash } : null };
+}
+
+// Recompute the chain from the file alone. Stops at the first line that does not hold.
+export function verifyLedger(file, anchors = []) {
+  const lines = readLines(file), problems = [];
+  if (!lines.length) return { valid: false, entries: 0, problems: ["The ledger is empty or missing."] };
+  const header = lines[0];
+  if (header.kind !== "header" || header.body?.schema !== SCHEMA) problems.push("The first line is not this ledger's header.");
+  let publicKey = null;
+  try { publicKey = createPublicKey(header.body.public_key); } catch { problems.push("The header's public key cannot be read."); }
+  let prev = null, seals = 0, sealedTo = -1;
+  for (const [i, e] of lines.entries()) {
+    if (e.seq !== i) { problems.push(`Line ${i + 1} has sequence ${e.seq}: a line was added, removed or moved.`); break; }
+    if (e.prev !== prev) { problems.push(`Line ${i + 1} does not follow the one before it.`); break; }
+    if (entryHash(e) !== e.hash) { problems.push(`Line ${i + 1} was changed: its hash does not match its content.`); break; }
+    if (e.kind === "seal") {
+      if (!publicKey || !e.signature || !verify(null, Buffer.from(e.hash, "hex"), publicKey, Buffer.from(e.signature, "base64"))) { problems.push(`Line ${i + 1} is a seal whose signature does not verify.`); break; }
+      seals += 1; sealedTo = i;
+    }
+    prev = e.hash;
+  }
+  for (const a of anchors) if (lines[a.seq]?.hash !== a.hash) problems.push(`The published head at line ${a.seq + 1} does not match this file, so history was rewritten or cut.`);
+  const tail = lines.length - 1 - sealedTo;
+  if (!problems.length && tail > 0) problems.push(`${tail} ${tail === 1 ? "line comes" : "lines come"} after the last seal and ${tail === 1 ? "is" : "are"} unsigned.`);
+  const head = lines.at(-1);
+  return {
+    valid: problems.length === 0, entries: lines.length, seals, anchors_checked: anchors.length,
+    head: { seq: head.seq, hash: head.hash, at: head.at }, key_fingerprint: publicKey ? sha256(publicKey.export({ type: "spki", format: "der" })).slice(0, 16) : null,
+    problems, limits: PROOF_LIMITS_TEXT,
+  };
+}
+
+// ---------------------------------------------------------------------------------------------
+// What companies filed, and what later filings changed
+// ---------------------------------------------------------------------------------------------
+const CONCEPTS = Object.freeze(["RevenueFromContractWithCustomerExcludingAssessedTax", "Revenues", "SalesRevenueNet", "NetIncomeLoss", "OperatingIncomeLoss", "GrossProfit", "Assets", "Liabilities", "StockholdersEquity", "CashAndCashEquivalentsAtCarryingValue", "NetCashProvidedByUsedInOperatingActivities", "EarningsPerShareDiluted"]);
+
+// Rows from a concept's facts: one record per value per filing, and a restatement where a period's value changes.
+export function filingRecords(cik, name, concept, unit, rows) {
+  const byPeriod = new Map();
+  for (const r of rows) if (r.accn && Number.isFinite(r.val)) { const p = `${r.start ?? ""}|${r.end}`; (byPeriod.get(p) ?? byPeriod.set(p, []).get(p)).push(r); }
+  const out = [];
+  for (const list of byPeriod.values()) {
+    list.sort((a, b) => String(a.filed).localeCompare(String(b.filed)) || String(a.accn).localeCompare(String(b.accn)));
+    let last = null;
+    for (const r of list) {
+      if (last === null || r.val !== last.val) {
+        const period = { ...(r.start ? { start: r.start } : {}), end: r.end };
+        const base = { cik, company: name, concept, unit, ...period };
+        out.push({ kind: "figure", body: { id: `figure|${cik}|${concept}|${unit}|${r.start ?? ""}|${r.end}|${r.val}|${r.accn}`, ...base, value: r.val, form: r.form, accession: r.accn, filed: r.filed } });
+        if (last !== null) out.push({ kind: "restatement", body: { id: `restatement|${cik}|${concept}|${unit}|${r.start ?? ""}|${r.end}|${last.accn}|${r.accn}`, ...base, from: { value: last.val, accession: last.accn, filed: last.filed }, to: { value: r.val, accession: r.accn, filed: r.filed }, change: last.val !== 0 ? (r.val - last.val) / Math.abs(last.val) : null } });
+        last = r;
+      }
+    }
+  }
+  return out;
+}
+
+export const proofFilingsInput = z.object({
+  ledger_file: z.string().min(1).max(1000).describe("The ledger file; started if new."),
+  companies: z.array(z.string().min(1).max(120)).min(1).max(600).describe("Tickers, CIKs or names."),
+  key_file: z.string().min(1).max(1000).optional().describe("Signing key (PEM); created if new. Default ~/.canli/proof-key.pem."),
+}).strict();
+export async function proofFilings(session, args) {
+  const a = proofFilingsInput.parse(args);
+  const records = [], read = [], failed = [];
+  for (const c of a.companies) {
+    try {
+      const e = await resolveEntity(session, c);
+      const facts = await getJson(session, `https://data.sec.gov/api/xbrl/companyfacts/CIK${pad10(e.cik)}.json`, { maxBytes: 96 * 1024 * 1024 });
+      for (const concept of CONCEPTS) for (const [unit, rows] of Object.entries(facts?.facts?.["us-gaap"]?.[concept]?.units ?? {})) records.push(...filingRecords(e.cik, e.name ?? facts.entityName ?? c, concept, unit, rows));
+      read.push(c);
+    } catch (err) { failed.push({ company: c, why: String(err.message).slice(0, 200) }); }
+  }
+  const r = appendRecords(a.ledger_file, records, { keyFile: a.key_file });
+  const restatements = records.filter((x) => x.kind === "restatement").length;
+  return { ledger_file: a.ledger_file, companies_read: read.length, ...(failed.length ? { failed } : {}), figures_and_restatements_read: records.length, restatements_seen: restatements, ...r, plain_reading: `Read ${read.length} ${read.length === 1 ? "company" : "companies"}: ${r.added} new lines sealed, ${r.skipped} already in the ledger. ${restatements} changes between filings seen. A change can be a correction, a reclassification or a new way of reporting; the lines do not say which.`, limits: PROOF_LIMITS_TEXT };
+}
+
+export const proofFileInput = z.object({
+  ledger_file: z.string().min(1).max(1000).describe("The ledger file; started if new."),
+  file: z.string().min(1).max(1000).describe("The file to record: a backtest's result, a returns file, a league entry. Only its hash goes in the ledger."),
+  label: z.string().min(1).max(200).describe("What this file is."),
+  kind: z.enum(["backtest", "returns", "league_entry", "other"]).optional().describe("Default other."),
+  key_file: z.string().min(1).max(1000).optional().describe("Signing key (PEM); created if new."),
+}).strict();
+export function proofFile(args) {
+  const a = proofFileInput.parse(args);
+  const digest = sha256(readFileSync(a.file));
+  const r = appendRecords(a.ledger_file, [{ kind: "file", body: { id: `file|${digest}`, sha256: digest, label: a.label, kind: a.kind ?? "other" } }], { keyFile: a.key_file });
+  return { ledger_file: a.ledger_file, sha256: digest, ...r, plain_reading: r.added ? `Recorded the hash of ${a.file}: this exact file existed when this line was sealed. Nothing else about it is claimed.` : "This exact file is already in the ledger.", limits: PROOF_LIMITS_TEXT };
+}
+
+export const proofVerifyInput = z.object({
+  ledger_file: z.string().min(1).max(1000),
+  anchors: z.array(z.object({ seq: z.number().int().min(0), hash: z.string().regex(/^[0-9a-f]{64}$/) }).strict()).max(1000).optional().describe("Heads published elsewhere: each must still be in the file."),
+}).strict();
+
+export const proofFindInput = z.object({
+  ledger_file: z.string().min(1).max(1000),
+  sha256: z.string().regex(/^[0-9a-f]{64}$/).optional().describe("A file's hash."),
+  file: z.string().min(1).max(1000).optional().describe("Or the file itself, hashed here."),
+  company: z.string().min(1).max(120).optional().describe("Company name or CIK as recorded."),
+  concept: z.string().min(1).max(160).optional(),
+  kind: z.enum(["figure", "restatement", "file"]).optional(),
+  limit: z.number().int().min(1).max(500).optional().describe("Default 50."),
+}).strict();
+export function proofFind(args) {
+  const a = proofFindInput.parse(args);
+  const want = a.file ? sha256(readFileSync(a.file)) : a.sha256;
+  const who = a.company?.toLowerCase();
+  const hits = readLines(a.ledger_file).filter((e) => {
+    if (!["figure", "restatement", "file"].includes(e.kind)) return false;
+    if (a.kind && e.kind !== a.kind) return false;
+    if (want && e.body.sha256 !== want) return false;
+    if (who && !(String(e.body.company ?? "").toLowerCase().includes(who) || String(e.body.cik) === a.company)) return false;
+    return !(a.concept && e.body.concept !== a.concept);
+  });
+  const limit = a.limit ?? 50;
+  return { found: hits.length, records: hits.slice(-limit).map((e) => ({ seq: e.seq, at: e.at, kind: e.kind, ...e.body, id: undefined, hash: e.hash })), plain_reading: hits.length ? `${hits.length} ${hits.length === 1 ? "record" : "records"} found.` : "No record found. That says only that this ledger holds none: it does not mean the file, figure or strategy is wrong or made up.", limits: PROOF_LIMITS_TEXT };
+}

package/src/server.mjs

@@ -22,14 +22,18 @@ import { ledgerDir, recordTrial } from "canli-validation-mcp/src/ledger.mjs";
 import { agreementInput, annotationAgreement, annotationGold, annotationPacket, goldInput, packetInput } from "./annotate.mjs";
 import { BREADTH_LIMITS_TEXT, effectiveBets, runBreadth, signalCatalog } from "./breadth.mjs";
 import { buildPanel, panelInput } from "./panel.mjs";
-import { ENGINE_LIMITS_TEXT, describe, runBacktest } from "./engine.mjs";
+import { CRISES, crisisReplay, ENGINE_LIMITS_TEXT, describe, runBacktest } from "./engine.mjs";
+import { cpcv, cpcvInput, CPCV_LIMITS_TEXT } from "./cpcv.mjs";
+import { arenaNew, arenaNewInput, arenaOrders, arenaOrdersInput, arenaStep, arenaStepInput } from "./arena.mjs";
+import { leagueCommit, leagueCommitInput, leagueNew, leagueNewInput, leagueScore, leagueScoreInput } from "./league.mjs";
+import { proofFile, proofFileInput, proofFilings, proofFilingsInput, proofFind, proofFindInput, proofVerifyInput, verifyLedger } from "./proof.mjs";
 import { readPanel, writePanel } from "./panel-io.mjs";
 import { breadthSweep, sweepInput } from "./sweep.mjs";
 import { FACTORS, PIT_LIMITS_TEXT, buildFactorPanel } from "./pit.mjs";
 
 export const SERVER_NAME = "canli-backtest-mcp";
 export const SERVER_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-export const SERVER_INSTRUCTIONS = "Backtests that refuse lookahead. Build a point-in-time factor from SEC filings with pit_factor (or bring your own signal CSV, each row dated when it was known), then run backtest_signal against your own prices CSV. Pass the same ledger name to every backtest_signal call in one search: the reply judges the best variant against all of them. For breadth, price_panel builds a free price panel (an index fund's holdings, prices, dollar volume and industries), breadth_book builds a sleeve for every signal in every industry from one price panel and trades them as one netted account; effective_bets counts the independent bets in any set of return series. For datasets, annotation_packet, annotation_agreement and annotation_gold turn figures into a gold set people have checked against the filings.";
+export const SERVER_INSTRUCTIONS = "Backtests that refuse lookahead. Build a point-in-time factor from SEC filings with pit_factor (or bring your own signal CSV, each row dated when it was known), then run backtest_signal against your own prices CSV. Pass the same ledger name to every backtest_signal call in one search: the reply judges the best variant against all of them. For breadth, price_panel builds a free price panel (an index fund's holdings, prices, dollar volume and industries), breadth_book builds a sleeve for every signal in every industry from one price panel and trades them as one netted account; effective_bets counts the independent bets in any set of return series. For a search, cpcv scores the chosen variant on held-out blocks across many paths, and crisis_replay holds any returns against named crises. proof_filings and proof_file keep a signed, append-only record; league_new, league_commit and league_score run a paper league scored after the fact; arena_new, arena_orders and arena_step are a paper market for agents, with made-up assets and money. For datasets, annotation_packet, annotation_agreement and annotation_gold turn figures into a gold set people have checked against the filings.";
 export const SERVER_INFO = Object.freeze({
   name: SERVER_NAME,
   version: SERVER_VERSION,
@@ -80,10 +84,20 @@ export const backtestInput = z.object({
   cost_bps: z.number().min(0).optional().describe("Cost per unit traded, in basis points. Default 10."),
   min_names: z.number().int().min(2).optional().describe("Skip a rebalance with fewer ranked names. Default 5."),
   periods_per_year: z.number().positive().optional().describe("Default 252 (daily prices)."),
+  capital_usd: z.number().positive().optional().describe("Size to trade at, in dollars. Needs dollar_volume_file. Orders fill only up to max_participation of recent volume and pay square-root impact, and the reply adds a capacity curve."),
+  dollar_volume_file: filePath.optional().describe("CSV like prices_file with daily dollar volume. price_panel writes one from adjusted closes, which understates older volume by the dividends paid since."),
+  max_participation: z.number().gt(0).max(1).optional().describe("Largest share of a name's average daily dollar volume one order can take. Default 0.1."),
+  impact_coefficient: z.number().min(0).max(5).optional().describe("Y in impact = Y x daily volatility x sqrt(participation). Default 1."),
+  crisis_drawdown_limit: z.number().gt(0).max(1).optional().describe("A drawdown beyond this inside one crisis counts as a rupture. Default 0.5."),
   ledger: z.string().regex(/^[a-z0-9][a-z0-9-]{2,63}$/).optional().describe("Record this run in a search ledger (created if new) and judge it against every run recorded there."),
   label: z.string().min(1).max(200).optional().describe("The variant's name in the ledger. Default: the settings."),
 });
 
+export const crisisInput = z.object({
+  returns_file: filePath.describe("CSV: a date column (YYYY-MM-DD) and one column of daily returns per strategy, at most 50."),
+  drawdown_limit: z.number().gt(0).max(1).optional().describe("A drawdown beyond this inside one crisis counts as a rupture. Default 0.5."),
+}).strict();
+
 export const breadthInput = z.object({
   prices_file: filePath.describe("CSV: a date column and one column of closing (total-return) prices per ticker."),
   groups_file: filePath.optional().describe("CSV with columns ticker,group (an industry, say): one sleeve per signal per group. Default: one group, the whole panel."),
@@ -114,7 +128,19 @@ export const TOOL_DESCRIPTIONS = Object.freeze({
   effective_bets: "How many independent bets a set of return series holds: the participation ratio of their weekly correlations (n for unrelated series, 1 for copies), and with families, the families' bets and the ideas they cluster into.",
   list_factors: "The point-in-time factors pit_factor builds from SEC filings, and what each measures.",
   pit_factor: `Build a factor from SEC filings for a list of tickers, monthly from start to end, using only what had been filed by each date (restatements invisible until filed). Writes a signal CSV for backtest_signal. ${PIT_LIMITS_TEXT[0]}`,
-  backtest_signal: `Backtest a signal against your prices: rank, long and short quantiles, rebalance, trading only on what was known lag_days earlier, costs on actual trades. Pass ledger to judge the best of a search against all of it. ${ENGINE_LIMITS_TEXT[1]}`,
+  proof_filings: "Add what companies filed to a signed, append-only ledger: each figure with its filing, and a restatement line whenever a later filing changes one. Re-running adds only what is new. It shows the lines were not altered afterwards, not that a figure is right.",
+  proof_file: "Record a file's hash in a signed, append-only ledger, a backtest result or a returns file, so anyone can later check this exact file existed by then. Nothing else about the file is claimed.",
+  proof_verify: "Check a proof ledger from the file alone: every hash, order and signature, and any heads published elsewhere. Says which line first fails.",
+  proof_find: "Look up a file, company or concept in a proof ledger. No record means only that this ledger holds none, not that anything is wrong.",
+  league_new: "Start a paper league: a schedule of rounds and rules with a hash to publish. No prizes, no stakes and nobody's money.",
+  league_commit: "Commit a league entry before its round closes: only the hash of its CSV of ticker,score goes in the ledger, and the file is shown after the round. Only the latest commit counts, so revealing whichever of several did best is refused.",
+  league_score: "Score a paper league from its files and prices, repeatable by anyone: each entrant's rank correlation with what followed, set against the best luck gives across that many entrants, how different each is from the rest, and a paper book of the top entrants chosen on earlier rounds only.",
+  arena_new: "Start a paper market for AI agents to trade in: made-up assets and made-up money, with scripted traders, reproducible from a seed. Nothing here represents or reaches a real security, token or currency.",
+  arena_orders: "Send paper orders for an agent in an arena, for the coming auction. No short selling and no borrowing.",
+  arena_step: "Clear a paper arena's next call auctions at one price per asset, and show prices and standings. Paper only.",
+  crisis_replay: `Hold any strategy's daily returns against named market crises (${Object.values(CRISES).map((c) => c.what.replace(/^the /, "")).slice(0, 4).join(", ")} and others): its return, drawdown and worst day in each one its dates fully cover, and the crises it was not there for, listed as untested and never as passed.`,
+  cpcv: `Combinatorial purged cross-validation of a search: choose the best trial on training days, score it on held-out blocks, with purge and embargo at the edges, for every choice of blocks, stitched into whole paths. Returns the spread of out-of-sample Sharpes against the in-sample one. Splits can run as shards on other machines and merge back. ${CPCV_LIMITS_TEXT[1]}`,
+  backtest_signal: `Backtest a signal against your prices: rank, long and short quantiles, rebalance, trading only on what was known lag_days earlier, costs on actual trades. Every reply holds the result against the crises its dates cover and lists the ones it does not. With capital_usd and dollar_volume_file, orders fill only as far as the market traded, pay square-root impact, and the reply shows the Sharpe at each size the market can take. Pass ledger to judge the best of a search against all of it. ${ENGINE_LIMITS_TEXT[1]}`,
 });
 
 export async function toolPitFactor(session, args) {
@@ -141,23 +167,57 @@ export async function toolPitFactor(session, args) {
   });
 }
 
+const CAPACITY_LADDER = Object.freeze([1e5, 1e6, 1e7, 1e8, 1e9]);
+
 export async function toolBacktestSignal(session, args) {
   const a = backtestInput.parse(args);
   const prices = readPanel(a.prices_file, "prices_file");
   const signal = readPanel(a.signal_file, "signal_file");
   const tickers = prices.tickers.filter((t) => signal.tickers.includes(t));
   const cfg = { rebalance: a.rebalance ?? "monthly", lagDays: a.lag_days ?? 1, side: a.side ?? "long_short", quantile: a.quantile ?? 0.2, costBps: a.cost_bps ?? 10, minNames: a.min_names ?? 5, periodsPerYear: a.periods_per_year ?? 252 };
-  const result = runBacktest({ dates: prices.dates, tickers, prices: prices.values, signalDates: signal.dates, signals: signal.values, ...cfg });
+  if (a.capital_usd && !a.dollar_volume_file) throw new RangeError("capital_usd needs dollar_volume_file: without volume nothing says how much the market can take");
+  if (a.dollar_volume_file && !a.capital_usd) throw new RangeError("dollar_volume_file needs capital_usd: volume only matters at a size");
+  const volumes = a.dollar_volume_file ? readPanel(a.dollar_volume_file, "dollar_volume_file") : null;
+  if (volumes && volumes.dates.join() !== prices.dates.join()) throw new RangeError("dollar_volume_file must have the same dates as prices_file");
+  const size = volumes ? { dollarVolumes: volumes.values, maxParticipation: a.max_participation ?? 0.1, impactCoefficient: a.impact_coefficient ?? 1 } : {};
+  const run = (capital) => runBacktest({ dates: prices.dates, tickers, prices: prices.values, signalDates: signal.dates, signals: signal.values, ...cfg, ...size, ...(capital ? { capital } : {}) });
+  const result = run(a.capital_usd);
   const stats = describe(result);
-  const settings = { rebalance: cfg.rebalance, lag_days: cfg.lagDays, side: cfg.side, quantile: cfg.quantile, cost_bps: cfg.costBps, min_names: cfg.minNames };
+  const crises = crisisReplay({ dates: result.dates, returns: result.returns, ...(a.crisis_drawdown_limit ? { limit: a.crisis_drawdown_limit } : {}) });
+  const capacity = a.capital_usd ? CAPACITY_LADDER.map((capital) => {
+    const r = run(capital), d = describe(r);
+    // A book that cannot fill holds stale positions, and its Sharpe can even rise: not a figure to choose a size by.
+    const tradable = r.liquidity.verdict === "tradable";
+    return { capital_usd: capital, sharpe_annualized: tradable ? d.sharpe_annualized : null, annualized_return: tradable ? d.annualized_return : null, fill_ratio: r.liquidity.fill_ratio, impact_paid: r.liquidity.impact_paid, verdict: r.liquidity.verdict };
+  }) : null;
+  const settings = { rebalance: cfg.rebalance, lag_days: cfg.lagDays, side: cfg.side, quantile: cfg.quantile, cost_bps: cfg.costBps, min_names: cfg.minNames, ...(a.capital_usd ? { capital_usd: a.capital_usd, max_participation: size.maxParticipation, impact_coefficient: size.impactCoefficient } : {}) };
   let search = null;
   if (a.ledger) {
-    const label = a.label ?? `${a.signal_file.split("/").pop()} ${cfg.side} q${cfg.quantile} ${cfg.rebalance} lag${cfg.lagDays} ${cfg.costBps}bps`;
+    const label = a.label ?? `${a.signal_file.split("/").pop()} ${cfg.side} q${cfg.quantile} ${cfg.rebalance} lag${cfg.lagDays} ${cfg.costBps}bps${a.capital_usd ? ` $${a.capital_usd}` : ""}`;
     const r = recordTrial(session.ledgerDir, { ledger: a.ledger, label, returns: result.returns, periods_per_year: cfg.periodsPerYear, params: { ...settings, signal_file: a.signal_file } });
     search = { ledger: r.ledger, trial: r.trial, trials: r.trials, best: r.best, deflated: r.deflated, overfitting: r.overfitting, plain_reading: r.plain_reading };
   }
   const plain = `${stats.first_date} to ${stats.last_date}, ${tickers.length} tickers: annualized Sharpe ${stats.sharpe_annualized?.toFixed(2)}, return ${(100 * (stats.annualized_return ?? 0)).toFixed(1)}% a year, worst drawdown ${(100 * stats.max_drawdown).toFixed(1)}%, turnover ${stats.turnover_per_year?.toFixed(1)}x a year after ${cfg.costBps} bps costs. Every trade used signals at least ${stats.causality.min_days_signal_to_trade} calendar days old.`;
-  return text({ settings, tickers: tickers.length, ...stats, plain_reading: plain, ...(search ? { search } : {}), limits: ENGINE_LIMITS_TEXT });
+  const fails = [
+    ...(result.liquidity?.verdict === "too_big" ? [`Too big to trade: at $${a.capital_usd.toLocaleString("en-US")} only ${(100 * result.liquidity.fill_ratio).toFixed(0)}% of the wanted trading could fill; the figures below are for the smaller book that did.`] : []),
+    ...crises.tested.filter((c) => c.ruptured).map((c) => `Ruptured in ${c.what}: a ${(100 * c.drawdown).toFixed(0)}% drawdown against a ${(100 * crises.drawdown_limit).toFixed(0)}% limit.`),
+  ];
+  const coverage = `Crises: ${crises.tested.length} covered by these dates, ${crises.untested.length} untested${crises.untested.length ? ` (not having been there is not surviving them)` : ""}.`;
+  return text({ settings, tickers: tickers.length, fails, ...stats, crises, ...(result.liquidity ? { liquidity: result.liquidity, capacity } : {}), plain_reading: [...fails, plain, coverage].join(" "), ...(search ? { search } : {}), limits: ENGINE_LIMITS_TEXT });
+}
+
+export async function toolCrisisReplay(args) {
+  const a = crisisInput.parse(args);
+  const p = readPanel(a.returns_file, "returns_file");
+  if (p.tickers.length > 50) throw new RangeError("returns_file has more than 50 columns; crisis_replay takes at most 50");
+  const series = p.tickers.map((name) => {
+    // A series counts as there from its first value to its last; blank days in between earn nothing.
+    const v = p.values[name], first = v.findIndex((x) => x !== null), last = v.findLastIndex((x) => x !== null);
+    if (first < 0) return { name, verdict: "untested", tested: [], untested: Object.entries(CRISES).map(([id, c]) => ({ id, what: c.what, from: c.from, to: c.to })) };
+    return { name, ...crisisReplay({ dates: p.dates.slice(first, last + 1), returns: v.slice(first, last + 1).map((x) => x ?? 0), ...(a.drawdown_limit ? { limit: a.drawdown_limit } : {}) }) };
+  });
+  const ruptured = series.filter((s) => s.verdict === "ruptured");
+  return text({ series, plain_reading: `${series.length} ${series.length === 1 ? "strategy" : "strategies"} held against ${Object.keys(CRISES).length} crises: ${ruptured.length} ruptured${ruptured.length ? ` (${ruptured.slice(0, 5).map((s) => s.name).join(", ")})` : ""}. A crisis outside a strategy's dates is untested, not passed; surviving past crises says nothing about the next one.` });
 }
 
 function readGroups(path) {
@@ -224,6 +284,18 @@ export function registerTools(server, session) {
   tool("list_factors", "Point-in-time factors", z.object({}).strict(), READ_ONLY, async () => text({ factors: Object.fromEntries(Object.entries(FACTORS).map(([k, v]) => [k, v.meaning])), plus: "level:<measure> for any annual measure (revenue, net_income, assets, equity, operating_cash_flow, ...)", limits: PIT_LIMITS_TEXT }));
   tool("pit_factor", "Build a point-in-time factor", pitInput, { ...WRITES_LOCAL, openWorldHint: true }, (args) => toolPitFactor(session, args));
   tool("backtest_signal", "Backtest a signal without lookahead", backtestInput, WRITES_LOCAL, (args) => toolBacktestSignal(session, args));
+  tool("proof_filings", "Add company filings to a proof ledger", proofFilingsInput, { ...WRITES_LOCAL, openWorldHint: true }, async (args) => text(await proofFilings(session.markets ??= marketsSession(), args)));
+  tool("proof_file", "Record a file in a proof ledger", proofFileInput, WRITES_LOCAL, async (args) => text(proofFile(args)));
+  tool("proof_verify", "Verify a proof ledger", proofVerifyInput, READ_ONLY, async (args) => { const a = proofVerifyInput.parse(args); return text(verifyLedger(a.ledger_file, a.anchors ?? [])); });
+  tool("proof_find", "Look up a proof ledger", proofFindInput, READ_ONLY, async (args) => text(proofFind(args)));
+  tool("league_new", "Start a paper league", leagueNewInput, WRITES_LOCAL, async (args) => text(leagueNew(args)));
+  tool("league_commit", "Commit a league entry", leagueCommitInput, WRITES_LOCAL, async (args) => text(leagueCommit(args)));
+  tool("league_score", "Score a paper league", leagueScoreInput, READ_ONLY, async (args) => text(leagueScore(args)));
+  tool("arena_new", "Start a paper arena", arenaNewInput, WRITES_LOCAL, async (args) => text(arenaNew(args)));
+  tool("arena_orders", "Send paper orders to an arena", arenaOrdersInput, WRITES_LOCAL, async (args) => text(arenaOrders(args)));
+  tool("arena_step", "Clear a paper arena", arenaStepInput, WRITES_LOCAL, async (args) => text(arenaStep(args)));
+  tool("crisis_replay", "Replay strategies through named crises", crisisInput, READ_ONLY, (args) => toolCrisisReplay(args));
+  tool("cpcv", "Combinatorial purged cross-validation", cpcvInput, WRITES_LOCAL, async (args) => text(cpcv(args)));
   tool("price_panel", "Build a price panel", panelInput, { ...WRITES_LOCAL, openWorldHint: true }, async (args) => text(await buildPanel(session.markets ??= marketsSession(), args)));
   tool("breadth_signals", "Breadth lab signals", z.object({}).strict(), READ_ONLY, async () => text({ signals: signalCatalog(), next: "breadth_book with your prices_file (and groups_file, dollar_volume_file) builds a sleeve per signal per group.", limits: BREADTH_LIMITS_TEXT }));
   tool("breadth_book", "Breadth book of sleeves", breadthInput, WRITES_LOCAL, (args) => toolBreadthBook(session, args));