canli-validation-mcp 0.5.0 → 0.7.0

package/README.md

@@ -1,12 +1,19 @@
 # canli-validation-mcp
 
+[![npm](https://img.shields.io/npm/v/canli-validation-mcp)](https://www.npmjs.com/package/canli-validation-mcp)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/arhancanli/canli-validation-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/arhancanli/canli-validation-mcp)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14954/badge)](https://www.bestpractices.dev/projects/14954)
+[![Glama score](https://glama.ai/mcp/servers/arhancanli/canli-validation-mcp/badges/score.svg)](https://glama.ai/mcp/servers/arhancanli/canli-validation-mcp)
+
 An MCP (Model Context Protocol) server over canlicapital.com's free, keyed validation API. It
-gives a coding agent nine tools: issue a free key, run the five validators (deflated Sharpe,
-CSCV overfitting, paper-evidence conformance, breadth ceiling, minimum track record length),
-fetch a stored receipt, read service status, and read a company's reported financial history
-from SEC filings. Every tool returns the full API envelope as its result text, success or error,
-so the agent cannot see a number without the sentences beside it that say what the number does
-not establish.
+gives a coding agent fourteen tools: issue a free key, run the eight validators (deflated Sharpe,
+CSCV overfitting, paper-evidence conformance, breadth ceiling, minimum track record length,
+minimum backtest length, haircut Sharpe ratio, luck-equivalent trials),
+audit one backtest with three of them in a single call, fetch a stored receipt, verify a
+receipt's signature offline, read service status, and read a company's reported financial history
+from SEC filings. Every validation result carries, beside the number, the sentences that say what
+it does not establish and the receipt that records it, success or error, so the agent cannot see a
+number without its limits.
 
 This package is published to npm as [`canli-validation-mcp`](https://www.npmjs.com/package/canli-validation-mcp).
 Also listed on the official MCP Registry (`io.github.arhancanli/canli-validation-mcp`) and
@@ -16,11 +23,18 @@ test this package itself; see "Local checkout" near the bottom.
 This README describes the version in `package.json`. Unversioned `npx` runs npm's latest
 release; `npx -y canli-validation-mcp@<version>` pins one.
 
+## How well agents use it
+
+A fixed benchmark gives models these tools and scores whether they pick the right one and return
+the right answer, against ground truth computed from the same checked code. Results for three
+models, with every run recorded, are in
+[`bench/agent/README.md`](https://github.com/arhancanli/canlicapital/blob/main/mcp/bench/agent/README.md).
+
 ## What the API is (and is not)
 
 The engine is the product. The service runs your submitted numbers through the same honesty
 arithmetic canlicapital.com's own paper record runs on itself and hands back a verdict anyone can
-recompute from the receipt. It does not accept market data, does not sign receipts, does not
+recompute from the receipt. It signs every receipt, does not accept market data, does not
 grade a strategy, and never saw your data source, its costs, or any lookahead in how a series was
 built. See `docs/superpowers/specs/2026-09-05-developer-key-validation-api-design.md` in the main
 repository for the full design.
@@ -35,6 +49,11 @@ repository for the full design.
 | `validate_paper_evidence` | `POST /api/v1/validate/paper-evidence` | yes |
 | `validate_breadth` | `POST /api/v1/validate/breadth` | yes |
 | `validate_track_record` | `POST /api/v1/validate/track-record` | yes |
+| `validate_backtest_length` | `POST /api/v1/validate/backtest-length` | yes |
+| `validate_haircut_sharpe` | `POST /api/v1/validate/haircut-sharpe` | yes |
+| `validate_luck_trials` | `POST /api/v1/validate/luck-trials` | yes |
+| `audit_backtest` | the deflated Sharpe, track record and, with `variants`, overfitting routes, one validation each | yes |
+| `verify_receipt` | `GET /api/v1/receipts/{id}` when given an id; the checks run locally | no |
 | `get_receipt` | `GET /api/v1/receipts/{id}` | no |
 | `service_status` | `GET /api/v1/validate/status` | no |
 | `company_financial_history` | `GET /company-data/{cik}.json` (a ticker resolves through `GET /api/v1/company-tickers.json`) | no |
@@ -59,6 +78,24 @@ original SEC response and the record's own boundary sentence: these are accounti
 reported to the SEC, not market prices, returns or a recommendation. Companies and concepts
 outside the current release return an error with the available concepts listed.
 
+## Auditing a backtest in one call
+
+`audit_backtest` takes one strategy's return series, the number of variants tried and their Sharpe
+dispersion, and optionally every variant's returns. It runs `validate_deflated_sharpe` on the
+series, then `validate_track_record` on the Sharpe, skew and kurtosis that check derived, then,
+with `variants`, `validate_overfitting`. Each check is exactly what its own tool returns, with its
+own receipt; the boundary sentences they share are stated once. A check that refuses (a Sharpe
+that cannot beat the benchmark has no minimum track record) is reported as that check's error.
+The audit adds no grade of its own. Through the API it uses one validation per check.
+
+When the server runs on your machine, `returns_file` and `variants_file` take the path of the
+backtest's output instead of the numbers: a CSV (comma, semicolon or tab separated, with or without
+a header; date and label columns are ignored, an unnamed or counting index column is skipped and
+reported) or a JSON array. `returns_column` picks the column when there are several. Only the
+numbers are read; the hosted endpoint refuses file paths. An agent copying a long series into a
+call can drop values, and the copy costs tokens; in our agent benchmark, reading the file instead
+took three audit questions from 4 of 9 to 8 of 9 answered correctly on gpt-5.4-mini.
+
 ## Prompts, resources and structured results
 
 Clients that show MCP prompts offer two guided workflows: `validate_backtest` (deflated Sharpe, then
@@ -96,7 +133,9 @@ an array of objects.
 |---|---|---|
 | `CANLI_API_BASE` | `https://canlicapital.com` | Where the API lives. Point it at a preview deployment for testing. |
 | `CANLI_KEY` | unset | A key already issued from `POST /api/v1/keys`. When set, `get_key` sends no request and reports the key is already configured; every other tool sends it as `Authorization: Bearer <key>`. |
-| `CANLI_LOCAL` | unset | `1` or `true` runs the five validators on this machine (private local mode, below): no key, no network, no receipt. |
+| `CANLI_FULL_ENVELOPE` | unset | `1` or `true` returns each validation's full API envelope instead of the compact result (below). |
+| `CANLI_TOOLSETS` | all | Which tools to list: a comma-separated choice of `validate`, `receipts`, `company` and `status`, or `all`. An unknown name is refused at startup. See "Toolsets" below. |
+| `CANLI_LOCAL` | unset | `1` or `true` runs the eight validators on this machine (private local mode, below): no key, no network, no receipt. |
 
 If `CANLI_KEY` is not set and local mode is off, call `get_key` once per session before the validators. The key it
 returns lives only in this process's memory for the life of the session; it is not written to
@@ -133,6 +172,9 @@ by every hosted caller. For your own quota, issue a free key (see
 claude mcp add --transport http canli https://canlicapital.com/mcp --header "Authorization: Bearer $CANLI_KEY"
 ```
 
+Add `?toolsets=` to the URL to list only some tools (see "Toolsets" below), for example
+`https://canlicapital.com/mcp?toolsets=company`.
+
 The endpoint is stateless. On it, `get_key` issues nothing and says which key is in use, because a
 key issued there would not reach the next request. A malformed Authorization header is refused
 rather than replaced with the shared key.
@@ -165,7 +207,7 @@ Run `claude mcp list` to confirm it is registered, and `claude mcp remove canli`
 
 ## Private local mode
 
-Set `CANLI_LOCAL=1` and the five validators run on your machine: nothing about the series you
+Set `CANLI_LOCAL=1` and the eight validators run on your machine: nothing about the series you
 submit is sent to canlicapital.com, no key is needed, and no receipt is stored. The computation is
 the API's own, shipped byte for byte in `src/local` (a test fails if it drifts), so a local result
 equals the hosted one; it names no receipt id because none was made.
@@ -211,7 +253,7 @@ const result = await client.callTool({
     cross_trial_sharpe_sd_annualized: 0.5,
   },
 });
-console.log(result.content[0].text); // the full envelope, including limits and receipt.url
+console.log(result.content[0].text); // the answer, its limits and its receipt
 
 await client.close();
 ```
@@ -231,8 +273,45 @@ Every envelope this server returns carries these sentences, verbatim, from the A
   request, 20000 observations per series, 200 variants per matrix.
 
 Each tool's description also states one of these sentences, so an agent sees the boundary before
-it calls the tool, not only after. No tool in this server strips `limits` or `receipt.url` from
-a response; the full envelope is always the result text.
+it calls the tool, not only after.
+
+## Compact results (tokens)
+
+A validation result is the answer (`data`), the sentences above except the quota line, and the
+receipt's id and URL; an error keeps its error. The rest of the API envelope (schema, endpoint,
+timestamps, claim and capital class, the human page, the source-file hashes and the quota line)
+describes the service rather than the answer, and an agent pays for every token of it on every
+call. It stays in the stored receipt, which `get_receipt` returns in full, and in `service_status`.
+On a breadth result this is about half the text. Set `CANLI_FULL_ENVELOPE=1` to receive every field.
+
+## Toolsets (tokens)
+
+A client sends the model the whole tool list on every turn, and it is most of each turn's prompt:
+a validation result is a few hundred tokens, the list of all fourteen tools several thousand. A
+client that needs one kind of tool can list only that kind, with `CANLI_TOOLSETS` (stdio) or
+`?toolsets=` (hosted endpoint). The default is every tool.
+
+| toolset | tools |
+|---|---|
+| `validate` | `get_key`, the eight validators, `audit_backtest` |
+| `receipts` | `get_receipt`, `verify_receipt` |
+| `company` | `company_financial_history` |
+| `status` | `service_status` |
+
+Measured with `bench/tool_list_tokens.py` (tokenizer: tiktoken `o200k_base`; other models'
+tokenizers give different absolute counts), in the shape an OpenAI-style client sends the list:
+
+| CANLI_TOOLSETS | tools | tokens per turn | of all |
+|---|---|---|---|
+| `all` | 14 | 3,888 | 100% |
+| `validate` | 10 | 3,154 | 81% |
+| `receipts` | 2 | 340 | 9% |
+| `company` | 1 | 302 | 8% |
+| `status` | 1 | 98 | 3% |
+
+Providers cache a tool list that is identical from turn to turn and bill the cached part at a
+fraction of the price (`test/tool-list-stable.test.mjs` keeps each list byte-stable); a smaller list
+costs less either way.
 
 ## Local checkout
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canli-validation-mcp",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "MCP server for canlicapital.com's free validation API: deflated Sharpe, CSCV overfitting, paper-evidence conformance, and breadth ceiling, each returned as the full API envelope so the boundary language cannot be dropped.",
   "private": false,
   "type": "module",
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
-    "zod": "4.5.4"
+    "zod": "4.6.5"
   },
   "mcpName": "io.github.arhancanli/canli-validation-mcp",
   "repository": {

package/src/local/api/_lib/limits.js

@@ -16,7 +16,7 @@ export const LIMITS = Object.freeze({
 export const LIMITS_TEXT = Object.freeze([
   "This verdict is about the series exactly as submitted. The service never saw the data source, its costs, survivorship, or any lookahead in how the series was built.",
   "A deflated Sharpe or overfitting probability above or below any threshold is not admission to anything and is not a forecast.",
-  "The receipt is content-hashed and reproducible from the open-source core it names. It is not signed.",
+  "The receipt is content-hashed, reproducible from the open-source core it names, and signed with Ed25519 by a key published at https://canlicapital.com/.well-known/canli-receipt-keys.json.",
   `Quotas: ${LIMITS.validations_per_key_per_day} validations per key per UTC day, ${LIMITS.keys_per_client_per_day} keys per client per UTC day, ${LIMITS.max_body_bytes} bytes per validation request, ${LIMITS.max_key_revoke_body_bytes} bytes per key revocation request, ${LIMITS.max_observations} observations per series, ${LIMITS.max_variants} variants per matrix.`,
 ]);
 

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

@@ -125,6 +125,57 @@ function requireFinite(name, value) {
   if (!Number.isFinite(value)) throw new RangeError(`${name} must be a finite number`);
 }
 
+// Expected maximum of N independent standard Normal draws (Bailey, Borwein, López de Prado and Zhu
+// 2014, Proposition 2.1; Bailey and López de Prado 2014, the deflated Sharpe ratio): the Sharpe
+// ratio, in units of its standard deviation, that the best of N skill-less trials is expected to show.
+export function expectedMaxStandardNormal(trials) {
+  const n = Number(trials);
+  if (!Number.isInteger(n) || n < 2) throw new RangeError("Effective independent trials must be an integer of at least 2");
+  return (1 - EULER_MASCHERONI) * normalPpf(1 - 1 / n) + EULER_MASCHERONI * normalPpf(1 - 1 / (n * Math.E));
+}
+
+// Minimum Backtest Length (Bailey, Borwein, López de Prado and Zhu 2014, Theorem 3.1): the years of
+// backtest needed so that the best of N skill-less trials is not expected to show an annualized
+// Sharpe of targetSharpe in sample: ((1-g) Z^-1[1-1/N] + g Z^-1[1-1/(Ne)])^2 / targetSharpe^2,
+// bounded above by 2 ln N / targetSharpe^2. Necessary, not sufficient, to avoid overfitting.
+export function minimumBacktestLength({ trials, targetSharpe }) {
+  const target = Number(targetSharpe);
+  if (!(target > 0 && Number.isFinite(target))) throw new RangeError("The target Sharpe must be a positive number");
+  const expectedMax = expectedMaxStandardNormal(trials);
+  return {
+    years: (expectedMax / target) ** 2,
+    upper_bound_years: (2 * Math.log(Number(trials))) / target ** 2,
+    expected_max_sharpe_one_year: expectedMax,
+  };
+}
+
+// The largest number of independent trials whose best is still expected to stay below targetSharpe
+// in sample over `years` of backtest (Eq. 3.1 solved for N). The expected maximum grows with N, so
+// a doubling search then a bisection finds it exactly. Returns 1 when even two trials are too many.
+export function maximumIndependentTrials({ years, targetSharpe }) {
+  const y = Number(years);
+  const target = Number(targetSharpe);
+  if (!(y > 0 && Number.isFinite(y))) throw new RangeError("Backtest years must be a positive number");
+  if (!(target > 0 && Number.isFinite(target))) throw new RangeError("The target Sharpe must be a positive number");
+  const ceiling = target * Math.sqrt(y);
+  const fits = (n) => expectedMaxStandardNormal(n) <= ceiling;
+  if (!fits(2)) return 1;
+  let lo = 2;
+  let hi = 4;
+  const LIMIT = 1e15;
+  while (fits(hi)) {
+    lo = hi;
+    if (hi >= LIMIT) return LIMIT;
+    hi = Math.min(hi * 2, LIMIT);
+  }
+  while (hi - lo > 1) {
+    const mid = Math.floor((lo + hi) / 2);
+    if (fits(mid)) lo = mid;
+    else hi = mid;
+  }
+  return lo;
+}
+
 export function calculateDsr(input) {
   const values = Object.fromEntries(
     Object.entries(input).map(([key, value]) => [key, Number(value)]),
@@ -150,10 +201,7 @@ export function calculateDsr(input) {
   const observedSharpePerPeriod = values.observed_sharpe_annualized / annualizationScale;
   const trialSdPerPeriod = values.cross_trial_sharpe_sd_annualized / annualizationScale;
   const trialVariancePerPeriod = trialSdPerPeriod ** 2;
-  const nTrials = values.effective_independent_trials;
-  const quantile =
-    (1 - EULER_MASCHERONI) * normalPpf(1 - 1 / nTrials) +
-    EULER_MASCHERONI * normalPpf(1 - 1 / (nTrials * Math.E));
+  const quantile = expectedMaxStandardNormal(values.effective_independent_trials);
   const expectedMaxSharpePerPeriod = trialSdPerPeriod * quantile;
   const nonNormalityVarianceTerm =
     1 -

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

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;
+}