canli-validation-mcp 0.3.1 → 0.5.0

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

@@ -0,0 +1,167 @@
+// =============================================================================
+// paper-evidence-core.js
+// -----------------------------------------------------------------------------
+// A validator for canli.paper-evidence.v0, with no dependencies.
+//
+// It implements the subset of JSON Schema the standard actually uses: type,
+// const, enum, required, additionalProperties, properties, items, minItems,
+// minLength, minimum, maximum, pattern, and the date and date-time formats.
+//
+// WHY NOT A LIBRARY. A standard is only adoptable if checking it is cheap. A
+// validator that pulls a dependency tree makes conformance a project; one that
+// runs in any browser and any Node without installing anything makes it a
+// paste. The subset is small enough to read in one sitting, which is the other
+// half of adoptability.
+//
+// Every error carries a JSON Pointer to the offending location, because "invalid"
+// without a path is a validator that makes you do its work.
+// =============================================================================
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+
+const typeOf = (value) => {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (Number.isInteger(value)) return "integer";
+  return typeof value;
+};
+
+const matchesType = (value, expected) => {
+  const actual = typeOf(value);
+  if (expected === "number") return actual === "number" || actual === "integer";
+  return actual === expected;
+};
+
+function isValidDate(text) {
+  if (!ISO_DATE.test(text)) return false;
+  const [y, m, d] = text.split("-").map(Number);
+  const date = new Date(Date.UTC(y, m - 1, d));
+  // Round-trip: rejects 2026-02-30, which a regex alone accepts.
+  return date.getUTCFullYear() === y && date.getUTCMonth() === m - 1 && date.getUTCDate() === d;
+}
+
+/**
+ * Validate `value` against `schema`. Returns every error found, not just the
+ * first: a conformance report that stops at the first problem turns adoption
+ * into a guessing game.
+ */
+export function validate(value, schema, pointer = "") {
+  const errors = [];
+  const fail = (message, at = pointer) => errors.push({ pointer: at || "/", message });
+
+  if ("const" in schema && value !== schema.const) {
+    fail(`must equal ${JSON.stringify(schema.const)}`);
+    return errors;
+  }
+
+  if (schema.enum && !schema.enum.includes(value)) {
+    fail(`must be one of ${schema.enum.map((v) => JSON.stringify(v)).join(", ")}`);
+    return errors;
+  }
+
+  if (schema.type) {
+    const allowed = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!allowed.some((t) => matchesType(value, t))) {
+      fail(`expected ${allowed.join(" or ")}, got ${typeOf(value)}`);
+      return errors;
+    }
+  }
+
+  if (typeof value === "string") {
+    if (schema.minLength !== undefined && value.length < schema.minLength) {
+      fail(`must be at least ${schema.minLength} character(s)`);
+    }
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
+      fail(`must match ${schema.pattern}`);
+    }
+    if (schema.format === "date" && !isValidDate(value)) fail("must be a valid ISO date");
+    if (schema.format === "date-time" && !ISO_DATE_TIME.test(value)) {
+      fail("must be an ISO date-time");
+    }
+  }
+
+  if (typeof value === "number") {
+    if (schema.minimum !== undefined && value < schema.minimum) fail(`must be >= ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum) fail(`must be <= ${schema.maximum}`);
+  }
+
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) {
+      fail(`must contain at least ${schema.minItems} item(s)`);
+    }
+    if (schema.items) {
+      value.forEach((item, i) => errors.push(...validate(item, schema.items, `${pointer}/${i}`)));
+    }
+  }
+
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    for (const key of schema.required ?? []) {
+      if (!(key in value)) fail(`missing required property "${key}"`);
+    }
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(value)) {
+        if (!(schema.properties && key in schema.properties)) {
+          fail(`unexpected property "${key}"`, `${pointer}/${key}`);
+        }
+      }
+    }
+    for (const [key, sub] of Object.entries(schema.properties ?? {})) {
+      if (key in value) errors.push(...validate(value[key], sub, `${pointer}/${key}`));
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Checks the standard cannot express as shape, only as a relationship between
+ * fields. A record can satisfy every type in the schema and still make a claim
+ * it has disqualified itself from making, and these are exactly those cases.
+ */
+export function semanticChecks(record) {
+  const errors = [];
+  const fail = (pointer, message) => errors.push({ pointer, message });
+
+  if (record?.returns?.sharpe_reportable === false && record?.returns?.sharpe_annualised !== null) {
+    fail(
+      "/returns/sharpe_annualised",
+      "sharpe_reportable is false, so sharpe_annualised must be null. Declaring a sample " +
+        "cannot support a figure and then publishing the figure is the defect this field exists to prevent.",
+    );
+  }
+  if (record?.selection?.trials_counted === true && record?.selection?.trial_count === null) {
+    fail("/selection/trial_count", "trials_counted is true, so trial_count may not be null");
+  }
+  if (record?.selection?.deflation_applied === true && record?.selection?.deflated_sharpe_ratio === null) {
+    fail("/selection/deflated_sharpe_ratio", "deflation_applied is true, so the deflated ratio must be present");
+  }
+  if (record?.capital?.kind === "PAPER" && record?.returns?.basis === "NET_OF_REALISED_COSTS") {
+    fail(
+      "/returns/basis",
+      "a PAPER record cannot be net of REALISED costs: realised costs require funded execution. " +
+        "Use NET_OF_MODELLED_COSTS.",
+    );
+  }
+  if (record?.risk?.drawdown_basis === "NOT_ESTABLISHED" && record?.risk?.max_drawdown_realised !== null) {
+    fail(
+      "/risk/max_drawdown_realised",
+      "drawdown_basis is NOT_ESTABLISHED, so no realised drawdown may be stated",
+    );
+  }
+  const first = record?.period?.first_observation;
+  const last = record?.period?.last_observation;
+  if (first && last && first > last) {
+    fail("/period", "first_observation is after last_observation");
+  }
+  return errors;
+}
+
+/** Full conformance: shape, then the relationships shape cannot express. */
+export function conformance(record, schema) {
+  const structural = validate(record, schema);
+  // Semantic checks read fields; running them on a structurally broken record
+  // produces noise, so they are gated on the shape being right first.
+  const semantic = structural.length === 0 ? semanticChecks(record) : [];
+  return { valid: structural.length === 0 && semantic.length === 0, structural, semantic };
+}

package/src/local/js/pbo-core.js

@@ -0,0 +1,112 @@
+// js/pbo-core.js
+// Probability of Backtest Overfitting by Combinatorially Symmetric Cross-Validation.
+// A line-for-line port of alphaforge.validation.pbo.pbo_cscv. Where the Python samples
+// combinations with numpy's generator this port uses the repo's mulberry32 and SAYS SO
+// in the result (`exhaustive: false`): the exhaustive case is bit-comparable, the sampled
+// case is comparable within sampling noise. Pinned to standards/validation-api/vectors.json.
+import { makeRandom } from "./selection-risk-core.js";
+
+function blockSharpe(rows, nConfigs) {
+  // Population std (ddof=0); zero variance -> -Infinity so it is never IS-best and ranks worst OOS.
+  const out = new Array(nConfigs);
+  for (let j = 0; j < nConfigs; j++) {
+    let sum = 0;
+    for (const row of rows) sum += row[j];
+    const mean = sum / rows.length;
+    let ss = 0;
+    for (const row of rows) { const d = row[j] - mean; ss += d * d; }
+    const std = Math.sqrt(ss / rows.length);
+    out[j] = std > 0 ? mean / std : Number.NEGATIVE_INFINITY;
+  }
+  return out;
+}
+
+function averageRanks(values) {
+  // scipy.stats.rankdata(method="average"): 1-based, ties share the mean rank.
+  const order = values.map((v, i) => [v, i]).sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  const ranks = new Array(values.length);
+  let i = 0;
+  while (i < order.length) {
+    let j = i;
+    while (j + 1 < order.length && order[j + 1][0] === order[i][0]) j++;
+    const rank = (i + 1 + j + 1) / 2;
+    for (let k = i; k <= j; k++) ranks[order[k][1]] = rank;
+    i = j + 1;
+  }
+  return ranks;
+}
+
+function binomial(n, k) {
+  let r = 1;
+  for (let i = 1; i <= k; i++) r = (r * (n - k + i)) / i;
+  return Math.round(r);
+}
+
+function* combinations(n, k) {
+  const idx = Array.from({ length: k }, (_, i) => i);
+  while (true) {
+    yield idx.slice();
+    let i = k - 1;
+    while (i >= 0 && idx[i] === n - k + i) i--;
+    if (i < 0) return;
+    idx[i]++;
+    for (let j = i + 1; j < k; j++) idx[j] = idx[j - 1] + 1;
+  }
+}
+
+function sampleCombinations(n, k, count, seed) {
+  const next = makeRandom(seed);
+  const seen = new Set();
+  const out = [];
+  while (out.length < count) {
+    const pool = Array.from({ length: n }, (_, i) => i);
+    const pick = [];
+    for (let d = 0; d < k; d++) {
+      const at = Math.floor(next() * pool.length);
+      pick.push(pool[at]);
+      pool.splice(at, 1);
+    }
+    pick.sort((a, b) => a - b);
+    const key = pick.join(",");
+    if (!seen.has(key)) { seen.add(key); out.push(pick); }
+  }
+  return out.sort((a, b) => a.join(",").localeCompare(b.join(","), undefined, { numeric: true }));
+}
+
+export function pboCscv(matrix, { nSplits = 16, maxCombinations = 2000, seed = 42 } = {}) {
+  if (!Number.isInteger(nSplits) || nSplits < 2 || nSplits % 2 !== 0) throw new RangeError(`n_splits must be an even integer >= 2; got ${nSplits}`);
+  if (!Number.isInteger(maxCombinations) || maxCombinations < 1) throw new RangeError(`max_combinations must be >= 1; got ${maxCombinations}`);
+  if (!Array.isArray(matrix) || matrix.length === 0 || !Array.isArray(matrix[0])) throw new RangeError("matrix must be a non-empty array of rows");
+  const nConfigs = matrix[0].length;
+  if (nConfigs < 2) throw new RangeError(`matrix needs >= 2 config columns to rank cross-sectionally; got ${nConfigs}`);
+  for (const row of matrix) {
+    if (row.length !== nConfigs) throw new RangeError("every row must have the same number of columns");
+    for (const v of row) if (!Number.isFinite(Number(v))) throw new RangeError("matrix values must be finite numbers");
+  }
+  const nRows = matrix.length;
+  if (nRows < nSplits) throw new RangeError(`matrix has ${nRows} rows < n_splits=${nSplits}; cannot form that many non-empty contiguous blocks`);
+  const blockLen = Math.floor(nRows / nSplits);
+  const blocks = Array.from({ length: nSplits }, (_, b) => matrix.slice(b * blockLen, (b + 1) * blockLen).map((r) => r.map(Number)));
+  const half = nSplits / 2;
+  const total = binomial(nSplits, half);
+  const exhaustive = total <= maxCombinations;
+  const combos = exhaustive ? [...combinations(nSplits, half)] : sampleCombinations(nSplits, half, maxCombinations, seed);
+  const lambdas = [];
+  const isOos = [];
+  for (const isBlocks of combos) {
+    const isSet = new Set(isBlocks);
+    const isRows = isBlocks.flatMap((b) => blocks[b]);
+    const oosRows = [];
+    for (let b = 0; b < nSplits; b++) if (!isSet.has(b)) oosRows.push(...blocks[b]);
+    const srIs = blockSharpe(isRows, nConfigs);
+    let best = 0;
+    for (let j = 1; j < nConfigs; j++) if (srIs[j] > srIs[best]) best = j;
+    const srOos = blockSharpe(oosRows, nConfigs);
+    const ranks = averageRanks(srOos);
+    const omega = ranks[best] / (nConfigs + 1);
+    lambdas.push(Math.log(omega / (1 - omega)));
+    isOos.push([srIs[best], srOos[best]]);
+  }
+  const pbo = lambdas.filter((l) => l <= 0).length / lambdas.length;
+  return { pbo, n_combinations: combos.length, lambdas, is_oos_pairs: isOos, exhaustive, block_length: blockLen };
+}

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/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/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.` };
+}

package/src/local/js/validate/track-record.js

@@ -0,0 +1,48 @@
+// js/validate/track-record.js
+// The pure computation behind POST /api/v1/validate/track-record, 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 { minimumTrackRecordLength, probabilisticSharpe } from "../dsr-core.js";
+
+// Minimum track record length for an observed Sharpe to clear a benchmark Sharpe at a confidence
+// level, and, when the record's length is sent, the probabilistic Sharpe against that benchmark:
+// Bailey and López de Prado, "The Sharpe Ratio Efficient Frontier" (2012), checked against the
+// paper's worked examples in js/dsr-paper-vectors.test.js.
+
+const REQUIRED = ["observed_sharpe_annualized", "periods_per_year", "skew", "non_excess_kurtosis"];
+
+export function compute(body) {
+  const missing = REQUIRED.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),
+    benchmark_sharpe_annualized: body.benchmark_sharpe_annualized === undefined ? 0 : Number(body.benchmark_sharpe_annualized),
+    periods_per_year: Number(body.periods_per_year),
+    skew: Number(body.skew),
+    non_excess_kurtosis: Number(body.non_excess_kurtosis),
+    confidence: body.confidence === undefined ? 0.95 : Number(body.confidence),
+  };
+  if (!(inputs.periods_per_year > 0 && inputs.periods_per_year <= 10000)) throw new RangeError("periods_per_year must be between 0 and 10000");
+  if (!(inputs.non_excess_kurtosis >= 1 && inputs.non_excess_kurtosis <= 100)) throw new RangeError("non_excess_kurtosis must be between 1 and 100 (a Normal distribution is 3)");
+  const minimum = minimumTrackRecordLength(inputs);
+  const result = { minimum_observations: Math.ceil(minimum.observations), minimum_years: minimum.years, confidence: minimum.confidence };
+  if (body.observations !== undefined) {
+    const observations = Number(body.observations);
+    if (!Number.isInteger(observations) || observations < 2 || observations > 1000000) throw new RangeError("observations must be an integer from 2 to 1000000");
+    const psr = probabilisticSharpe({ ...inputs, observations });
+    result.record = {
+      observations,
+      years: observations / inputs.periods_per_year,
+      psr_against_benchmark: psr.probabilistic_sharpe_ratio,
+      long_enough: observations >= result.minimum_observations,
+    };
+  }
+  return { derived_inputs: inputs, result, plain_reading: reading(inputs, result) };
+}
+
+function reading(inputs, r) {
+  const pct = (x) => `${(x * 100).toFixed(1)} percent`;
+  const need = `To be ${pct(r.confidence)} confident that a Sharpe of ${inputs.observed_sharpe_annualized} is above ${inputs.benchmark_sharpe_annualized}, the track record needs at least ${r.minimum_observations} observations, about ${r.minimum_years.toFixed(2)} years.`;
+  if (!r.record) return `${need} This counts sample uncertainty and the shape of the returns only; it is not a forecast.`;
+  const verdict = r.record.long_enough ? "is long enough" : "is not long enough yet";
+  return `${need} The record sent, ${r.record.observations} observations, ${verdict}: the probability its Sharpe is above the benchmark is ${pct(r.record.psr_against_benchmark)}. Neither number is a forecast.`;
+}