canli-validation-mcp 0.4.0 → 0.6.0

package/src/local/js/validate/track-record.js

@@ -0,0 +1,50 @@
+// js/validate/track-record.js
+// The pure computation behind POST /api/v1/validate/track-record, 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 { minimumTrackRecordLength, probabilisticSharpe } from "../dsr-core.js";
+
+// Minimum track record length for an observed Sharpe to clear a benchmark Sharpe at a confidence
+// level, and, when the record's length is sent, the probabilistic Sharpe against that benchmark:
+// Bailey and López de Prado, "The Sharpe Ratio Efficient Frontier" (2012), checked against the
+// paper's worked examples in js/dsr-paper-vectors.test.js.
+
+const REQUIRED = ["observed_sharpe_annualized", "periods_per_year", "skew", "non_excess_kurtosis"];
+
+export function compute(body) {
+  const missing = REQUIRED.filter((k) => body[k] === undefined);
+  if (missing.length) throw new RangeError(`Missing required fields: ${missing.join(", ")}`);
+  const inputs = {
+    observed_sharpe_annualized: Number(body.observed_sharpe_annualized),
+    benchmark_sharpe_annualized: body.benchmark_sharpe_annualized === undefined ? 0 : Number(body.benchmark_sharpe_annualized),
+    periods_per_year: Number(body.periods_per_year),
+    skew: Number(body.skew),
+    non_excess_kurtosis: Number(body.non_excess_kurtosis),
+    confidence: body.confidence === undefined ? 0.95 : Number(body.confidence),
+  };
+  if (!(inputs.periods_per_year > 0 && inputs.periods_per_year <= 10000)) throw new RangeError("periods_per_year must be between 0 and 10000");
+  if (!(inputs.non_excess_kurtosis >= 1 && inputs.non_excess_kurtosis <= 100)) throw new RangeError("non_excess_kurtosis must be between 1 and 100 (a Normal distribution is 3)");
+  const minimum = minimumTrackRecordLength(inputs);
+  const result = { minimum_observations: Math.ceil(minimum.observations), minimum_years: minimum.years, confidence: minimum.confidence };
+  if (body.observations !== undefined) {
+    const observations = Number(body.observations);
+    if (!Number.isInteger(observations) || observations < 2 || observations > 1000000) throw new RangeError("observations must be an integer from 2 to 1000000");
+    const psr = probabilisticSharpe({ ...inputs, observations });
+    result.record = {
+      observations,
+      years: observations / inputs.periods_per_year,
+      psr_against_benchmark: psr.probabilistic_sharpe_ratio,
+      long_enough: observations >= result.minimum_observations,
+    };
+  }
+  return { derived_inputs: inputs, result, plain_reading: reading(inputs, result) };
+}
+
+function reading(inputs, r) {
+  const pct = (x) => `${(x * 100).toFixed(1)} percent`;
+  // A Sharpe derived from a return series carries every digit of the float; three decimals read.
+  const sharpe = (x) => String(Number(Number(x).toFixed(3)));
+  const need = `To be ${pct(r.confidence)} confident that a Sharpe of ${sharpe(inputs.observed_sharpe_annualized)} is above ${sharpe(inputs.benchmark_sharpe_annualized)}, the track record needs at least ${r.minimum_observations} observations, about ${r.minimum_years.toFixed(2)} years.`;
+  if (!r.record) return `${need} This counts sample uncertainty and the shape of the returns only; it is not a forecast.`;
+  const verdict = r.record.long_enough ? "is long enough" : "is not long enough yet";
+  return `${need} The record sent, ${r.record.observations} observations, ${verdict}: the probability its Sharpe is above the benchmark is ${pct(r.record.psr_against_benchmark)}. Neither number is a forecast.`;
+}

package/src/local/scripts/canonical-json.mjs

@@ -0,0 +1,176 @@
+// =============================================================================
+// canonical-json.mjs
+// -----------------------------------------------------------------------------
+// ONE canonicalisation for every published `content_hash` on this site.
+//
+// WHY THIS FILE EXISTS. `reproduce.py` -- the kit a reader runs to check that the
+// published record reproduces -- recomputes every artifact's hash with Python's
+//
+//     json.dumps(payload_without_content_hash, sort_keys=True, separators=(",", ":"))
+//
+// Seven generators carried their own copy-pasted `canonical()` that happened to
+// agree with it. `build-paper-evidence-vectors.mjs` carried NO copy and hashed
+// with a bare `JSON.stringify`, which preserves insertion order instead of
+// sorting. Its artifact therefore never reproduced, L1 read 158/1, and because
+// the nightly ceremony gates on L1 the whole publish halted -- OTS anchoring,
+// capacity and founder commitments included. One generator missing a helper the
+// other seven had duplicated took the ceremony down.
+//
+// That is the same shape as `normalizeEditableCopy`, which was pasted into three
+// generators while the verifier had no copy at all. A helper that must agree
+// across N call sites cannot live as N copies. It lives here.
+//
+// WHAT "CANONICAL" MEANS HERE, exactly, because two of these are traps:
+//
+//   * KEY ORDER -- recursively sorted, matching `sort_keys=True`. This is the one
+//     the missing copy got wrong.
+//   * SEPARATORS -- "," and ":" with no spaces, matching `separators=(",", ":")`.
+//   * NON-ASCII -- escaped to \uXXXX, matching Python's default `ensure_ascii=True`.
+//     JS `JSON.stringify` emits raw UTF-8 instead. For a pure-ASCII document the
+//     two settings emit IDENTICAL bytes, so this divergence stays invisible until
+//     the first accented character -- which is exactly how "Lopez de Prado" in one
+//     contract halted the nightly for three nights.
+//   * NUMBERS -- Python and JS disagree on when to switch to exponent form
+//     (Python at >=1e16 and <1e-4, JS at >=1e21 and <1e-6) and on the exponent's
+//     own spelling (Python "1e-05", JS "1e-5"). `pythonNumber` reproduces
+//     Python's rule. A number this cannot render faithfully THROWS rather than
+//     emitting a hash that will not reproduce: a wrong hash fails at 22:12 in the
+//     nightly, an exception fails in the generator that caused it.
+//
+// The differential test in `canonical-json.test.mjs` is what makes any of this
+// believable: it hands the same values to Python and compares the bytes.
+// =============================================================================
+
+/**
+ * Render a number the way Python re-emits it after parsing the literal JS wrote.
+ *
+ * THE CHAIN THIS HAS TO PREDICT, because getting it wrong is invisible until the
+ * nightly ceremony halts: a JS generator builds an object, writes it with
+ * `JSON.stringify(payload, null, 2)`, and `reproduce.py` later PARSES that file and
+ * re-emits it with `json.dumps`. So the target is not "what Python's repr does to
+ * this JS number" -- it is "what Python does to the LITERAL JSON.stringify writes".
+ *
+ * That distinction is the whole rule. `1e16` reaches the file as
+ * `10000000000000000`, which Python parses as an INT and echoes digit for digit;
+ * predicting Python's float repr (`1e+16`) there would be wrong. `1e-7` reaches the
+ * file as `1e-7`, which Python parses as a float and re-spells `1e-07`.
+ *
+ * KNOWN LIMIT, stated because it bounds where this module may be used: a float
+ * Python wrote as `1.0` parses to the JS number `1`, and no JS function can tell it
+ * from an integer. So this canonicalisation is faithful for payloads BUILT in JS and
+ * written by `JSON.stringify` -- the artifact and its hash then agree -- and is NOT a
+ * general re-canonicaliser for files a Python exporter produced.
+ */
+export function pythonNumber(value) {
+  if (!Number.isFinite(value)) {
+    // Python writes Infinity/NaN; JSON has no such literals and JS writes null.
+    // Neither is reproducible, so refuse rather than publish an unreproducible hash.
+    throw new Error(`canonical-json: ${value} has no reproducible JSON form`);
+  }
+  // Exactly the bytes JSON.stringify will put in the artifact file.
+  const literal = JSON.stringify(value);
+  if (!/[.eE]/.test(literal)) {
+    // No decimal point and no exponent: Python parses an int and echoes the digits.
+    return literal;
+  }
+  // Python parses a float, so the output is `repr(float)`: shortest round-trip
+  // digits -- identical in both languages -- laid out by Python's rule, which is
+  // fixed notation for a decimal exponent in [-4, 16) and exponent form otherwise.
+  const [mantissa, exponent] = value.toExponential().split("e");
+  const e = Number(exponent);
+  const negative = mantissa.startsWith("-");
+  const digits = mantissa.replace("-", "").replace(".", "");
+  if (e >= -4 && e < 16) {
+    let whole;
+    let fraction;
+    if (e >= 0) {
+      whole = digits.slice(0, e + 1).padEnd(e + 1, "0");
+      fraction = digits.slice(e + 1);
+    } else {
+      whole = "0";
+      fraction = "0".repeat(-e - 1) + digits;
+    }
+    // Python always keeps at least one fractional digit on a float.
+    return `${negative ? "-" : ""}${whole}.${fraction === "" ? "0" : fraction}`;
+  }
+  const sign = e < 0 ? "-" : "+";
+  const magnitude = String(Math.abs(e)).padStart(2, "0");
+  return `${mantissa}e${sign}${magnitude}`;
+}
+
+// Every code unit above ASCII. Written as an escape range rather than as literal
+// characters so the source file itself stays ASCII -- a file about non-ASCII
+// escaping is the worst possible place to smuggle in a stray accented byte.
+const NON_ASCII = /[\u0080-\uffff]/g;
+
+/** Escape a string the way Python's `json.dumps(ensure_ascii=True)` does. */
+export function pythonString(value) {
+  // JSON.stringify already handles quotes, backslashes and control characters
+  // identically to Python. Only non-ASCII is spelled differently, so escape that
+  // and leave the rest of JS's output alone. Astral characters are already
+  // surrogate pairs in JS, and Python escapes them as a surrogate pair too.
+  return JSON.stringify(value).replace(
+    NON_ASCII,
+    (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+}
+
+/** The canonical byte string an artifact's `content_hash` is taken over. */
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((k) => `${pythonString(k)}:${canonicalJson(value[k])}`)
+      .join(",")}}`;
+  }
+  if (typeof value === "number") return pythonNumber(value);
+  if (typeof value === "string") return pythonString(value);
+  if (value === null || typeof value === "boolean") return JSON.stringify(value);
+  // undefined, function, symbol, bigint: JSON.stringify would silently drop or
+  // throw. Neither belongs in a published artifact, so say so by name.
+  throw new Error(`canonical-json: ${typeof value} has no canonical JSON form`);
+}
+
+/** `sha256:...` over the payload with its own `content_hash` field removed. */
+export function contentHash(payload, createHash) {
+  const body = Object.fromEntries(
+    Object.entries(payload).filter(([k]) => k !== "content_hash"),
+  );
+  return `sha256:${createHash("sha256").update(canonicalJson(body)).digest("hex")}`;
+}
+
+/**
+ * Write a glass-box artifact, stamp its `content_hash`, and PROVE the file on disk
+ * reproduces that hash before returning.
+ *
+ * WHY THE READ-BACK. Computing a hash and writing a file are two steps, and every
+ * incident in this pipeline's history lives in the gap between them: a generator
+ * that hashed insertion-ordered bytes while the reader sorted them, an exporter that
+ * emitted raw UTF-8 while the reader escaped it. In both cases the generator
+ * succeeded, the artifact looked fine, and the failure surfaced days later as a
+ * halted nightly ceremony pointing at the reader rather than the writer.
+ *
+ * So this re-reads what it just wrote, re-canonicalises it the way `reproduce.py`
+ * will, and throws if the two disagree. The generator that caused the problem is the
+ * thing that fails, at the moment it causes it. A list of "artifacts to check" would
+ * have to be maintained and would silently omit the next new one; a self-check
+ * cannot be omitted by anyone who uses the helper.
+ */
+export function writeArtifact(path, payload, { createHash, readFileSync, writeFileSync }) {
+  const stamped = { ...payload };
+  delete stamped.content_hash;
+  stamped.content_hash = contentHash(stamped, createHash);
+  writeFileSync(path, `${JSON.stringify(stamped, null, 2)}\n`);
+
+  const reread = JSON.parse(readFileSync(path, "utf8"));
+  const observed = contentHash(reread, createHash);
+  if (observed !== reread.content_hash) {
+    throw new Error(
+      `canonical-json: ${path} does not reproduce its own content_hash ` +
+        `(wrote ${reread.content_hash}, re-read as ${observed}). ` +
+        "The published record would not reproduce and the nightly ceremony would halt.",
+    );
+  }
+  return stamped.content_hash;
+}

package/src/local/standards/paper-evidence/schema.json

@@ -0,0 +1,429 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://canlicapital.com/standards/paper-evidence/v0/schema.json",
+  "title": "canli.paper-evidence.v0",
+  "description": "A record of paper-traded or simulated strategy performance that states what it does not know. The schema exists because the failure mode of a performance claim is not a wrong number, it is a number whose basis, cost assumptions, search history and missing evidence are unstated. Every required field below is one of those.",
+  "type": "object",
+  "required": [
+    "schema",
+    "generated_at",
+    "capital",
+    "identity",
+    "period",
+    "returns",
+    "costs",
+    "selection",
+    "risk",
+    "corrections",
+    "provenance",
+    "claim_maturity"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema": {
+      "const": "canli.paper-evidence.v0"
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "capital": {
+      "type": "object",
+      "description": "What kind of money produced this record. The single most misreadable fact about any track record, so it is required and enumerated rather than described in prose.",
+      "required": [
+        "kind",
+        "execution"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "enum": [
+            "PAPER",
+            "FUNDED",
+            "SIMULATED",
+            "MIXED"
+          ],
+          "description": "PAPER: orders placed at a broker against a paper account. SIMULATED: no broker involved. FUNDED: real capital at risk. MIXED: any combination, which must be decomposed in `notes`."
+        },
+        "execution": {
+          "enum": [
+            "BROKER_PAPER_FILLS",
+            "LOCAL_SIMULATED_FILLS",
+            "BROKER_LIVE_FILLS",
+            "MIXED"
+          ],
+          "description": "Where the fills came from. A broker paper fill and a locally modelled fill are different evidence and may not be merged silently."
+        },
+        "venue": {
+          "type": "string"
+        },
+        "notes": {
+          "type": "string"
+        }
+      }
+    },
+    "identity": {
+      "type": "object",
+      "description": "What this record is about, and whether that thing was frozen before the returns were seen.",
+      "required": [
+        "name",
+        "kind",
+        "preregistered"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "enum": [
+            "SLEEVE",
+            "BOOK",
+            "CANDIDATE"
+          ]
+        },
+        "preregistered": {
+          "type": "boolean",
+          "description": "Whether the strategy identity was frozen before its out-of-sample returns were opened. False is a legitimate answer and is far more useful than an absent field."
+        },
+        "preregistration_ref": {
+          "type": "string"
+        },
+        "constituents": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "period": {
+      "type": "object",
+      "required": [
+        "first_observation",
+        "last_observation",
+        "observation_count",
+        "frequency"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "first_observation": {
+          "type": "string",
+          "format": "date"
+        },
+        "last_observation": {
+          "type": "string",
+          "format": "date"
+        },
+        "observation_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "frequency": {
+          "enum": [
+            "DAILY",
+            "WEEKLY",
+            "MONTHLY",
+            "HOURLY",
+            "IRREGULAR"
+          ]
+        },
+        "calendar": {
+          "type": "string"
+        }
+      }
+    },
+    "returns": {
+      "type": "object",
+      "description": "Return figures, always net-of-what stated. A return series whose cost treatment is unstated is not a measurement.",
+      "required": [
+        "basis",
+        "cumulative",
+        "series_available"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "basis": {
+          "enum": [
+            "GROSS",
+            "NET_OF_MODELLED_COSTS",
+            "NET_OF_REALISED_COSTS"
+          ],
+          "description": "NET_OF_REALISED_COSTS requires broker-observed costs, not a model."
+        },
+        "cumulative": {
+          "type": "number"
+        },
+        "annualised": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "sharpe_annualised": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "sharpe_reportable": {
+          "type": "boolean",
+          "description": "Whether the sample supports reporting a Sharpe at all. A short record must set this false and leave sharpe_annualised null rather than publishing a figure the sample cannot carry."
+        },
+        "series_available": {
+          "type": "boolean"
+        },
+        "series_url": {
+          "type": "string"
+        }
+      }
+    },
+    "costs": {
+      "type": "object",
+      "description": "What was charged and what was assumed. Absent cost modelling is itself a disclosure.",
+      "required": [
+        "modelled"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "modelled": {
+          "type": "boolean"
+        },
+        "components": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "SPREAD",
+              "FEES",
+              "IMPACT",
+              "LATENCY",
+              "FINANCING",
+              "BORROW",
+              "FUNDING"
+            ]
+          }
+        },
+        "turnover_annualised": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "notes": {
+          "type": "string"
+        },
+        "not_modelled": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Cost categories the publisher does NOT charge. Optional in v0 and a candidate to become required in the next version, because a cost model described only by its inclusions is structurally misleading: a reader cannot distinguish a cost judged immaterial from one nobody considered, since both appear as silence. Unmodelled costs almost always flatter, so this list has a known direction."
+        },
+        "coverage_url": {
+          "type": "string"
+        }
+      }
+    },
+    "selection": {
+      "type": "object",
+      "description": "How much searching produced this result. Without it a Sharpe ratio is uninterpretable, which is the single most common defect in published performance.",
+      "required": [
+        "trials_counted",
+        "trial_count",
+        "deflation_applied"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "trials_counted": {
+          "type": "boolean",
+          "description": "Whether the publisher actually maintains a trial ledger. False is honest; an unstated trial count is not."
+        },
+        "trial_count": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "trial_unit": {
+          "type": "string"
+        },
+        "deflation_applied": {
+          "type": "boolean"
+        },
+        "deflated_sharpe_ratio": {
+          "type": [
+            "number",
+            "null"
+          ],
+          "minimum": 0,
+          "maximum": 1
+        },
+        "deflation_method": {
+          "type": "string"
+        }
+      }
+    },
+    "risk": {
+      "type": "object",
+      "required": [
+        "max_drawdown_realised",
+        "drawdown_basis"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "max_drawdown_realised": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "drawdown_basis": {
+          "enum": [
+            "OBSERVED",
+            "MODEL_ESTIMATED",
+            "NOT_ESTABLISHED"
+          ]
+        },
+        "max_drawdown_model_expected": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "exposure_notes": {
+          "type": "string"
+        }
+      }
+    },
+    "corrections": {
+      "type": "object",
+      "description": "Whether anything in this record has been withdrawn. A record with no correction history and no statement that it has none is silent, not clean.",
+      "required": [
+        "count",
+        "withdrawn_figures"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "withdrawn_figures": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "figure",
+              "withdrawn_on",
+              "reason"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "figure": {
+                "type": "string"
+              },
+              "withdrawn_on": {
+                "type": "string",
+                "format": "date"
+              },
+              "reason": {
+                "type": "string"
+              },
+              "superseded_by": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "log_url": {
+          "type": "string"
+        }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "description": "What a reader can check without trusting the publisher.",
+      "required": [
+        "source_bindings",
+        "independently_verifiable"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "source_bindings": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": [
+              "path",
+              "sha256"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "path": {
+                "type": "string"
+              },
+              "sha256": {
+                "type": "string",
+                "pattern": "^(sha256:)?[0-9a-f]{64}$"
+              },
+              "url": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "independently_verifiable": {
+          "type": "boolean"
+        },
+        "verification_url": {
+          "type": "string"
+        },
+        "signed": {
+          "type": "boolean"
+        },
+        "signature_scheme": {
+          "type": "string"
+        }
+      }
+    },
+    "claim_maturity": {
+      "type": "object",
+      "description": "What this record does NOT establish. Required, because the omission of this section is what makes an otherwise accurate record misleading.",
+      "required": [
+        "establishes",
+        "does_not_establish"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "establishes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "does_not_establish": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          },
+          "description": "At least one entry. Every record fails to establish something, and a publisher who cannot name one has not looked."
+        },
+        "external_review_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "independent_replication_count": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "notes": {
+      "type": "string"
+    }
+  }
+}