canli-validation-mcp 0.4.0 → 0.6.0

package/src/local/js/selection-risk-core.js

@@ -0,0 +1,197 @@
+// =============================================================================
+// selection-risk-core.js
+// -----------------------------------------------------------------------------
+// The engine behind /tools/selection-risk: a sandbox where you search a strategy
+// space over a series that provably has NO edge, and watch what your best result
+// is worth once the search is counted.
+//
+// WHY SYNTHETIC, AND WHY THAT IS NOT A COMPROMISE.
+// Two reasons, and the second is the better one.
+//
+//   1. Rights. config/data_source_rights_policy.json records every market-data
+//      source this project uses as PROHIBITED or WITHHELD for raw redistribution,
+//      with a project default of "do not bundle raw third-party rows". Shipping
+//      real bars into a browser is not available, and no amount of wanting it
+//      changes that.
+//
+//   2. Proof. On real data you can always argue the edge you found was real. Here
+//      the generator is a driftless random walk, so the true Sharpe is ZERO by
+//      construction. Every good result the visitor finds is therefore luck, with
+//      no room for debate, which is exactly the point being demonstrated. A real
+//      series would make the lesson weaker, not stronger.
+//
+// NO-LOOKAHEAD, the same rule the engine enforces. A signal is computed from
+// closes up to and including bar t. The position it implies is held from the OPEN
+// of bar t+1 to the OPEN of bar t+2. A decision never touches a price from its own
+// bar or earlier than its own execution. `assertNoLookahead` below is the
+// mechanical statement of that, and the test suite perturbs a bar to prove the
+// property is real rather than asserted.
+// =============================================================================
+
+/** Deterministic PRNG (mulberry32). Same seed, same series, on every machine. */
+export function makeRandom(seed) {
+  let a = seed >>> 0;
+  return function next() {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Box-Muller, drawing from a supplied uniform generator so it stays deterministic. */
+function gaussian(next) {
+  let u = 0;
+  let v = 0;
+  while (u === 0) u = next();
+  while (v === 0) v = next();
+  return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v);
+}
+
+/**
+ * A driftless geometric random walk, as OHLC-style bars with an open and a close.
+ *
+ * `drift` exists only so a caller can demonstrate the contrast; the sandbox pins it
+ * to zero, which is what makes the true Sharpe zero.
+ */
+export function generateSeries({ seed, bars = 750, volatility = 0.011, drift = 0, gapVolatility = 0 }) {
+  if (!Number.isInteger(bars) || bars < 32) throw new Error("bars must be an integer >= 32");
+  if (!(volatility > 0)) throw new Error("volatility must be positive");
+  const next = makeRandom(seed);
+  const out = [];
+  let level = 100;
+  for (let i = 0; i < bars; i += 1) {
+    // The overnight gap. With gapVolatility at zero, open[i+1] equals close[i] and
+    // the series is continuous, which is what the Selection Risk Lab wants: it
+    // studies search, not execution, and a gap would only add noise there.
+    //
+    // The Execution Reality Lab needs a non-zero gap, because without one "fill at
+    // the next open" and "fill at the decision close" are the SAME price and the
+    // most important comparison on that page silently collapses to a tie.
+    if (gapVolatility > 0) level *= Math.exp(gapVolatility * gaussian(next));
+    const open = level;
+    level *= Math.exp(drift + volatility * gaussian(next));
+    out.push({ i, open, close: level });
+  }
+  return out;
+}
+
+/** Simple moving average of `closes` ending at index `end`, inclusive. */
+function sma(closes, end, window) {
+  if (end + 1 < window) return Number.NaN;
+  let total = 0;
+  for (let k = end - window + 1; k <= end; k += 1) total += closes[k];
+  return total / window;
+}
+
+/**
+ * A fast/slow moving-average crossover, run under the engine's fill rule.
+ *
+ * Returns per-period returns, the equity path, and the summary statistics. The
+ * returned `decisions` array records, for each realised return, which bar the
+ * decision was taken on and which bars priced it, so a test can assert the
+ * causality rather than trust the comment above it.
+ */
+export function runCrossover({ series, fast, slow, costBps = 0 }) {
+  if (!Number.isInteger(fast) || !Number.isInteger(slow)) throw new Error("windows must be integers");
+  if (fast < 1 || slow < 2) throw new Error("windows must be positive");
+  if (fast >= slow) throw new Error("fast window must be shorter than slow");
+  const closes = series.map((b) => b.close);
+  const cost = costBps / 10000;
+
+  const returns = [];
+  const decisions = [];
+  let previousPosition = 0;
+
+  // t is the DECISION bar. Execution spans open[t+1] -> open[t+2], so the loop
+  // stops early enough that both exist.
+  for (let t = slow - 1; t + 2 < series.length; t += 1) {
+    const position = sma(closes, t, fast) > sma(closes, t, slow) ? 1 : 0;
+    const entry = series[t + 1].open;
+    const exit = series[t + 2].open;
+    const gross = position * (exit / entry - 1);
+    const turnover = Math.abs(position - previousPosition);
+    const net = gross - turnover * cost;
+    returns.push(net);
+    decisions.push({ decisionBar: t, entryBar: t + 1, exitBar: t + 2, position });
+    previousPosition = position;
+  }
+
+  let equity = 1;
+  const curve = [equity];
+  for (const r of returns) {
+    equity *= 1 + r;
+    curve.push(equity);
+  }
+
+  return {
+    returns,
+    curve,
+    decisions,
+    trades: decisions.reduce(
+      (n, d, k) => n + (k === 0 ? d.position : Math.abs(d.position - decisions[k - 1].position)),
+      0,
+    ),
+    ...summarize(returns, curve),
+  };
+}
+
+/** Per-period Sharpe, its annualised form, and the worst peak-to-trough drop. */
+export function summarize(returns, curve) {
+  const n = returns.length;
+  if (n < 2) return { sharpePerPeriod: 0, sharpeAnnualised: 0, maxDrawdown: 0, totalReturn: 0 };
+  const mean = returns.reduce((a, b) => a + b, 0) / n;
+  const variance = returns.reduce((a, b) => a + (b - mean) ** 2, 0) / (n - 1);
+  const sd = Math.sqrt(variance);
+  const sharpePerPeriod = sd > 0 ? mean / sd : 0;
+  let peak = curve[0];
+  let maxDrawdown = 0;
+  for (const value of curve) {
+    if (value > peak) peak = value;
+    const drop = peak > 0 ? 1 - value / peak : 0;
+    if (drop > maxDrawdown) maxDrawdown = drop;
+  }
+  // Sample skewness and NON-EXCESS kurtosis, which is what the deflation wants:
+  // a Gaussian scores 3 here, not 0. Handing it excess kurtosis silently shifts
+  // the estimator variance and the answer stays plausible, so the convention is
+  // named rather than assumed.
+  const m3 = returns.reduce((a, b) => a + (b - mean) ** 3, 0) / n;
+  const m4 = returns.reduce((a, b) => a + (b - mean) ** 4, 0) / n;
+  const populationSd = Math.sqrt(returns.reduce((a, b) => a + (b - mean) ** 2, 0) / n);
+  const skew = populationSd > 0 ? m3 / populationSd ** 3 : 0;
+  const nonExcessKurtosis = populationSd > 0 ? m4 / populationSd ** 4 : 3;
+
+  return {
+    sharpePerPeriod,
+    // 252 periods, the convention for a daily-frequency series.
+    sharpeAnnualised: sharpePerPeriod * Math.sqrt(252),
+    maxDrawdown,
+    totalReturn: curve[curve.length - 1] - 1,
+    skew,
+    nonExcessKurtosis,
+    observations: n,
+  };
+}
+
+/**
+ * The mechanical no-lookahead statement: for every realised return, the decision
+ * bar strictly precedes the bar whose open is paid, which strictly precedes the
+ * bar whose open is received.
+ */
+export function assertNoLookahead(result) {
+  for (const d of result.decisions) {
+    if (!(d.decisionBar < d.entryBar && d.entryBar < d.exitBar)) {
+      return { ok: false, offending: d };
+    }
+  }
+  return { ok: true, offending: null };
+}
+
+/** Sample variance of a list of Sharpe ratios, the V[SR] the deflation needs. */
+export function sharpeVariance(sharpes) {
+  const n = sharpes.length;
+  if (n < 2) return 0;
+  const mean = sharpes.reduce((a, b) => a + b, 0) / n;
+  return sharpes.reduce((a, b) => a + (b - mean) ** 2, 0) / (n - 1);
+}

package/src/local/js/student-t.js

@@ -0,0 +1,139 @@
+// Student's t distribution to full double precision, for the haircut Sharpe ratio (Harvey and Liu,
+// "Backtesting", 2015), which tests a Sharpe ratio's t-statistic against t with N - 1 degrees of
+// freedom. Checked against R's pt and qt (js/fixtures/student-t-reference.json).
+//
+// The upper tail is computed directly, never as 1 - cdf: the authors' Haircut_SR.m computes
+// 2 * (1 - tcdf(t, N - 1)), which rounds to 0 once t passes about 8 and makes the haircut Sharpe
+// ratio infinite. P(T > t) = I_x(df / 2, 1 / 2) / 2 with x = df / (df + t^2) keeps full relative
+// precision far into the tail.
+
+const HALF_LOG_TWO_PI = 0.5 * Math.log(2 * Math.PI);
+
+// Stirling's correction ln Gamma(x) - [(x - 1/2) ln x - x + ln(2 pi) / 2], for x >= 10: the series
+// to the 1/x^13 term, whose error there is below 1e-16.
+function stirlingCorrection(x) {
+  const inv = 1 / x;
+  const inv2 = inv * inv;
+  return inv * (1 / 12 + inv2 * (-1 / 360 + inv2 * (1 / 1260 + inv2 * (-1 / 1680 + inv2 * (1 / 1188 + inv2 * (-691 / 360360 + inv2 * (1 / 156)))))));
+}
+
+// ln Gamma(x) for x > 0: shifted to x >= 10, where the series applies; ln Gamma(x) = ln Gamma(x + 1) -
+// ln x undoes the shift.
+export function logGamma(value) {
+  let x = Number(value);
+  if (!(x > 0) || !Number.isFinite(x)) throw new RangeError("logGamma needs a positive finite number");
+  let shift = 0;
+  while (x < 10) {
+    shift -= Math.log(x);
+    x += 1;
+  }
+  return (x - 0.5) * Math.log(x) - x + HALF_LOG_TWO_PI + stirlingCorrection(x) + shift;
+}
+
+// ln Gamma(a + b) - ln Gamma(a) without subtracting two large numbers when a is large (degrees of
+// freedom in the thousands): (a - 1/2) ln(1 + b/a) + b ln(a + b) - b + the two corrections.
+function logGammaRatio(a, b) {
+  if (a < 10) return logGamma(a + b) - logGamma(a);
+  return (a - 0.5) * Math.log1p(b / a) + b * Math.log(a + b) - b + stirlingCorrection(a + b) - stirlingCorrection(a);
+}
+
+// Continued fraction for the incomplete beta function (modified Lentz).
+function betaFraction(a, b, x) {
+  const TINY = 1e-300;
+  const qab = a + b;
+  const qap = a + 1;
+  const qam = a - 1;
+  let c = 1;
+  let d = 1 - (qab * x) / qap;
+  if (Math.abs(d) < TINY) d = TINY;
+  d = 1 / d;
+  let h = d;
+  for (let m = 1; m <= 100000; m += 1) {
+    const m2 = 2 * m;
+    let aa = (m * (b - m) * x) / ((qam + m2) * (a + m2));
+    d = 1 + aa * d;
+    if (Math.abs(d) < TINY) d = TINY;
+    c = 1 + aa / c;
+    if (Math.abs(c) < TINY) c = TINY;
+    d = 1 / d;
+    h *= d * c;
+    aa = (-(a + m) * (qab + m) * x) / ((a + m2) * (qap + m2));
+    d = 1 + aa * d;
+    if (Math.abs(d) < TINY) d = TINY;
+    c = 1 + aa / c;
+    if (Math.abs(c) < TINY) c = TINY;
+    d = 1 / d;
+    const delta = d * c;
+    h *= delta;
+    if (Math.abs(delta - 1) < 1e-16) return h;
+  }
+  throw new Error("The incomplete beta continued fraction did not converge");
+}
+
+// Regularized incomplete beta I_x(a, b) for b = 1/2 (all Student t needs), with y = 1 - x and both
+// logarithms passed separately so that nothing is lost to cancellation when x or y is tiny.
+function incompleteBeta(x, y, logX, logY, a, b) {
+  if (x <= 0) return 0;
+  if (y <= 0) return 1;
+  const front = Math.exp(logGammaRatio(a, b) - logGamma(b) + a * logX + b * logY);
+  if (x < (a + 1) / (a + b + 2)) return (front * betaFraction(a, b, x)) / a;
+  return 1 - (front * betaFraction(b, a, y)) / b;
+}
+
+function requireDf(df) {
+  const v = Number(df);
+  if (!(v > 0) || !Number.isFinite(v)) throw new RangeError("Degrees of freedom must be a positive finite number");
+  return v;
+}
+
+// P(T > t) for T ~ t(df).
+export function studentTUpper(t, df) {
+  const v = requireDf(df);
+  const value = Number(t);
+  if (Number.isNaN(value)) return Number.NaN;
+  if (value === 0) return 0.5;
+  if (value === Infinity) return 0;
+  if (value === -Infinity) return 1;
+  const t2 = value * value;
+  const logX = -Math.log1p(t2 / v);
+  const logY = Math.log(t2) - Math.log(v + t2);
+  const half = 0.5 * incompleteBeta(Math.exp(logX), t2 / (v + t2), logX, logY, v / 2, 0.5);
+  return value > 0 ? half : 1 - half;
+}
+
+export function studentTPdf(t, df) {
+  const v = requireDf(df);
+  const value = Number(t);
+  return Math.exp(logGammaRatio(v / 2, 0.5) - 0.5 * Math.log(v * Math.PI) - ((v + 1) / 2) * Math.log1p((value * value) / v));
+}
+
+// The t with P(T > t) = upper: bisection on a bracket (the tail can be very heavy for small df),
+// then Newton steps on log P(T > t), which is smooth and keeps relative precision in the tail.
+export function studentTQuantileUpper(upper, df) {
+  const v = requireDf(df);
+  const p = Number(upper);
+  if (!(p > 0 && p < 1)) throw new RangeError("The upper-tail probability must be strictly between 0 and 1");
+  if (p === 0.5) return 0;
+  if (p > 0.5) return -studentTQuantileUpper(1 - p, v);
+  let lo = 0;
+  let hi = 1;
+  while (studentTUpper(hi, v) > p) {
+    lo = hi;
+    hi *= 2;
+    if (!Number.isFinite(hi)) throw new RangeError("The upper-tail probability is too small for these degrees of freedom");
+  }
+  for (let i = 0; i < 200 && hi - lo > 1e-12 * hi; i += 1) {
+    const mid = 0.5 * (lo + hi);
+    if (studentTUpper(mid, v) > p) lo = mid;
+    else hi = mid;
+  }
+  let t = 0.5 * (lo + hi);
+  const target = Math.log(p);
+  for (let i = 0; i < 4; i += 1) {
+    const tail = studentTUpper(t, v);
+    const step = (Math.log(tail) - target) / (-studentTPdf(t, v) / tail);
+    if (!Number.isFinite(step)) break;
+    t -= step;
+  }
+  return t;
+}

package/src/local/js/validate/backtest-length.js

@@ -0,0 +1,61 @@
+// js/validate/backtest-length.js
+// The pure computation behind POST /api/v1/validate/backtest-length, shared by the API route and the
+// MCP package's local mode (mcp/src/local mirrors it byte for byte), so the two cannot disagree.
+import { expectedMaxStandardNormal, maximumIndependentTrials, minimumBacktestLength } from "../dsr-core.js";
+
+// Minimum Backtest Length: Bailey, Borwein, López de Prado and Zhu, "Pseudo-Mathematics and
+// Financial Charlatanism" (Notices of the AMS, 2014), Theorem 3.1, checked against the paper's own
+// statements in js/minbtl-paper-vectors.test.js. With N independent trials and a target in-sample
+// Sharpe, how many years a backtest needs before the best trial is not expected to reach the target
+// by luck; with the backtest's years, how many independent trials those years allow.
+
+export function compute(body) {
+  const hasTrials = body.effective_independent_trials !== undefined;
+  const hasYears = body.backtest_years !== undefined;
+  if (!hasTrials && !hasYears) throw new RangeError("Send effective_independent_trials, backtest_years, or both");
+  const inputs = { target_sharpe_annualized: body.target_sharpe_annualized === undefined ? 1 : Number(body.target_sharpe_annualized) };
+  if (!(inputs.target_sharpe_annualized > 0 && inputs.target_sharpe_annualized <= 10)) throw new RangeError("target_sharpe_annualized must be greater than 0 and at most 10");
+  if (hasTrials) {
+    inputs.effective_independent_trials = Number(body.effective_independent_trials);
+    if (!Number.isInteger(inputs.effective_independent_trials) || inputs.effective_independent_trials < 2 || inputs.effective_independent_trials > 1e9) {
+      throw new RangeError("effective_independent_trials must be an integer from 2 to 1000000000");
+    }
+  }
+  if (hasYears) {
+    inputs.backtest_years = Number(body.backtest_years);
+    if (!(inputs.backtest_years > 0 && inputs.backtest_years <= 1000)) throw new RangeError("backtest_years must be greater than 0 and at most 1000");
+  }
+  const result = {};
+  if (hasTrials) {
+    const minimum = minimumBacktestLength({ trials: inputs.effective_independent_trials, targetSharpe: inputs.target_sharpe_annualized });
+    result.minimum_backtest_years = minimum.years;
+    result.upper_bound_years = minimum.upper_bound_years;
+  }
+  if (hasYears) {
+    result.maximum_independent_trials = maximumIndependentTrials({ years: inputs.backtest_years, targetSharpe: inputs.target_sharpe_annualized });
+  }
+  if (hasTrials && hasYears) {
+    result.expected_max_sharpe_annualized = expectedMaxStandardNormal(inputs.effective_independent_trials) / Math.sqrt(inputs.backtest_years);
+    result.long_enough = inputs.backtest_years >= result.minimum_backtest_years;
+  }
+  return { derived_inputs: inputs, result, plain_reading: reading(inputs, result) };
+}
+
+function reading(inputs, r) {
+  const sharpe = (x) => String(Number(Number(x).toFixed(3)));
+  const target = sharpe(inputs.target_sharpe_annualized);
+  const parts = [];
+  if (r.minimum_backtest_years !== undefined) {
+    parts.push(`With ${inputs.effective_independent_trials} independent trials, the best one is expected to show an in-sample Sharpe of ${target} by luck alone unless the backtest covers at least ${r.minimum_backtest_years.toFixed(2)} years.`);
+  }
+  if (r.maximum_independent_trials !== undefined) {
+    parts.push(r.maximum_independent_trials === 1
+      ? `${sharpe(inputs.backtest_years)} years of backtest is too short for even two independent trials: their best is expected to reach a Sharpe of ${target} by luck.`
+      : `${sharpe(inputs.backtest_years)} years of backtest allows at most ${r.maximum_independent_trials} independent trials before the best is expected to reach a Sharpe of ${target} by luck.`);
+  }
+  if (r.expected_max_sharpe_annualized !== undefined) {
+    parts.push(`Over ${sharpe(inputs.backtest_years)} years, the best of ${inputs.effective_independent_trials} skill-less trials is expected to show a Sharpe of ${sharpe(r.expected_max_sharpe_annualized)}.`);
+  }
+  parts.push("Meeting this length is necessary, not sufficient: a backtest can still be overfit.");
+  return parts.join(" ");
+}

package/src/local/js/validate/breadth.js

@@ -0,0 +1,24 @@
+// js/validate/breadth.js
+// The pure computation behind POST /api/v1/validate/breadth, shared by the API route and the
+// MCP package's local mode (mcp/src/local mirrors it byte for byte), so the two cannot disagree.
+import { bookSharpe, breadthCeiling, ceilingCaptured, sleevesRequired } from "../breadth-core.js";
+
+export function compute(body) {
+  const sleeveSharpe = Number(body.sleeve_sharpe);
+  const correlation = Number(body.average_pairwise_correlation);
+  if (!Number.isFinite(sleeveSharpe) || sleeveSharpe <= 0) throw new RangeError("sleeve_sharpe must be a positive number");
+  if (!Number.isFinite(correlation) || correlation < -1 || correlation > 1) throw new RangeError("average_pairwise_correlation must be between -1 and 1");
+  const sleeves = body.sleeves === undefined ? null : Number(body.sleeves);
+  if (sleeves !== null && (!Number.isInteger(sleeves) || sleeves < 1 || sleeves > 500)) throw new RangeError("sleeves must be an integer from 1 to 500");
+  const target = body.target === undefined ? null : Number(body.target);
+  if (target !== null && !(target > 0)) throw new RangeError("target must be a positive Sharpe");
+  const ceiling = breadthCeiling({ sleeveSharpe, correlation });
+  const out = { identity: "S_book = s_bar * sqrt(N / (1 + (N - 1) * rho_bar)); ceiling as N grows is s_bar / sqrt(rho_bar)", ceiling: Number.isFinite(ceiling) ? ceiling : null, ceiling_is_unbounded: !Number.isFinite(ceiling) };
+  if (sleeves !== null) out.book = { sleeves, book_sharpe: bookSharpe({ sleeveSharpe, sleeves, correlation }), ceiling_captured: Number.isFinite(ceiling) ? ceilingCaptured({ sleeveSharpe, sleeves, correlation }) : null };
+  if (target !== null) {
+    const req = sleevesRequired({ sleeveSharpe, correlation, target });
+    out.target = { target, reachable: req.reachable, sleeves_required: req.sleeves, note: req.reachable ? "At this per-sleeve quality and correlation the target is reachable with the stated sleeve count." : "No number of sleeves of this quality at this correlation reaches the target; raise per-sleeve quality or lower correlation." };
+  }
+  out.plain_reading = out.ceiling_is_unbounded ? "With average pairwise correlation at or below zero the book Sharpe has no ceiling from breadth alone; correlation this low is rare and should be checked in stress." : `Adding sleeves of this quality can never take the book above a Sharpe of ${ceiling.toFixed(3)}. Quality and correlation set the ceiling; count only approaches it.`;
+  return out;
+}

package/src/local/js/validate/deflated-sharpe.js

@@ -0,0 +1,28 @@
+// js/validate/deflated-sharpe.js
+// The pure computation behind POST /api/v1/validate/deflated-sharpe, shared by the API route and the
+// MCP package's local mode (mcp/src/local mirrors it byte for byte), so the two cannot disagree.
+import { calculateDsr } from "../dsr-core.js";
+import { dsrFromReturns } from "../moments-core.js";
+import { LIMITS } from "../../api/_lib/limits.js";
+
+const CONTRACT_KEYS = ["observed_sharpe_annualized", "observations", "periods_per_year", "skew", "non_excess_kurtosis", "effective_independent_trials", "cross_trial_sharpe_sd_annualized"];
+
+export function compute(body) {
+  const hasSeries = Array.isArray(body.returns);
+  const hasContract = CONTRACT_KEYS.every((k) => body[k] !== undefined);
+  if (hasSeries && body.observed_sharpe_annualized !== undefined) throw new RangeError("Send either a return series or the contract inputs, not both");
+  if (hasSeries) {
+    if (body.returns.length > LIMITS.max_observations) throw new RangeError(`A series may hold at most ${LIMITS.max_observations} observations`);
+    const { derived_inputs, result } = dsrFromReturns(body);
+    return { input_mode: "return_series", derived_inputs, result, plain_reading: reading(result) };
+  }
+  if (!hasContract) throw new RangeError(`Send a return series (returns, periods_per_year, effective_independent_trials, cross_trial_sharpe_sd_annualized) or all of: ${CONTRACT_KEYS.join(", ")}`);
+  const inputs = Object.fromEntries(CONTRACT_KEYS.map((k) => [k, body[k]]));
+  const result = calculateDsr(inputs);
+  return { input_mode: "contract_inputs", derived_inputs: inputs, result, plain_reading: reading(result) };
+}
+
+function reading(r) {
+  const pct = (x) => `${(x * 100).toFixed(1)} percent`;
+  return `Counting only sample uncertainty, the probability this Sharpe is above zero is ${pct(r.psr_against_zero)}. Deflated for the best-by-luck Sharpe the declared search would produce (${r.expected_max_sharpe_annualized.toFixed(3)} annualised), it is ${pct(r.deflated_sharpe_ratio)}. Neither number is a forecast.`;
+}

package/src/local/js/validate/haircut-sharpe.js

@@ -0,0 +1,54 @@
+// js/validate/haircut-sharpe.js
+// The pure computation behind POST /api/v1/validate/haircut-sharpe, shared by the API route and the
+// MCP package's local mode (mcp/src/local mirrors it byte for byte), so the two cannot disagree.
+import { haircutSharpe } from "../haircut-core.js";
+
+// The haircut Sharpe ratio of Harvey and Liu, "Backtesting" (2015), checked against the authors'
+// Haircut_SR.m and R in js/haircut-paper-vectors.test.js. Bonferroni and independent-test adjustments
+// need only the number of tests; Holm and BHY need the other tests' Sharpe ratios, which the caller
+// knows (the authors simulate them from a published factor model when they are unknown).
+
+const MAX_OTHERS = 10000;
+
+export function compute(body) {
+  const missing = ["observed_sharpe_annualized", "periods_per_year", "observations"].filter((k) => body[k] === undefined);
+  if (missing.length) throw new RangeError(`Missing required fields: ${missing.join(", ")}`);
+  const others = body.other_sharpe_ratios_annualized;
+  if (others !== undefined && (!Array.isArray(others) || others.length < 1 || others.length > MAX_OTHERS)) {
+    throw new RangeError(`other_sharpe_ratios_annualized must be an array of 1 to ${MAX_OTHERS} Sharpe ratios`);
+  }
+  if (others === undefined && body.tests === undefined) throw new RangeError("Send tests, other_sharpe_ratios_annualized, or both");
+  const inputs = {
+    observed_sharpe_annualized: Number(body.observed_sharpe_annualized),
+    periods_per_year: Number(body.periods_per_year),
+    observations: Number(body.observations),
+    autocorrelation: body.autocorrelation === undefined ? 0 : Number(body.autocorrelation),
+    ...(body.tests !== undefined ? { tests: Number(body.tests) } : {}),
+    ...(others !== undefined ? { other_tests: others.length } : {}),
+  };
+  if (!(inputs.observations <= 1000000)) throw new RangeError("observations must be at most 1000000");
+  const result = haircutSharpe({
+    sharpeAnnualized: inputs.observed_sharpe_annualized,
+    periodsPerYear: inputs.periods_per_year,
+    observations: inputs.observations,
+    tests: inputs.tests,
+    autocorrelation: inputs.autocorrelation,
+    otherSharpesAnnualized: others,
+  });
+  return { derived_inputs: inputs, result, plain_reading: reading(inputs, result) };
+}
+
+function reading(inputs, r) {
+  const num = (x, d = 3) => String(Number(Number(x).toFixed(d)));
+  const pct = (x) => `${(x * 100).toFixed(1)} percent`;
+  const p = (x) => (x < 0.0001 ? Number(x).toExponential(2) : num(x, 4));
+  const line = (name, a) => `${name} gives an adjusted p-value of ${p(a.adjusted_p)} and a haircut Sharpe of ${num(a.haircut_sharpe_annualized)}, a ${pct(a.haircut)} haircut`;
+  const corrected = inputs.autocorrelation !== 0 ? ` (${num(r.sharpe_annualized_corrected)} after the autocorrelation correction)` : "";
+  const parts = [
+    `Tested alone, an annualized Sharpe of ${num(inputs.observed_sharpe_annualized)}${corrected} over ${inputs.observations} observations has a p-value of ${p(r.p_value_single)}.`,
+    `Counting ${r.tests} tests, ${line("Bonferroni", r.bonferroni)}; treating the tests as independent ${line("", r.independent).trim()}.`,
+  ];
+  if (r.holm) parts.push(`With the other tests' own Sharpe ratios, ${line("Holm", r.holm)}, and ${line("BHY", r.bhy)}.`);
+  parts.push("The haircut counts only the tests declared; tests run and not counted are invisible to it.");
+  return parts.join(" ");
+}

package/src/local/js/validate/luck-trials.js

@@ -0,0 +1,63 @@
+// js/validate/luck-trials.js
+// The pure computation behind POST /api/v1/validate/luck-trials, shared by the API route and the
+// MCP package's local mode (mcp/src/local mirrors it byte for byte), so the two cannot disagree.
+import { luckEquivalentTrials, TRIAL_CAP } from "../luck-core.js";
+
+// Luck-equivalent trials (js/luck-core.js): how many skill-less strategies a search would have had
+// to try for its best to reach the observed Sharpe by luck. Calibrated by Monte Carlo in
+// js/luck-core.test.js; too kind to negatively skewed strategies, which the reading says when the
+// caller sends the skew.
+
+const NEGATIVE_SKEW = -0.5;
+
+export function compute(body) {
+  const missing = ["observed_sharpe_annualized", "periods_per_year", "observations"].filter((k) => body[k] === undefined);
+  if (missing.length) throw new RangeError(`Missing required fields: ${missing.join(", ")}`);
+  const inputs = {
+    observed_sharpe_annualized: Number(body.observed_sharpe_annualized),
+    periods_per_year: Number(body.periods_per_year),
+    observations: Number(body.observations),
+    ...(body.effective_independent_trials !== undefined ? { effective_independent_trials: Number(body.effective_independent_trials) } : {}),
+    ...(body.skew !== undefined ? { skew: Number(body.skew) } : {}),
+    ...(body.autocorrelation !== undefined ? { autocorrelation: Number(body.autocorrelation) } : {}),
+  };
+  if (!(Math.abs(inputs.observed_sharpe_annualized) <= 20)) throw new RangeError("observed_sharpe_annualized must be a number from -20 to 20");
+  if (!(inputs.periods_per_year > 0 && inputs.periods_per_year <= 100000)) throw new RangeError("periods_per_year must be greater than 0 and at most 100000");
+  if (!Number.isInteger(inputs.observations) || inputs.observations < 3 || inputs.observations > 1000000) throw new RangeError("observations must be an integer from 3 to 1000000");
+  const trials = inputs.effective_independent_trials;
+  if (trials !== undefined && (!Number.isInteger(trials) || trials < 1 || trials > 1e9)) throw new RangeError("effective_independent_trials must be an integer from 1 to 1000000000");
+  if (inputs.skew !== undefined && !Number.isFinite(inputs.skew)) throw new RangeError("skew must be a finite number");
+  if (inputs.autocorrelation !== undefined && !(inputs.autocorrelation > -1 && inputs.autocorrelation < 1)) throw new RangeError("autocorrelation must be strictly between -1 and 1");
+  const result = luckEquivalentTrials({ sharpe: inputs.observed_sharpe_annualized, observations: inputs.observations, periodsPerYear: inputs.periods_per_year, trials, autocorrelation: inputs.autocorrelation });
+  return { derived_inputs: inputs, result, plain_reading: reading(inputs, result) };
+}
+
+const whole = (n) => Math.floor(n).toLocaleString("en-US");
+
+function reading(inputs, r) {
+  const sharpe = String(Number(inputs.observed_sharpe_annualized.toFixed(3)));
+  const over = `over these ${inputs.observations} observations`;
+  const parts = [];
+  if (r.trials_for_five_percent >= TRIAL_CAP) {
+    parts.push(`Luck alone would need more than ${TRIAL_CAP.toExponential(0).replace("e+", "e")} skill-less strategies to reach a Sharpe of ${sharpe} ${over}.`);
+  } else if (r.trials_for_even_odds < 2) {
+    parts.push(`A single skill-less strategy shows a Sharpe of ${sharpe} or more ${over} with probability ${r.single_trial_probability.toFixed(3)}: luck alone readily explains it.`);
+  } else if (r.trials_for_five_percent < 1) {
+    parts.push(`The best of ${whole(r.trials_for_even_odds)} skill-less strategies reaches a Sharpe of ${sharpe} ${over} about half the time, and even one reaches it more than 5 percent of the time.`);
+  } else {
+    parts.push(`The best of ${whole(r.trials_for_even_odds)} skill-less strategies reaches a Sharpe of ${sharpe} ${over} about half the time; with at most ${whole(r.trials_for_five_percent)} tried, luck reaches it less than 5 percent of the time.`);
+  }
+  if (r.best_of_trials_probability !== undefined) {
+    parts.push(`With ${inputs.effective_independent_trials} independent trials, the chance that the best reaches it by luck is ${(r.best_of_trials_probability * 100).toPrecision(3)} percent.`);
+  }
+  if (inputs.skew !== undefined && inputs.skew < NEGATIVE_SKEW) {
+    parts.push(`With a return skew of ${inputs.skew}, these counts are too generous: negatively skewed returns reach high Sharpe ratios by luck more often than this assumes.`);
+  }
+  if (inputs.autocorrelation === undefined) {
+    parts.push("Without the returns' autocorrelation this assumes none; positively autocorrelated returns reach high Sharpe ratios by luck more often.");
+  } else if (inputs.autocorrelation !== 0) {
+    parts.push(`The Sharpe was first corrected for an autocorrelation of ${inputs.autocorrelation} (Lo, 2002), to ${String(Number((inputs.observed_sharpe_annualized * r.autocorrelation_factor).toFixed(3)))}.`);
+  }
+  parts.push("It counts independent trials; correlated trials count as fewer.");
+  return parts.join(" ");
+}

package/src/local/js/validate/overfitting.js

@@ -0,0 +1,29 @@
+// js/validate/overfitting.js
+// The pure computation behind POST /api/v1/validate/overfitting, shared by the API route and the
+// MCP package's local mode (mcp/src/local mirrors it byte for byte), so the two cannot disagree.
+import { pboCscv } from "../pbo-core.js";
+import { LIMITS } from "../../api/_lib/limits.js";
+
+const mean = (xs) => xs.reduce((a, b) => a + (Number.isFinite(b) ? b : 0), 0) / xs.length;
+
+export function compute(body) {
+  const { matrix, n_splits = 16, max_combinations = LIMITS.max_cscv_combinations, seed = 42 } = body;
+  if (!Array.isArray(matrix) || !Array.isArray(matrix[0])) throw new RangeError("matrix must be an array of rows, each a row of variant returns for one period");
+  if (matrix.length > LIMITS.max_observations) throw new RangeError(`A matrix may hold at most ${LIMITS.max_observations} rows`);
+  if (matrix[0].length > LIMITS.max_variants) throw new RangeError(`A matrix may hold at most ${LIMITS.max_variants} variants`);
+  if (!Number.isInteger(max_combinations) || max_combinations > LIMITS.max_cscv_combinations) throw new RangeError(`max_combinations may not exceed ${LIMITS.max_cscv_combinations}`);
+  const out = pboCscv(matrix, { nSplits: Number(n_splits), maxCombinations: max_combinations, seed: Number(seed) });
+  const sorted = [...out.lambdas].sort((a, b) => a - b);
+  const q = (p) => sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
+  const degraded = out.is_oos_pairs.filter(([i, o]) => o < i).length / out.is_oos_pairs.length;
+  return {
+    pbo: out.pbo,
+    n_combinations: out.n_combinations,
+    exhaustive: out.exhaustive,
+    sampler: out.exhaustive ? "all combinations enumerated in lexicographic order" : `${out.n_combinations} combinations drawn without replacement by mulberry32(seed=${Number(seed)}); the Python reference draws with numpy, so estimates agree within sampling noise, not bit for bit`,
+    block_length: out.block_length,
+    lambda_quantiles: { p05: q(0.05), p25: q(0.25), p50: q(0.5), p75: q(0.75), p95: q(0.95) },
+    is_oos_summary: { mean_is_sharpe_of_selected: mean(out.is_oos_pairs.map((p) => p[0])), mean_oos_sharpe_of_selected: mean(out.is_oos_pairs.map((p) => p[1])), share_oos_below_is: degraded },
+    plain_reading: `In ${(out.pbo * 100).toFixed(1)} percent of the ${out.n_combinations} in-sample and out-of-sample splits, the variant that looked best in sample ranked in the worse half out of sample. That share is the probability of backtest overfitting for this set of variants as submitted.`,
+  };
+}

package/src/local/js/validate/paper-evidence.js

@@ -0,0 +1,11 @@
+// js/validate/paper-evidence.js
+// The pure computation behind POST /api/v1/validate/paper-evidence, shared by the API route and the
+// MCP package's local mode (mcp/src/local mirrors it byte for byte), so the two cannot disagree.
+import schema from "../../standards/paper-evidence/schema.json" with { type: "json" };
+import { conformance } from "../paper-evidence-core.js";
+
+export function compute(body) {
+  if (!body.record || typeof body.record !== "object" || Array.isArray(body.record)) throw new RangeError("Send the record to validate under the key \"record\"");
+  const out = conformance(body.record, schema);
+  return { standard: "canli.paper-evidence.v0", valid: out.valid, structural: out.structural, semantic: out.semantic, plain_reading: out.valid ? "The record conforms to the standard. Conformance says the record states what a paper record must state; it does not say the strategy works." : `The record does not conform: ${out.structural.length} structural and ${out.semantic.length} semantic failure(s), each with a JSON pointer.` };
+}