canli-validation-mcp 0.4.0 → 0.6.0

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

@@ -0,0 +1,96 @@
+// The haircut Sharpe ratio: Harvey and Liu, "Backtesting", Journal of Portfolio Management, 2015.
+// A Sharpe ratio found among several tests is converted to a t-statistic, its p-value is adjusted
+// for the number of tests, and the adjusted p-value is converted back to the Sharpe ratio a single
+// test would have needed: the haircut Sharpe ratio. Checked against the authors' own Haircut_SR.m
+// (run in GNU Octave) and against R's p.adjust in js/haircut-paper-vectors.test.js.
+import { studentTQuantileUpper, studentTUpper } from "./student-t.js";
+
+// Lo (2002) for returns with first-order autocorrelation rho sampled q times a year: the annualized
+// Sharpe ratio is scaled by [1 + (2 rho / (1 - rho)) (1 - (1 - rho^q) / (q (1 - rho)))]^(-1/2), the
+// form Haircut_SR.m applies to an annualized input.
+export function autocorrelationFactor(rho, periodsPerYear) {
+  const r = Number(rho);
+  const q = Number(periodsPerYear);
+  if (!(r > -1 && r < 1)) throw new RangeError("autocorrelation must be strictly between -1 and 1");
+  if (r === 0) return 1;
+  const inner = 1 + ((2 * r) / (1 - r)) * (1 - (1 - r ** q) / (q * (1 - r)));
+  if (!(inner > 0)) throw new RangeError("This autocorrelation gives no valid annualization factor");
+  return inner ** -0.5;
+}
+
+function requireCount(name, value, min) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < min) throw new RangeError(`${name} must be an integer of at least ${min}`);
+  return n;
+}
+
+// Holm (step-down) and Benjamini-Hochberg-Yekutieli adjusted p-values for one member of a family,
+// computed exactly as R's p.adjust computes them (stable order, ties by position).
+export function familyAdjusted(pValues, index) {
+  const n = pValues.length;
+  const ascending = pValues.map((p, i) => [p, i]).sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  const holm = new Array(n);
+  let runningMax = 0;
+  ascending.forEach(([p, i], k) => {
+    runningMax = Math.max(runningMax, (n - k) * p);
+    holm[i] = Math.min(1, runningMax);
+  });
+  const harmonic = pValues.reduce((sum, _, k) => sum + 1 / (k + 1), 0);
+  const descending = pValues.map((p, i) => [p, i]).sort((a, b) => b[0] - a[0] || b[1] - a[1]);
+  const bhy = new Array(n);
+  let runningMin = Infinity;
+  descending.forEach(([p, i], k) => {
+    const rank = n - k;
+    runningMin = Math.min(runningMin, ((harmonic * n) / rank) * p);
+    bhy[i] = Math.min(1, runningMin);
+  });
+  return { holm: holm[index], bhy: bhy[index] };
+}
+
+export function haircutSharpe({ sharpeAnnualized, periodsPerYear, observations, tests, autocorrelation = 0, otherSharpesAnnualized }) {
+  const sharpe = Number(sharpeAnnualized);
+  const q = Number(periodsPerYear);
+  if (!(sharpe > 0 && Number.isFinite(sharpe))) throw new RangeError("The haircut applies to a positive, finite Sharpe ratio");
+  if (!(q > 0 && q <= 10000)) throw new RangeError("periods_per_year must be greater than 0 and at most 10000");
+  const T = requireCount("observations", observations, 3);
+  const others = otherSharpesAnnualized === undefined ? null : otherSharpesAnnualized.map(Number);
+  if (others && !others.every(Number.isFinite)) throw new RangeError("Every other Sharpe ratio must be a finite number");
+  const m = others ? others.length + 1 : requireCount("tests", tests, 1);
+  if (others && tests !== undefined && Number(tests) !== m) throw new RangeError("tests must equal the number of other Sharpe ratios plus one, or be left out");
+
+  const factor = autocorrelationFactor(autocorrelation, q);
+  const df = T - 1;
+  const tOf = (annual) => ((annual * factor) / Math.sqrt(q)) * Math.sqrt(T);
+  // Two-sided, as in Haircut_SR.m, but from the upper tail directly so that a large t keeps its p-value.
+  const pOf = (annual) => {
+    const t = tOf(annual);
+    return 2 * (t >= 0 ? studentTUpper(t, df) : studentTUpper(-t, df));
+  };
+  const srCorrected = sharpe * factor;
+  const tStat = tOf(sharpe);
+  const pSingle = pOf(sharpe);
+  const invert = (adjustedP) => {
+    const p = Math.min(1, adjustedP);
+    const tAdjusted = p >= 1 ? 0 : studentTQuantileUpper(p / 2, df);
+    const haircutSharpe = (tAdjusted / Math.sqrt(T)) * Math.sqrt(q);
+    return { adjusted_p: p, haircut_sharpe_annualized: haircutSharpe, haircut: (srCorrected - haircutSharpe) / srCorrected };
+  };
+  const result = {
+    sharpe_annualized_corrected: srCorrected,
+    autocorrelation_factor: factor,
+    t_statistic: tStat,
+    degrees_of_freedom: df,
+    p_value_single: pSingle,
+    tests: m,
+    bonferroni: invert(m * pSingle),
+    // Harvey and Liu's Eq. 4 for independent tests: 1 - (1 - p)^M.
+    independent: invert(-Math.expm1(m * Math.log1p(-pSingle))),
+  };
+  if (others) {
+    const family = [pSingle, ...others.map(pOf)];
+    const adjusted = familyAdjusted(family, 0);
+    result.holm = invert(adjusted.holm);
+    result.bhy = invert(adjusted.bhy);
+  }
+  return result;
+}

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

@@ -0,0 +1,97 @@
+// Luck-equivalent trials: how many skill-less strategies a search would have had to try for the best
+// of them to reach the observed Sharpe ratio by luck alone. A reviewer's statistic, stated in the
+// unit a research log records (trials), assembled from known results:
+//
+// - Under the null of no skill and normal returns, the Sharpe ratio's t-statistic, SR * sqrt(T) with
+//   the Sharpe per period, is exactly Student t with T - 1 degrees of freedom, so one trial reaches
+//   the observed Sharpe with probability p1 = P(t_{T-1} >= SR sqrt(T)).
+// - The best of N independent skill-less trials reaches it with probability 1 - (1 - p1)^N (Sidak),
+//   so the N at which that probability equals q is N_q = ln(1 - q) / ln(1 - p1).
+// - The expected maximum of N standard normals (Bailey, Borwein, Lopez de Prado and Zhu 2014), the
+//   deflated Sharpe ratio's benchmark, gives the N whose best is expected to reach it.
+//
+// Calibrated by Monte Carlo in js/luck-core.test.js; the full size study, with fixed seeds, is
+// scripts/research/luck-trials-size-study.mjs and its output config/research/luck-trials-size-study.json.
+// The size is correct for normal and for symmetric fat-tailed (Student t4) returns, conservative for
+// positively skewed returns, and too small a count, so too kind to the strategy, for negatively
+// skewed returns: with 252 observations a nominal 5% test rejected 10.8% of skill-less searches at
+// skew -1.3 and 20.8% at skew -3.7.
+import { expectedMaxStandardNormal } from "./dsr-core.js";
+import { autocorrelationFactor } from "./haircut-core.js";
+import { studentTUpper } from "./student-t.js";
+
+export const TRIAL_CAP = 1e15;
+
+function requirePositiveInteger(name, value, min) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < min) throw new RangeError(`${name} must be an integer of at least ${min}`);
+  return n;
+}
+
+// P(one skill-less trial shows a Sharpe at least this high): the Student t upper tail.
+export function singleTrialProbability({ sharpe, observations, periodsPerYear }) {
+  const sr = Number(sharpe);
+  const periods = Number(periodsPerYear);
+  const t = requirePositiveInteger("observations", observations, 3);
+  if (!Number.isFinite(sr)) throw new RangeError("The Sharpe ratio must be a finite number");
+  if (!(periods > 0 && Number.isFinite(periods))) throw new RangeError("periods per year must be a positive number");
+  const tStatistic = (sr / Math.sqrt(periods)) * Math.sqrt(t);
+  return { t_statistic: tStatistic, probability: studentTUpper(tStatistic, t - 1) };
+}
+
+// The N at which the best of N skill-less trials reaches the Sharpe with probability q, as a real
+// number. Below 1 means a single trial already reaches it with probability above q; the count is
+// capped at TRIAL_CAP, beyond which the tail probability is below what double precision resolves.
+export function trialsAtProbability(probability, q) {
+  const p = Number(probability);
+  const level = Number(q);
+  if (!(level > 0 && level < 1)) throw new RangeError("The probability level must be strictly between 0 and 1");
+  if (!(p >= 0 && p <= 1)) throw new RangeError("The single-trial probability must be between 0 and 1");
+  if (p === 0) return TRIAL_CAP;
+  return Math.min(TRIAL_CAP, Math.log1p(-level) / Math.log1p(-p));
+}
+
+// P(the best of N skill-less trials shows a Sharpe at least this high): 1 - (1 - p1)^N.
+export function bestOfTrialsProbability(probability, trials) {
+  const n = requirePositiveInteger("trials", trials, 1);
+  return -Math.expm1(n * Math.log1p(-Number(probability)));
+}
+
+// The largest N whose best skill-less trial is expected (the deflated Sharpe ratio's approximation)
+// to stay at or below the t-statistic; 1 when even two are expected to exceed it.
+export function expectedMaximumTrials(tStatistic) {
+  const ceiling = Number(tStatistic);
+  const fits = (n) => expectedMaxStandardNormal(n) <= ceiling;
+  if (!fits(2)) return 1;
+  let lo = 2;
+  let hi = 4;
+  while (fits(hi)) {
+    lo = hi;
+    if (hi >= TRIAL_CAP) return TRIAL_CAP;
+    hi = Math.min(hi * 2, TRIAL_CAP);
+  }
+  while (hi - lo > 1) {
+    const mid = Math.floor((lo + hi) / 2);
+    if (fits(mid)) lo = mid;
+    else hi = mid;
+  }
+  return lo;
+}
+
+// With the returns' lag-1 autocorrelation, the Sharpe is first corrected as Lo (2002), the form
+// js/haircut-core.js applies; the Null Zoo measured that without it, positively autocorrelated
+// returns (0.2) make every best-of-N test reject about four times as often as its level.
+export function luckEquivalentTrials({ sharpe, observations, periodsPerYear, trials, autocorrelation = 0 }) {
+  const factor = autocorrelationFactor(autocorrelation, periodsPerYear);
+  const single = singleTrialProbability({ sharpe: Number(sharpe) * factor, observations, periodsPerYear });
+  const result = {
+    autocorrelation_factor: factor,
+    t_statistic: single.t_statistic,
+    single_trial_probability: single.probability,
+    trials_for_even_odds: trialsAtProbability(single.probability, 0.5),
+    trials_for_five_percent: trialsAtProbability(single.probability, 0.05),
+    trials_expected_to_match: expectedMaximumTrials(single.t_statistic),
+  };
+  if (trials !== undefined) result.best_of_trials_probability = bestOfTrialsProbability(single.probability, trials);
+  return result;
+}

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

@@ -0,0 +1,54 @@
+// js/moments-core.js
+// Per-period moments of a return series, in the exact conventions of
+// alphaforge.validation.dsr._per_period_moments: Sharpe with the SAMPLE standard
+// deviation (ddof=1); skewness and kurtosis as the BIASED population moment
+// estimators (scipy bias=True), kurtosis NON-excess (fisher=False). These are the
+// Bailey-Lopez de Prado conventions the PSR/DSR formulas assume. Pinned to
+// standards/validation-api/vectors.json.
+import { calculateDsr } from "./dsr-core.js";
+
+export function perPeriodMoments(returns) {
+  if (!Array.isArray(returns)) throw new RangeError("returns must be an array of numbers");
+  const x = returns.map(Number).filter((v) => Number.isFinite(v));
+  const n = x.length;
+  if (n < 2) throw new RangeError("need at least 2 finite return observations");
+  let min = Infinity;
+  let max = -Infinity;
+  let sum = 0;
+  for (const v of x) { sum += v; if (v < min) min = v; if (v > max) max = v; }
+  if (max - min === 0) throw new RangeError("return series has zero variance; Sharpe is undefined");
+  const mean = sum / n;
+  let m2 = 0;
+  let m3 = 0;
+  let m4 = 0;
+  for (const v of x) {
+    const d = v - mean;
+    const d2 = d * d;
+    m2 += d2; m3 += d2 * d; m4 += d2 * d2;
+  }
+  const sampleStd = Math.sqrt(m2 / (n - 1));
+  if (sampleStd === 0) throw new RangeError("return series has zero variance; Sharpe is undefined");
+  m2 /= n; m3 /= n; m4 /= n;
+  return {
+    sharpe_per_period: mean / sampleStd,
+    skew: m3 / Math.pow(m2, 1.5),
+    non_excess_kurtosis: m4 / (m2 * m2),
+    observations: n,
+  };
+}
+
+export function dsrFromReturns({ returns, periods_per_year, effective_independent_trials, cross_trial_sharpe_sd_annualized }) {
+  const ppy = Number(periods_per_year);
+  if (!(ppy > 0)) throw new RangeError("periods_per_year must be greater than zero");
+  const m = perPeriodMoments(returns);
+  const derived_inputs = {
+    observed_sharpe_annualized: m.sharpe_per_period * Math.sqrt(ppy),
+    observations: m.observations,
+    periods_per_year: ppy,
+    skew: m.skew,
+    non_excess_kurtosis: m.non_excess_kurtosis,
+    effective_independent_trials: Number(effective_independent_trials),
+    cross_trial_sharpe_sd_annualized: Number(cross_trial_sharpe_sd_annualized),
+  };
+  return { derived_inputs, result: calculateDsr(derived_inputs) };
+}

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/receipt-statement.js

@@ -0,0 +1,54 @@
+// js/receipt-statement.js
+// What a canlicapital.com receipt signature covers, and how to check one. Shared by the API, which
+// signs (api/_lib/receipt-signature.js), and by the MCP package, which verifies offline
+// (mcp/src/local mirrors this file byte for byte), so the two cannot disagree about the bytes signed.
+//
+// The statement is the canonical JSON of the receipt's content: its id, the validator's endpoint,
+// the sha256 of the input, the sha256 of the output, and the sha256 of every source file that
+// computed it. The id is itself the first 24 hex characters of sha256 over the canonical JSON of
+// {endpoint, input_sha256, output, bindings}, so the signature ties the result to the exact code.
+import { createHash, createPublicKey, verify } from "node:crypto";
+
+import { canonicalJson } from "../scripts/canonical-json.mjs";
+
+export const SIGNATURE_SCHEMA = "canli.receipt-signature.v1";
+export const KEYS_URL = "https://canlicapital.com/.well-known/canli-receipt-keys.json";
+
+const sha256Hex = (text) => createHash("sha256").update(text).digest("hex");
+
+export function outputSha256(output) {
+  return `sha256:${sha256Hex(canonicalJson(output))}`;
+}
+
+export function receiptId({ endpoint, input_sha256, output, bindings }) {
+  return sha256Hex(canonicalJson({ endpoint, input_sha256, output, bindings })).slice(0, 24);
+}
+
+export function receiptStatement({ id, endpoint, input_sha256, output_sha256, bindings }) {
+  return canonicalJson({ schema: SIGNATURE_SCHEMA, id, endpoint, input_sha256, output_sha256, bindings });
+}
+
+// The key id is derived from the key: the first 16 hex characters of sha256 over its 32 raw bytes.
+export function keyIdFor(rawPublicKey) {
+  return sha256Hex(rawPublicKey).slice(0, 16);
+}
+
+// Checks a stored receipt end to end: its output hashes to output_sha256, its content hashes to its
+// id, its signature verifies over the statement, and the signing key is one canlicapital.com
+// publishes. Returns every check so a caller can see which one failed.
+export function verifyReceipt({ id, endpoint, input_sha256, output, bindings, signature }, keys) {
+  const checks = { id_matches_content: false, signature_valid: false, key_published: false };
+  const computedOutputSha = outputSha256(output);
+  checks.id_matches_content = receiptId({ endpoint, input_sha256, output, bindings }) === id;
+  const key = signature ? (keys ?? []).find((k) => k.key_id === signature.key_id && k.alg === "Ed25519") : undefined;
+  checks.key_published = Boolean(key);
+  if (key && signature?.value && signature.schema === SIGNATURE_SCHEMA) {
+    const raw = Buffer.from(key.x, "base64url");
+    if (keyIdFor(raw) === key.key_id) {
+      const publicKey = createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: key.x }, format: "jwk" });
+      const statement = receiptStatement({ id, endpoint, input_sha256, output_sha256: computedOutputSha, bindings });
+      checks.signature_valid = verify(null, Buffer.from(statement, "utf8"), publicKey, Buffer.from(signature.value, "base64url"));
+    }
+  }
+  return { valid: checks.id_matches_content && checks.signature_valid && checks.key_published, checks, output_sha256: computedOutputSha, key_id: signature?.key_id ?? null };
+}