canli-validation-mcp 0.4.0 → 0.5.0

package/README.md

@@ -37,7 +37,7 @@ repository for the full design.
 | `validate_track_record` | `POST /api/v1/validate/track-record` | yes |
 | `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 +59,14 @@ 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.
 
+## 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 +96,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. |
 
-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 +163,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 five 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canli-validation-mcp",
-  "version": "0.4.0",
+  "version": "0.5.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",
@@ -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 and reproducible from the open-source core it names. It is not signed.",
+  `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,254 @@
+// 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`);
+}
+
+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 nTrials = values.effective_independent_trials;
+  const quantile =
+    (1 - EULER_MASCHERONI) * normalPpf(1 - 1 / nTrials) +
+    EULER_MASCHERONI * normalPpf(1 - 1 / (nTrials * Math.E));
+  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 };
+}

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