canli-validation-mcp 0.4.0 → 0.6.0

package/README.md

@@ -1,12 +1,18 @@
 # 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)
+[![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 +22,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,9 +48,14 @@ 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` | no |
+| `company_financial_history` | `GET /company-data/{cik}.json` (a ticker resolves through `GET /api/v1/company-tickers.json`) | no |
 
 `validate_deflated_sharpe` accepts exactly one of two input shapes, never a mix of both:
 
@@ -59,6 +77,32 @@ 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
+overfitting, then the track record needed, reported with what each number does not establish) and
+`track_record_needed`. Two resources can be read: `canli://limits`, the boundary sentences every
+result carries, and `canli://sources`, the papers behind each validator and how each is checked
+against them. Every tool result carries its envelope both as text and as `structuredContent`.
+
 ## Compact context (0.3.0)
 
 An agent pays for every token a tool returns, including whitespace it never reads. Since 0.3.0
@@ -88,8 +132,10 @@ 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_FULL_ENVELOPE` | unset | `1` or `true` returns each validation's full API envelope instead of the compact result (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, call `get_key` once per session before the four validators. The key it
+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
 disk.
 
@@ -154,6 +200,20 @@ claude mcp add canli -- npx -y canli-validation-mcp
 
 Run `claude mcp list` to confirm it is registered, and `claude mcp remove canli` to remove it.
 
+## Private local mode
+
+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.
+
+```bash
+claude mcp add canli-local --env CANLI_LOCAL=1 -- npx -y canli-validation-mcp
+```
+
+`get_receipt`, `service_status` and `company_financial_history` still read from canlicapital.com;
+they send no series. In the Claude Desktop extension this is the "Private local mode" setting.
+
 ## Generic stdio client
 
 Any MCP client that can spawn a process and speak stdio will work. Using the official SDK
@@ -188,7 +248,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();
 ```
@@ -208,8 +268,16 @@ 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.
 
 ## Local checkout
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canli-validation-mcp",
-  "version": "0.4.0",
+  "version": "0.6.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",
@@ -9,7 +9,7 @@
     "canlicapital-validation-mcp": "src/server.mjs"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.10"
   },
   "files": [
     "src",
@@ -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": {
@@ -32,5 +32,8 @@
   "homepage": "https://canlicapital.com/developers",
   "bugs": {
     "url": "https://github.com/arhancanli/canlicapital/issues"
+  },
+  "devDependencies": {
+    "fast-check": "4.10.2"
   }
 }

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

@@ -0,0 +1,30 @@
+// api/_lib/limits.js
+// THE quota constants. Enforcement (handler.js), the /developers page, the OpenAPI document and
+// public/glassbox/validation_api_limits.json all import or derive from this object, so the number a
+// reader sees is the number the service enforces. Change a value here and nowhere else.
+export const LIMITS = Object.freeze({
+  validations_per_key_per_day: 1000,
+  keys_per_client_per_day: 5,
+  max_key_revoke_body_bytes: 1024,
+  max_body_bytes: 1024 * 1024,
+  max_observations: 20000,
+  max_variants: 200,
+  max_cscv_combinations: 2000,
+  wall_time_seconds: 10,
+});
+
+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, 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.`,
+]);
+
+// What the page has never said. None of this is enforcement text: it is what happens to a key
+// after it is issued, which a reader otherwise has to find out by trying it. Any numeral here is
+// a LIMITS value, never a hand-typed one, so it cannot drift from what the service actually does.
+export const KEY_LIFECYCLE_TEXT = Object.freeze([
+  "Keys do not expire once issued.",
+  "Revoke the bearer key with POST /api/v1/keys/revoke. Revocation does not use validation quota and is irreversible; repeating it leaves the original revocation time intact. Requests already admitted may finish. Confirm a successful response before assuming the key is disabled. Issue a replacement separately; there is no atomic rotate operation.",
+  `"Client", for the daily key-issuance quota, means the request's IP address hashed together with a salt that rotates every UTC day, not a stored account. A shared office or NAT IP address draws from the same pool of ${LIMITS.keys_per_client_per_day} keys a day as every other request behind it.`,
+]);

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

@@ -0,0 +1,96 @@
+// =============================================================================
+// breadth-core.js
+// -----------------------------------------------------------------------------
+// The arithmetic behind /tools/breadth: what a book of N sleeves is worth, and
+// why adding sleeves stops helping.
+//
+// For N equally weighted sleeves, each with per-period Sharpe s and identical
+// pairwise correlation rho:
+//
+//     portfolio mean      = s * sigma
+//     portfolio variance  = sigma^2 * (1 + (N-1) * rho) / N
+//     BOOK SHARPE         = s * sqrt( N / (1 + (N-1) * rho) )
+//
+// The limit as N grows without bound is the part worth staring at:
+//
+//     ceiling = s / sqrt(rho)          for rho > 0
+//
+// It does not depend on N at all. Past a certain point, breadth is not the lever;
+// correlation is. A project that answers a disappointing Sharpe by adding sleeves
+// is working on the wrong number, and this file exists so that is visible rather
+// than argued about.
+//
+// The assumptions are strong and stated everywhere they are used: equal weights,
+// equal Sharpe, one shared pairwise correlation. Real books have none of those.
+// The lab is for the SHAPE of the constraint, not for forecasting a book.
+// =============================================================================
+
+/** Book Sharpe for N equally weighted sleeves at shared correlation rho. */
+export function bookSharpe({ sleeveSharpe, sleeves, correlation }) {
+  if (!Number.isInteger(sleeves) || sleeves < 1) throw new Error("sleeves must be a positive integer");
+  if (!Number.isFinite(sleeveSharpe)) throw new Error("sleeveSharpe must be finite");
+  if (!Number.isFinite(correlation)) throw new Error("correlation must be finite");
+  // The single condition, stated once. `1 + (N-1)*rho` IS the portfolio variance in
+  // units of a sleeve's variance, so it must be strictly positive:
+  //
+  //   rho <  -1/(N-1)  the covariance matrix is not positive semidefinite and no
+  //                    set of real return series can produce it;
+  //   rho == -1/(N-1)  the matrix is PSD but singular, and the equally weighted
+  //                    portfolio has exactly zero variance, so its Sharpe is
+  //                    infinite. Mathematically real, financially a fantasy, and
+  //                    returning a spectacular number for it is precisely the
+  //                    failure mode this tool argues against.
+  //
+  // Both are refused, and the boundary case is named separately because a caller
+  // who lands on it exactly has done something interesting rather than careless.
+  const denominator = 1 + (sleeves - 1) * correlation;
+  if (denominator <= 0) {
+    const floor = sleeves > 1 ? -1 / (sleeves - 1) : -1;
+    throw new Error(
+      denominator === 0
+        ? `a shared correlation of exactly ${correlation} across ${sleeves} sleeves gives the ` +
+          "equally weighted book zero variance and an infinite Sharpe. That is a degenerate " +
+          "case, not an opportunity."
+        : `a shared correlation of ${correlation} is impossible for ${sleeves} sleeves: below ` +
+          `${floor.toFixed(4)} the covariance matrix is not positive semidefinite`,
+    );
+  }
+  return sleeveSharpe * Math.sqrt(sleeves / denominator);
+}
+
+/** The value no amount of breadth can exceed. Infinite only when rho <= 0. */
+export function breadthCeiling({ sleeveSharpe, correlation }) {
+  if (correlation <= 0) return Number.POSITIVE_INFINITY;
+  return sleeveSharpe / Math.sqrt(correlation);
+}
+
+/** The smallest N reaching `target`, or null when the ceiling forbids it. */
+export function sleevesRequired({ sleeveSharpe, correlation, target, maxSleeves = 500 }) {
+  const ceiling = breadthCeiling({ sleeveSharpe, correlation });
+  if (target > ceiling) return { sleeves: null, ceiling, reachable: false };
+  for (let n = 1; n <= maxSleeves; n += 1) {
+    if (bookSharpe({ sleeveSharpe, sleeves: n, correlation }) >= target) {
+      return { sleeves: n, ceiling, reachable: true };
+    }
+  }
+  return { sleeves: null, ceiling, reachable: false };
+}
+
+/** The curve of book Sharpe against N, for plotting. */
+export function breadthCurve({ sleeveSharpe, correlation, maxSleeves }) {
+  const points = [];
+  for (let n = 1; n <= maxSleeves; n += 1) {
+    // Stop at the last N the correlation can actually support, rather than at the
+    // last one that does not throw: those differ by exactly the degenerate case.
+    if (1 + (n - 1) * correlation <= 0) break;
+    points.push({ sleeves: n, sharpe: bookSharpe({ sleeveSharpe, sleeves: n, correlation }) });
+  }
+  return points;
+}
+
+/** How much of the distance to the ceiling N sleeves have actually captured. */
+export function ceilingCaptured({ sleeveSharpe, sleeves, correlation }) {
+  const ceiling = breadthCeiling({ sleeveSharpe, correlation });
+  if (!Number.isFinite(ceiling)) return null;
+  return bookSharpe({ sleeveSharpe, sleeves, correlation }) / ceiling;
+}

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

@@ -0,0 +1,302 @@
+// Pure deflated-Sharpe arithmetic. No DOM: shared by /tools/deflated-sharpe and the
+// validation API so the two can never disagree. Bound to
+// public/glassbox/deflated_sharpe_calculator_contract.json by checkGoldenVectors.
+const EULER_MASCHERONI = 0.5772156649;
+
+// Complementary error function to full double precision (relative error at most 1.5e-14 for
+// x >= -20 and 6e-14 to -38, measured against the C library erfc). For |x| < 1.5 it uses the series
+// erf(x) = 2/sqrt(pi) exp(-x^2) sum 2^n x^(2n+1) / (1*3*...*(2n+1)), which has no cancellation;
+// beyond that, the continued fraction erfc(x) = exp(-x^2)/sqrt(pi) / (x + 1/2 / (x + 1 / (x + ...)))
+// evaluated by the modified Lentz method. It replaced the Abramowitz and Stegun 7.1.26
+// approximation (absolute error up to 1.5e-7, no relative accuracy in the tails) on 2026-09-25.
+function erfc(value) {
+  if (Number.isNaN(value)) return Number.NaN;
+  if (value < 0) return 2 - erfc(-value);
+  const x = value;
+  if (x < 1.5) {
+    let term = x;
+    let sum = x;
+    for (let n = 1; n < 200; n++) {
+      term *= (2 * x * x) / (2 * n + 1);
+      sum += term;
+      if (term < sum * 1e-17) break;
+    }
+    return 1 - (2 / Math.sqrt(Math.PI)) * Math.exp(-x * x) * sum;
+  }
+  if (x > 27.3) return 0;
+  // Lentz: f = b0 + a1/(b1 + a2/(b2 + ...)) with b_k = x, a_k = k/2.
+  const tiny = 1e-300;
+  let f = x;
+  let c = x;
+  let d = 0;
+  for (let k = 1; k < 500; k++) {
+    const a = k / 2;
+    d = x + a * d;
+    d = d === 0 ? tiny : d;
+    c = x + a / c;
+    c = c === 0 ? tiny : c;
+    d = 1 / d;
+    const delta = c * d;
+    f *= delta;
+    if (Math.abs(delta - 1) < 1e-16) break;
+  }
+  return Math.exp(-x * x) / (Math.sqrt(Math.PI) * f);
+}
+
+export function normalCdf(value) {
+  if (value === Infinity) return 1;
+  if (value === -Infinity) return 0;
+  return 0.5 * erfc(-value / Math.SQRT2);
+}
+
+function acklamPpf(probability) {
+  if (!(probability > 0 && probability < 1)) {
+    throw new RangeError("Normal quantile probability must be between zero and one");
+  }
+
+  const a = [
+    -3.969683028665376e1,
+    2.209460984245205e2,
+    -2.759285104469687e2,
+    1.38357751867269e2,
+    -3.066479806614716e1,
+    2.506628277459239,
+  ];
+  const b = [
+    -5.447609879822406e1,
+    1.615858368580409e2,
+    -1.556989798598866e2,
+    6.680131188771972e1,
+    -1.328068155288572e1,
+  ];
+  const c = [
+    -7.784894002430293e-3,
+    -3.223964580411365e-1,
+    -2.400758277161838,
+    -2.549732539343734,
+    4.374664141464968,
+    2.938163982698783,
+  ];
+  const d = [
+    7.784695709041462e-3,
+    3.224671290700398e-1,
+    2.445134137142996,
+    3.754408661907416,
+  ];
+  const low = 0.02425;
+  const high = 1 - low;
+
+  if (probability < low) {
+    const q = Math.sqrt(-2 * Math.log(probability));
+    return (
+      (((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) /
+      ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1)
+    );
+  }
+  if (probability <= high) {
+    const q = probability - 0.5;
+    const r = q * q;
+    return (
+      (((((a[0] * r + a[1]) * r + a[2]) * r + a[3]) * r + a[4]) * r + a[5]) * q /
+      (((((b[0] * r + b[1]) * r + b[2]) * r + b[3]) * r + b[4]) * r + 1)
+    );
+  }
+  const q = Math.sqrt(-2 * Math.log(1 - probability));
+  return -(
+    (((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) /
+    ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1)
+  );
+}
+
+// Inverse normal CDF: Acklam's rational approximation (relative error near 1.15e-9) refined by two
+// Halley steps against the full-precision normalCdf, which brings it to the precision of the CDF.
+export function normalPpf(probability) {
+  let x = acklamPpf(probability);
+  for (let step = 0; step < 2; step++) {
+    const error = normalCdf(x) - probability;
+    const u = error * Math.sqrt(2 * Math.PI) * Math.exp((x * x) / 2);
+    if (!Number.isFinite(u)) break;
+    x -= u / (1 + (x * u) / 2);
+  }
+  return x;
+}
+
+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)]),
+  );
+  for (const [key, value] of Object.entries(values)) requireFinite(key, value);
+  if (!Number.isInteger(values.observations) || values.observations < 2) {
+    throw new RangeError("Return observations must be an integer of at least 2");
+  }
+  if (!(values.periods_per_year > 0)) {
+    throw new RangeError("Periods per year must be greater than zero");
+  }
+  if (
+    !Number.isInteger(values.effective_independent_trials) ||
+    values.effective_independent_trials < 2
+  ) {
+    throw new RangeError("Effective independent trials must be an integer of at least 2");
+  }
+  if (values.cross_trial_sharpe_sd_annualized < 0) {
+    throw new RangeError("Cross-trial Sharpe dispersion cannot be negative");
+  }
+
+  const annualizationScale = Math.sqrt(values.periods_per_year);
+  const observedSharpePerPeriod = values.observed_sharpe_annualized / annualizationScale;
+  const trialSdPerPeriod = values.cross_trial_sharpe_sd_annualized / annualizationScale;
+  const trialVariancePerPeriod = trialSdPerPeriod ** 2;
+  const quantile = expectedMaxStandardNormal(values.effective_independent_trials);
+  const expectedMaxSharpePerPeriod = trialSdPerPeriod * quantile;
+  const nonNormalityVarianceTerm =
+    1 -
+    values.skew * observedSharpePerPeriod +
+    ((values.non_excess_kurtosis - 1) / 4) * observedSharpePerPeriod ** 2;
+  if (!(nonNormalityVarianceTerm > 0)) {
+    throw new RangeError(
+      "These skew, kurtosis and Sharpe inputs produce a non-positive estimator variance term",
+    );
+  }
+  const denominator = Math.sqrt(nonNormalityVarianceTerm);
+  const sampleScale = Math.sqrt(values.observations - 1);
+  const psrZ = observedSharpePerPeriod * sampleScale / denominator;
+  const dsrZ =
+    (observedSharpePerPeriod - expectedMaxSharpePerPeriod) * sampleScale / denominator;
+
+  return {
+    observed_sharpe_per_period: observedSharpePerPeriod,
+    cross_trial_sharpe_variance_per_period: trialVariancePerPeriod,
+    expected_max_sharpe_per_period: expectedMaxSharpePerPeriod,
+    expected_max_sharpe_annualized: expectedMaxSharpePerPeriod * annualizationScale,
+    psr_against_zero: normalCdf(psrZ),
+    deflated_sharpe_ratio: normalCdf(dsrZ),
+    non_normality_variance_term: nonNormalityVarianceTerm,
+    search_haircut_annualized:
+      values.observed_sharpe_annualized - expectedMaxSharpePerPeriod * annualizationScale,
+    psr_z_score: psrZ,
+    dsr_z_score: dsrZ,
+  };
+}
+
+export function checkGoldenVectors(vectors, tolerance = 8e-7) {
+  const failures = [];
+  for (const vector of vectors) {
+    const observed = calculateDsr(vector.inputs);
+    for (const [key, expected] of Object.entries(vector.outputs)) {
+      const error = Math.abs(observed[key] - expected);
+      if (error > tolerance) failures.push({ vector: vector.id, key, expected, observed: observed[key], error });
+    }
+  }
+  return failures;
+}
+
+
+// Probabilistic Sharpe ratio against a benchmark Sharpe, and the minimum track record length for
+// it to clear that benchmark at a confidence level: Bailey and López de Prado, "The Sharpe Ratio
+// Efficient Frontier", Journal of Risk 15(2), 2012, Eqs. (11) and (13). Inputs are annualized; the
+// estimator works per period, like calculateDsr above.
+function perPeriodInputs(values) {
+  for (const [key, value] of Object.entries(values)) requireFinite(key, value);
+  if (!(values.periods_per_year > 0)) throw new RangeError("Periods per year must be greater than zero");
+  const scale = Math.sqrt(values.periods_per_year);
+  const sr = values.observed_sharpe_annualized / scale;
+  const benchmark = values.benchmark_sharpe_annualized / scale;
+  const term = 1 - values.skew * sr + ((values.non_excess_kurtosis - 1) / 4) * sr ** 2;
+  if (!(term > 0)) {
+    throw new RangeError("These skew, kurtosis and Sharpe inputs produce a non-positive estimator variance term");
+  }
+  return { sr, benchmark, term };
+}
+
+export function probabilisticSharpe(input) {
+  const values = {
+    observed_sharpe_annualized: Number(input.observed_sharpe_annualized),
+    benchmark_sharpe_annualized: Number(input.benchmark_sharpe_annualized ?? 0),
+    observations: Number(input.observations),
+    periods_per_year: Number(input.periods_per_year),
+    skew: Number(input.skew),
+    non_excess_kurtosis: Number(input.non_excess_kurtosis),
+  };
+  if (!Number.isInteger(values.observations) || values.observations < 2) {
+    throw new RangeError("Return observations must be an integer of at least 2");
+  }
+  const { sr, benchmark, term } = perPeriodInputs(values);
+  const z = ((sr - benchmark) * Math.sqrt(values.observations - 1)) / Math.sqrt(term);
+  return { probabilistic_sharpe_ratio: normalCdf(z), z_score: z };
+}
+
+export function minimumTrackRecordLength(input) {
+  const confidence = Number(input.confidence ?? 0.95);
+  if (!(confidence > 0 && confidence < 1)) throw new RangeError("Confidence must be strictly between 0 and 1");
+  const values = {
+    observed_sharpe_annualized: Number(input.observed_sharpe_annualized),
+    benchmark_sharpe_annualized: Number(input.benchmark_sharpe_annualized ?? 0),
+    periods_per_year: Number(input.periods_per_year),
+    skew: Number(input.skew),
+    non_excess_kurtosis: Number(input.non_excess_kurtosis),
+  };
+  const { sr, benchmark, term } = perPeriodInputs(values);
+  if (!(sr > benchmark)) {
+    throw new RangeError("The observed Sharpe must exceed the benchmark; no track record length is enough otherwise");
+  }
+  const observations = 1 + term * (normalPpf(confidence) / (sr - benchmark)) ** 2;
+  if (!Number.isFinite(observations)) {
+    throw new RangeError("The observed Sharpe is too close to the benchmark; no finite track record length reaches this confidence");
+  }
+  return { observations, years: observations / values.periods_per_year, confidence };
+}