canli-validation-mcp 0.9.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canli-validation-mcp",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Check whether a backtest is real: deflated Sharpe, CSCV probability of backtest overfitting, minimum track record and backtest length, haircut Sharpe and luck-equivalent trials, as an MCP server. Local mode, hosted endpoint, signed receipts.",
   "keywords": [
     "mcp",

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

@@ -58,22 +58,60 @@ export function bookSharpe({ sleeveSharpe, sleeves, correlation }) {
   return sleeveSharpe * Math.sqrt(sleeves / denominator);
 }
 
-/** The value no amount of breadth can exceed. Infinite only when rho <= 0. */
+/**
+ * The most sleeves a shared correlation admits: `1 + (N-1)*rho` must stay positive, so a negative
+ * rho allows only N < 1 - 1/rho (rho = -0.3 allows 4). Infinite when rho >= 0, and when rho is so
+ * close to zero (above about -1e-16) that the cap passes 2^53 sleeves.
+ */
+export function maxSleeves(correlation) {
+  if (!(correlation < 0)) return Number.POSITIVE_INFINITY;
+  const bound = 1 - 1 / correlation;
+  if (!(bound < Number.MAX_SAFE_INTEGER)) return Number.POSITIVE_INFINITY;
+  let n = Math.max(1, Math.ceil(bound) - 1);
+  // The closed form, then one step either way against floating-point rounding at the boundary.
+  while (n > 1 && 1 + (n - 1) * correlation <= 0) n -= 1;
+  while (1 + n * correlation > 0) n += 1;
+  return n;
+}
+
+/**
+ * The most a book of these sleeves can be worth. For rho > 0 it is the limit s / sqrt(rho), which
+ * no finite book reaches. For rho < 0 it is the book at maxSleeves, which is reached: a negative
+ * shared correlation caps the count, so it caps the Sharpe too. Infinite when rho is 0 (and, in
+ * practice, within about 1e-16 below it).
+ */
 export function breadthCeiling({ sleeveSharpe, correlation }) {
-  if (correlation <= 0) return Number.POSITIVE_INFINITY;
-  return sleeveSharpe / Math.sqrt(correlation);
+  if (correlation > 0) return sleeveSharpe / Math.sqrt(correlation);
+  const cap = maxSleeves(correlation);
+  if (!Number.isFinite(cap)) return Number.POSITIVE_INFINITY;
+  return bookSharpe({ sleeveSharpe, sleeves: cap, correlation });
 }
 
-/** The smallest N reaching `target`, or null when the ceiling forbids it. */
-export function sleevesRequired({ sleeveSharpe, correlation, target, maxSleeves = 500 }) {
+/**
+ * The smallest N reaching `target`, or null when no admissible N does. Exact at any size: from
+ * s * sqrt(N / (1 + (N-1)*rho)) >= T, with k = (T/s)^2, N * (1 - k*rho) >= k * (1 - rho). A target
+ * of 50 from sleeves of Sharpe 1 at rho = 0.0001 needs 3,333 sleeves; a search that stopped at 500
+ * called it unreachable.
+ */
+export function sleevesRequired({ sleeveSharpe, correlation, target }) {
   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 };
-    }
+  const unreachable = { sleeves: null, ceiling, reachable: false };
+  if (!(sleeveSharpe > 0) || !(target > 0)) return unreachable;
+  if (target <= sleeveSharpe) return { sleeves: 1, ceiling, reachable: true };
+  // For rho > 0 the ceiling is a limit no book attains; for rho < 0 it is attained at maxSleeves.
+  if (correlation > 0 ? target >= ceiling : target > ceiling) return unreachable;
+  const k = (target / sleeveSharpe) ** 2;
+  const book = (n) => bookSharpe({ sleeveSharpe, sleeves: n, correlation });
+  let n = Math.max(1, Math.ceil((k * (1 - correlation)) / (1 - k * correlation)));
+  if (!Number.isSafeInteger(n)) return unreachable;
+  const cap = maxSleeves(correlation);
+  if (n > cap) n = cap;
+  while (n > 1 && book(n - 1) >= target) n -= 1;
+  while (book(n) < target) {
+    if (n >= cap || !Number.isSafeInteger(n + 1)) return unreachable;
+    n += 1;
   }
-  return { sleeves: null, ceiling, reachable: false };
+  return { sleeves: n, ceiling, reachable: true };
 }
 
 /** The curve of book Sharpe against N, for plotting. */

package/src/local/js/validate/breadth.js

@@ -1,7 +1,7 @@
 // js/validate/breadth.js
 // The pure computation behind POST /api/v1/validate/breadth, shared by the API route and the
 // MCP package's local mode (mcp/src/local mirrors it byte for byte), so the two cannot disagree.
-import { bookSharpe, breadthCeiling, ceilingCaptured, sleevesRequired } from "../breadth-core.js";
+import { bookSharpe, breadthCeiling, ceilingCaptured, maxSleeves, sleevesRequired } from "../breadth-core.js";
 
 export function compute(body) {
   const sleeveSharpe = Number(body.sleeve_sharpe);
@@ -13,12 +13,40 @@ export function compute(body) {
   const target = body.target === undefined ? null : Number(body.target);
   if (target !== null && !(target > 0)) throw new RangeError("target must be a positive Sharpe");
   const ceiling = breadthCeiling({ sleeveSharpe, correlation });
-  const out = { identity: "S_book = s_bar * sqrt(N / (1 + (N - 1) * rho_bar)); ceiling as N grows is s_bar / sqrt(rho_bar)", ceiling: Number.isFinite(ceiling) ? ceiling : null, ceiling_is_unbounded: !Number.isFinite(ceiling) };
-  if (sleeves !== null) out.book = { sleeves, book_sharpe: bookSharpe({ sleeveSharpe, sleeves, correlation }), ceiling_captured: Number.isFinite(ceiling) ? ceilingCaptured({ sleeveSharpe, sleeves, correlation }) : null };
+  const cap = maxSleeves(correlation);
+  const bounded = Number.isFinite(ceiling);
+  // A negative shared correlation admits only so many sleeves, so the ceiling is the book at that
+  // count and is reached; a positive one gives a limit no finite book reaches; zero gives none.
+  const kind = !bounded ? "unbounded" : correlation > 0 ? "limit" : "maximum";
+  const out = {
+    identity: "S_book = s_bar * sqrt(N / (1 + (N - 1) * rho_bar)); for rho_bar > 0 the ceiling is the limit s_bar / sqrt(rho_bar); for rho_bar < 0 only N < 1 - 1 / rho_bar is possible, and the ceiling is the book at the largest such N",
+    ceiling: bounded ? ceiling : null,
+    ceiling_is_unbounded: !bounded,
+    ceiling_kind: kind,
+    ...(Number.isFinite(cap) ? { max_sleeves: cap } : {}),
+  };
+  if (sleeves !== null) {
+    if (sleeves > cap) throw new RangeError(`a shared correlation of ${correlation} admits at most ${cap} sleeves: with more, 1 + (N - 1) * rho is not positive and no real set of returns has that correlation`);
+    out.book = { sleeves, book_sharpe: bookSharpe({ sleeveSharpe, sleeves, correlation }), ceiling_captured: bounded ? ceilingCaptured({ sleeveSharpe, sleeves, correlation }) : null };
+  }
   if (target !== null) {
     const req = sleevesRequired({ sleeveSharpe, correlation, target });
-    out.target = { target, reachable: req.reachable, sleeves_required: req.sleeves, note: req.reachable ? "At this per-sleeve quality and correlation the target is reachable with the stated sleeve count." : "No number of sleeves of this quality at this correlation reaches the target; raise per-sleeve quality or lower correlation." };
+    const n = req.sleeves;
+    out.target = {
+      target,
+      reachable: req.reachable,
+      sleeves_required: n,
+      note: req.reachable
+        ? `${n} sleeve${n === 1 ? "" : "s"} of this quality at this correlation reach a book Sharpe of ${target}; ${n === 1 ? "one sleeve already does" : `${n - 1} fall short`}.`
+        : kind === "maximum"
+          ? `At most ${cap} sleeves can share this correlation, and ${cap} of them reach only ${ceiling.toFixed(3)}; raise per-sleeve quality.`
+          : "No number of sleeves of this quality at this correlation reaches the target; raise per-sleeve quality or lower correlation.",
+    };
   }
-  out.plain_reading = out.ceiling_is_unbounded ? "With average pairwise correlation at or below zero the book Sharpe has no ceiling from breadth alone; correlation this low is rare and should be checked in stress." : `Adding sleeves of this quality can never take the book above a Sharpe of ${ceiling.toFixed(3)}. Quality and correlation set the ceiling; count only approaches it.`;
+  out.plain_reading = kind === "unbounded"
+    ? "With average pairwise correlation of zero the book Sharpe grows with the square root of the sleeve count and has no ceiling from breadth alone; independence this clean is rare and should be checked in stress."
+    : kind === "maximum"
+      ? `A shared correlation of ${correlation} is possible for at most ${cap} sleeves, and ${cap} of them are worth a book Sharpe of ${ceiling.toFixed(3)}; a negative average correlation this strong is rare and should be checked in stress.`
+      : `Adding sleeves of this quality can never take the book above a Sharpe of ${ceiling.toFixed(3)}. Quality and correlation set the ceiling; count only approaches it.`;
   return out;
 }