@general-liquidity/sharpebench 0.19.0 → 0.20.0

package/README.md

@@ -37,17 +37,17 @@ console.log(greeks({ spot: 100, strike: 100, t_years: 1, rate: 0.05, vol: 0.2, i
 |---|---|
 | `score(submissions, config?)` | ranked `CompositeScore[]` |
 | `scoreAgent(submission, config?)` | one `CompositeScore` (deflated Sharpe, pass^k, process, rolling worst-case Sharpe) |
-| `selfAudit()` | `SelfAuditReport`, the benchmark's anti-gaming proof |
+| `selfAudit()` | `SelfAuditReport`, results of the named anti-gaming regressions |
 | `auditBriefing(briefing, policy?)` | `BriefingAudit`, an input-side salience-bias audit |
 | `scoreAllocation(trajectory, policy?)` | `AllocationReport`, weight-vector validity plus L1 turnover |
 | `greeks(params)` | `GreeksResult`, Black-Scholes price, Greeks, and local exposure flags |
 | `canary(seed)` | `Canary`, a do-not-train contamination tripwire |
-| `isMySharpeReal(returns, opts)` | One-series deflation, PSR, haircut, MinTRL, and verdict |
-| `isMySharpeRealFull(field, winner, opts)` | Fieldwise Reality Check, SPA, step-down, and PBO alongside the one-series verdict |
+| `isMySharpeReal(returns, opts)` | One-series deflation, PSR, haircut, MinTRL, and verdict. `trialsSrStd` is annualized; `periodsPerYear` (default 252) says what a period is |
+| `isMySharpeRealFull(field, winner, opts)` | Fieldwise Reality Check, SPA, step-down, PBO and HLZ diagnostics alongside the one-series verdict |
 | `percentileSelection(candidates, opts?)` | Point winner versus bootstrap-percentile winner and optimism gaps |
 | `decomposeUncertainty(input)` | Aleatoric, epistemic, and distributional diagnostic legs |
 | `crowdingHalfLife(adoption, params)` | Caller-calibrated crowding-decay prior, reported but never gating |
-| `classifyDisqualification(submissions, config?)` | Named hard-gate and advisory reasons |
+| `classifyDisqualification(submissions, config?)` | Named hard-gate, unavailability, and advisory reasons |
 | `regimeCompare(a, b, regimes, opts?)` | Regime-conditional distribution comparison and pooled-sign reversal |
 
 All inputs and outputs are fully typed (TypeScript declarations ship with the
@@ -56,6 +56,29 @@ committed golden on the Ubuntu CI host. The Rust CI separately pins the two
 committed golden fields on Linux, macOS, and Windows; this is not a claim about
 every possible input or platform.
 
+## Unavailable results
+
+Check error fields before interpreting numeric diagnostics. `statisticsError`
+marks withheld deflation; `snoopingError` marks withheld fieldwise tests, whose
+compatibility sentinels are p-values of 1 and all-false `stepDown`. These are
+not measured results. Unavailable PBO is `null` with `pboError`.
+
+Nonfinite numeric diagnostics serialize as `null`, including a minimum track
+record length with no finite solution. TypeScript callers must handle nulls.
+`percentileSelection` reports `input_error` and null winner indices when any
+candidate is unsupported. Its `alpha_warning` reports where `alpha` sits and
+nothing else: a refusal that had nothing to do with alpha, such as too few
+observations or a rejected block probability, leaves the flag false.
+
+`classifyDisqualification` returns eleven reasons in three groups: five mirror
+the scorer's hard eligibility gates, two name the unavailability of a statistic
+the scorer gates on (`deflation_unavailable`, `bootstrap_unavailable`), and four
+are advisory and never gate (`selection_unavailable`, `high_selection_gap`,
+`is_rediscovery`, `oos_decay`). `selection_unavailable` is advisory because the
+scorer reports `selection_gap` and never consults it in `rank_eligible`, so a
+submission carrying only advisory reasons is still rank-eligible. Read
+`rank_eligible`, not the presence of a reason. See the [error and migration guide](https://github.com/general-liquidity/sharpebench/blob/main/docs/book/src/wasm.md#statistical-unavailability-and-migration).
+
 ## Why luck-robust?
 
 Most agent leaderboards rank a raw Sharpe over a single short window, so they mostly measure noise. SharpeBench gates eligibility on Deflated Sharpe, pass^k reliability across every seed and window, stationary-bootstrap significance, process discipline, and the host drawdown mandate. PSR and the fieldwise multiple-testing family remain visible diagnostics. See the [benchmark repo](https://github.com/general-liquidity/sharpebench) for the full methodology.

package/dist/index.js

@@ -117,8 +117,22 @@ function honestyConfigJson(opts) {
         throw new RangeError("nTrials must be an integer in 1..=4294967295");
     }
     const cfg = { n_trials: opts.nTrials };
-    if (opts.trialsSrStd !== undefined)
+    if (opts.trialsSrStd !== undefined) {
+        // JSON.stringify turns NaN and Infinity into null, which the kernel reads as
+        // "omitted" and replaces with the 0.5 prior: refuse it before it crosses.
+        if (typeof opts.trialsSrStd !== "number" || !Number.isFinite(opts.trialsSrStd)) {
+            throw new RangeError("trialsSrStd must be a finite number (omit it for the 0.5 prior)");
+        }
         cfg.trials_sr_std = opts.trialsSrStd;
+    }
+    if (opts.periodsPerYear !== undefined) {
+        // JSON.stringify turns NaN and Infinity into null, which the kernel refuses
+        // rather than reading as "omitted"; say which input it was here instead.
+        if (typeof opts.periodsPerYear !== "number" || !Number.isFinite(opts.periodsPerYear)) {
+            throw new RangeError("periodsPerYear must be a finite number (omit it for the 252 default)");
+        }
+        cfg.periods_per_year = opts.periodsPerYear;
+    }
     if (opts.confidence !== undefined)
         cfg.confidence = opts.confidence;
     if (opts.borderline !== undefined)
@@ -144,6 +158,7 @@ function toHonestyVerdict(raw) {
         verdict: raw.verdict,
         explanation: raw.explanation,
         methodologyVersion: raw.methodology_version,
+        ...(raw.statistics_error === undefined ? {} : { statisticsError: raw.statistics_error }),
     };
 }
 /**
@@ -166,6 +181,7 @@ function isMySharpeReal(returns, opts) {
  */
 function isMySharpeRealFull(field, winnerIdx, opts) {
     const raw = parse(kernel.is_my_sharpe_real_full(JSON.stringify(field), winnerIdx, honestyConfigJson(opts)));
+    const hlz = raw.hlz;
     return {
         honesty: toHonestyVerdict(raw.honesty),
         realityCheckP: raw.reality_check_p,
@@ -173,6 +189,14 @@ function isMySharpeRealFull(field, winnerIdx, opts) {
         spaConsistentP: raw.spa_consistent_p,
         stepDown: raw.step_down,
         pbo: raw.pbo,
+        hlz: {
+            tStat: hlz.t_stat,
+            tThreshold: hlz.t_threshold,
+            passed: hlz.passed,
+            explanation: hlz.explanation,
+        },
+        ...(raw.snooping_error === undefined ? {} : { snoopingError: raw.snooping_error }),
+        ...(raw.pbo_error === undefined ? {} : { pboError: raw.pbo_error }),
     };
 }
 /**

package/dist/types.d.ts

@@ -153,33 +153,53 @@ export type Verdict = "Pass" | "Borderline" | "Fail";
 export interface HonestyOpts {
     /** Number of strategy trials behind this result, integer 1..=4294967295. REQUIRED. */
     nTrials: number;
-    /** Cross-trial Sharpe dispersion. Omit → estimated at 0.5 and flagged. */
+    /**
+     * **Annualized** cross-trial Sharpe dispersion, divided by
+     * `sqrt(periodsPerYear)` before use. Omit → estimated at 0.5 and flagged. A
+     * negative value yields a Fail verdict with `statisticsError`; NaN and
+     * infinity cannot cross JSON (they would arrive as the 0.5 prior) and throw a
+     * `RangeError`.
+     */
     trialsSrStd?: number;
+    /**
+     * Return periods per year for these returns (daily equities 252, daily crypto
+     * 365, hourly 8760, weekly 52). Omit → 252, flagged in the explanation. A
+     * non-positive value yields a Fail verdict with `statisticsError`; NaN and
+     * infinity cannot cross JSON and throw a `RangeError`.
+     */
+    periodsPerYear?: number;
     /** Deflated-Sharpe threshold for a Pass. Default 0.95. */
     confidence?: number;
     /** Deflated-Sharpe threshold for Borderline. Default 0.90. */
     borderline?: number;
-    /** PSR / MinTRL benchmark Sharpe to beat. Default 0.0. */
+    /** **Per-period** PSR / MinTRL benchmark Sharpe to beat (not converted). Default 0.0. */
     srBenchmark?: number;
 }
-/** The LITE verdict: everything derivable from one return series. */
+/** The LITE verdict. Nonfinite numeric diagnostics serialize as null, not zero. */
 export interface HonestyVerdict {
-    sharpe: number;
+    sharpe: number | null;
     nObs: number;
-    skew: number;
-    kurtosis: number;
+    skew: number | null;
+    kurtosis: number | null;
     nTrials: number;
-    expectedMaxSharpe: number;
-    deflatedSharpe: number;
-    probabilisticSharpe: number;
-    /** `1 - deflatedSharpe`: probability the edge is a search artifact. */
-    haircut: number;
-    /** `sharpe * deflatedSharpe`: Sharpe discounted by survival probability. */
-    haircutSharpe: number;
-    minTrackRecordLen: number;
+    expectedMaxSharpe: number | null;
+    deflatedSharpe: number | null;
+    probabilisticSharpe: number | null;
+    /**
+     * `1 - deflatedSharpe`: the p-value of the test whose null is that this Sharpe
+     * is the best of `nTrials` zero-skill trials. Not the probability that the
+     * edge is a search artifact.
+     */
+    haircut: number | null;
+    /** `sharpe * deflatedSharpe`: the Sharpe scaled down by the deflated Sharpe. */
+    haircutSharpe: number | null;
+    /** Null when no finite track length is returned by the kernel. */
+    minTrackRecordLen: number | null;
     verdict: Verdict;
     explanation: string;
     methodologyVersion: string;
+    /** When present, deflation was withheld; its numeric sentinels are not estimates. */
+    statisticsError?: string;
     [k: string]: unknown;
 }
 /** What a candidate is scored on inside {@link percentileSelection}. */
@@ -218,14 +238,18 @@ export interface CandidateUtility {
 export interface PercentileSelectionResult {
     /** The percentile actually used, clamped to [0, 1]. */
     alpha: number;
-    /** True when alpha sits below the recommended floor of 0.3. */
+    /** True when alpha sits below the recommended floor of 0.3. Computed from
+     * `alpha` alone, so a refusal that had nothing to do with alpha (too few
+     * observations, a rejected block probability) does not raise it. */
     alpha_warning: boolean;
     /** Every candidate, in input order. */
     candidates: CandidateUtility[];
-    /** Index of the candidate with the best percentile utility (the robust pick), or null for empty input. */
+    /** Index of the robust pick, or null for empty or refused input. */
     selected: number | null;
-    /** Index of the candidate with the best point utility (the naive pick), or null for empty input. */
+    /** Index of the point winner, or null for empty or refused input. */
     point_argmax: number | null;
+    /** Null on accepted input; a refusal withholds the entire candidate field. */
+    input_error: string | null;
     /** Whether the two picks agree. Disagreement is the interesting case. */
     agrees_with_point_argmax: boolean;
     /** Optimism gap of the point winner: report this next to any headline utility. */
@@ -293,10 +317,13 @@ export interface CrowdingDecayPrior {
 }
 /**
  * A reason an agent was (or should be) demoted. The first five mirror the hard
- * eligibility gates in the scorer; the last three are advisory quality flags
- * that never gate.
+ * eligibility gates in the scorer; two more name the unavailability of a
+ * statistic the scorer does gate on. The last four are advisory quality flags
+ * that never gate. `selection_unavailable` is advisory because the scorer
+ * reports the selection axis and never consults it in `rank_eligible`, so an
+ * agent carrying it alone is still ranked.
  */
-export type FailReason = "failed_pass_k" | "dsr_below_bar" | "process_violation" | "bootstrap_insignificant" | "mandate_breached" | "high_selection_gap" | "is_rediscovery" | "oos_decay";
+export type FailReason = "failed_pass_k" | "dsr_below_bar" | "process_violation" | "bootstrap_insignificant" | "mandate_breached" | "deflation_unavailable" | "bootstrap_unavailable" | "selection_unavailable" | "high_selection_gap" | "is_rediscovery" | "oos_decay";
 /** Every disqualification/quality signal that fired for one scored agent. */
 export interface DisqualificationReport {
     agent_id: string;
@@ -305,7 +332,14 @@ export interface DisqualificationReport {
     reasons: FailReason[];
     [k: string]: unknown;
 }
-/** The FULL verdict: LITE on the winner plus the multiple-testing family + PBO. */
+/** Harvey-Liu-Zhu hurdle and its interpretation from the kernel. */
+export interface HlzGate {
+    tStat: number | null;
+    tThreshold: number;
+    passed: boolean;
+    explanation: string;
+}
+/** The FULL verdict: LITE on the winner plus multiple testing, PBO and HLZ. */
 export interface FullVerdict {
     honesty: HonestyVerdict;
     /** White's Reality Check p-value over the field. */
@@ -316,8 +350,12 @@ export interface FullVerdict {
     spaConsistentP: number;
     /** Romano-Wolf step-down: which field members are significant at α. */
     stepDown: boolean[];
-    /** CSCV Probability of Backtest Overfitting over the field. */
-    pbo: number;
+    /** CSCV estimate; null when unavailable, with a reason in pboError. */
+    pbo: number | null;
+    hlz: HlzGate;
+    /** When present, p-values of 1 and all-false stepDown are refusal sentinels. */
+    snoopingError?: string;
+    pboError?: string;
     [k: string]: unknown;
 }
 /** Options for a regime-conditional comparison. Regime labels are caller inputs. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@general-liquidity/sharpebench",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Luck-robust quantitative evaluation for trading agents: deflated Sharpe, pass^k reliability, process discipline, and risk gates, backed by the identical Rust kernel compiled to WebAssembly.",
   "keywords": [
     "trading",

package/pkg/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sharpebench-wasm",
   "description": "WASM bindings for SharpeBench's deterministic, luck-robust trading-agent scoring kernel.",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",