@general-liquidity/sharpebench 0.14.1 → 0.16.0

package/README.md

@@ -2,7 +2,7 @@
 
 **The luck-robust scoring kernel for AI trading agents.**
 
-Rank agents on risk-adjusted *skill that survives deflation* — not the luckiest run over one quarter. This is the **identical Rust kernel** that powers the [SharpeBench](https://github.com/general-liquidity/sharpebench) benchmark, compiled to WebAssembly, with a typed JS/TS API. No native add-on, no network — pure deterministic scoring.
+Rank agents on risk-adjusted *skill that survives deflation*, not the luckiest run over one quarter. This is the **identical Rust kernel** that powers the [SharpeBench](https://github.com/general-liquidity/sharpebench) benchmark, compiled to WebAssembly, with a typed JS/TS API. No native add-on and no network: pure deterministic scoring.
 
 ```bash
 npm install @general-liquidity/sharpebench
@@ -13,15 +13,18 @@ npm install @general-liquidity/sharpebench
 ```ts
 import { score, greeks, selfAudit } from "@general-liquidity/sharpebench";
 
-// Rank a field. Raw return is reported but is NEVER the rank key — an agent ranks
-// only if its edge survives deflation, pass^k reliability, and process discipline.
+// Rank a field. Raw return is reported but is NEVER the rank key. An agent ranks
+// only if its edge survives deflation, pass^k reliability, process discipline,
+// the stationary-bootstrap null, and the configured mandate. This tiny input
+// demonstrates the API shape; use the benchmark's full run geometry for a
+// meaningful eligibility verdict.
 const board = score([
   { agent_id: "skilled", runs: [{ returns: [0.002, 0.0021, 0.0019, 0.002] }] },
   { agent_id: "lucky",   runs: [{ returns: [0.05, 0, 0, 0] }] },
 ]);
 console.log(board[0].agent_id, board[0].deflated_sharpe, board[0].rank_eligible);
 
-// Prove the scorer resists known gaming attacks.
+// Run the scorer's built-in checks against its catalogued gaming attacks.
 console.log(selfAudit().all_defended); // true
 
 // Options tail-risk: a short-gamma position a linear Sharpe can't see.
@@ -34,17 +37,28 @@ 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 |
-| `auditBriefing(briefing, policy?)` | `BriefingAudit` — input-side salience-bias audit |
-| `scoreAllocation(trajectory, policy?)` | `AllocationReport` — weight-vector validity + L1 turnover |
-| `greeks(params)` | `GreeksResult` — Black-Scholes price + Greeks + tail-selling risk |
-| `canary(seed)` | `Canary` — a do-not-train contamination tripwire |
+| `selfAudit()` | `SelfAuditReport`, the benchmark's anti-gaming proof |
+| `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 tail-selling risk |
+| `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 |
+| `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 |
+| `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 package). The kernel is deterministic: the same input yields byte-identical scores on any platform.
+All inputs and outputs are fully typed (TypeScript declarations ship with the
+package). The npm tests compare the WASM package with the native kernel and
+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.
 
 ## Why luck-robust?
 
-Most agent leaderboards rank a raw Sharpe over a single short window — so they mostly measure noise. SharpeBench adds, as **ranking gates**: deflated Sharpe / PSR, pass^k reliability (clear the bar on *every* seed × window), field-wide significance, and process discipline (an order that skipped the risk gate zeroes the entry). See the [benchmark repo](https://github.com/general-liquidity/sharpebench) for the full methodology.
+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.
 
 ## License
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { AgentSubmission, AllocationPolicy, AllocationReport, AllocationTrajectory, Briefing, BriefingAudit, BriefingPolicy, Canary, CompositeScore, CrowdingDecayPrior, CrowdingParams, DisqualificationReport, FullVerdict, GreeksParams, GreeksResult, HonestyOpts, HonestyVerdict, PercentileSelectionOpts, PercentileSelectionResult, ScoreConfig, SelfAuditReport, UncertaintyInput, UncertaintySplit } from "./types.js";
+import type { AgentSubmission, AllocationPolicy, AllocationReport, AllocationTrajectory, Briefing, BriefingAudit, BriefingPolicy, Canary, CompositeScore, CrowdingDecayPrior, CrowdingParams, DisqualificationReport, FullVerdict, GreeksParams, GreeksResult, HonestyOpts, HonestyVerdict, PercentileSelectionOpts, PercentileSelectionResult, RegimeCompareOpts, RegimeDistributionReport, ScoreConfig, SelfAuditReport, UncertaintyInput, UncertaintySplit } from "./types.js";
 export * from "./types.js";
 /**
  * Score and rank a field of submissions on the luck-robust composite. Returns the
@@ -78,3 +78,9 @@ export declare function crowdingHalfLife(adoption: number, params: CrowdingParam
  * oos_decay) never gate, and nothing here changes eligibility semantics.
  */
 export declare function classifyDisqualification(submissions: AgentSubmission[], config?: ScoreConfig): DisqualificationReport[];
+/**
+ * Compare two aligned return streams inside caller-supplied market regimes.
+ * The report separates zero/no-trade mass from continuous returns and names a
+ * pooled edge whose sign reverses in a sufficiently supported regime.
+ */
+export declare function regimeCompare(returnsA: number[], returnsB: number[], regimes: string[], opts?: RegimeCompareOpts): RegimeDistributionReport;

package/dist/index.js

@@ -49,6 +49,7 @@ exports.percentileSelection = percentileSelection;
 exports.decomposeUncertainty = decomposeUncertainty;
 exports.crowdingHalfLife = crowdingHalfLife;
 exports.classifyDisqualification = classifyDisqualification;
+exports.regimeCompare = regimeCompare;
 /**
  * `@general-liquidity/sharpebench` — the luck-robust scoring kernel for AI trading
  * agents, as a typed JS API over the *identical* Rust kernel that powers the
@@ -242,3 +243,18 @@ function crowdingHalfLife(adoption, params) {
 function classifyDisqualification(submissions, config) {
     return parse(kernel.classify_disqualification(JSON.stringify(submissions), optJson(config)));
 }
+/**
+ * Compare two aligned return streams inside caller-supplied market regimes.
+ * The report separates zero/no-trade mass from continuous returns and names a
+ * pooled edge whose sign reverses in a sufficiently supported regime.
+ */
+function regimeCompare(returnsA, returnsB, regimes, opts) {
+    const options = {};
+    if (opts?.zeroTol !== undefined)
+        options.zero_tol = opts.zeroTol;
+    if (opts?.minPeriods !== undefined)
+        options.min_periods = opts.minPeriods;
+    if (opts?.tieTol !== undefined)
+        options.tie_tol = opts.tieTol;
+    return parse(kernel.regime_compare(JSON.stringify(returnsA), JSON.stringify(returnsB), JSON.stringify(regimes), optJson(options)));
+}

package/dist/types.d.ts

@@ -303,3 +303,41 @@ export interface FullVerdict {
     pbo: number;
     [k: string]: unknown;
 }
+/** Options for a regime-conditional comparison. Regime labels are caller inputs. */
+export interface RegimeCompareOpts {
+    zeroTol?: number;
+    minPeriods?: number;
+    tieTol?: number;
+}
+export interface ZagaSplit {
+    n: number;
+    zero_mass: number;
+    n_nonzero: number;
+    positive_share: number;
+    cont_mean: number;
+    cont_sd: number;
+    cont_median: number;
+    gamma_shape: number;
+    gamma_rate: number;
+    pooled_mean: number;
+}
+export interface RegimeComparison {
+    regime: string;
+    n_periods: number;
+    a: ZagaSplit;
+    b: ZagaSplit;
+    zero_mass_gap: number;
+    mean_gap: number;
+    cont_mean_gap: number;
+    ks_statistic: number;
+    edge_sign: -1 | 0 | 1;
+    counted: boolean;
+}
+export interface RegimeDistributionReport {
+    regimes: RegimeComparison[];
+    pooled_mean_gap: number;
+    pooled_edge_sign: -1 | 0 | 1;
+    reversal_regimes: string[];
+    pooled_hides_reversal: boolean;
+    edge_dispersion: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@general-liquidity/sharpebench",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "description": "The luck-robust scoring kernel for AI trading agents — deflated Sharpe, pass^k reliability, and process-discipline gates. The identical Rust kernel as the SharpeBench benchmark, compiled to WASM.",
   "keywords": [
     "trading",
@@ -29,6 +29,7 @@
   "scripts": {
     "build": "tsc",
     "test": "node --test \"test/**/*.test.js\"",
+    "smoke-install": "node test/smoke-install.mjs",
     "prepublishOnly": "tsc && node -e \"require('fs').rmSync('pkg/.gitignore',{force:true})\""
   },
   "devDependencies": {

package/pkg/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sharpebench-wasm",
   "description": "WASM bindings for the SharpeBench scoring kernel (consumed by Gordon/Bun via the identical kernel).",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",
@@ -14,4 +14,4 @@
   ],
   "main": "sharpebench.js",
   "types": "sharpebench.d.ts"
-}
+}

package/pkg/sharpebench.d.ts

@@ -19,6 +19,8 @@ export function is_my_sharpe_real_full(field_json: string, winner_idx: number, c
 
 export function percentile_selection(candidates_json: string, params_json: string): string;
 
+export function regime_compare(returns_a_json: string, returns_b_json: string, regimes_json: string, options_json: string): string;
+
 export function score(submissions_json: string, config_json: string): string;
 
 export function score_agent(submission_json: string, config_json: string): string;

package/pkg/sharpebench.js

@@ -196,6 +196,35 @@ function percentile_selection(candidates_json, params_json) {
 }
 exports.percentile_selection = percentile_selection;
 
+/**
+ * @param {string} returns_a_json
+ * @param {string} returns_b_json
+ * @param {string} regimes_json
+ * @param {string} options_json
+ * @returns {string}
+ */
+function regime_compare(returns_a_json, returns_b_json, regimes_json, options_json) {
+    let deferred5_0;
+    let deferred5_1;
+    try {
+        const ptr0 = passStringToWasm0(returns_a_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(returns_b_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passStringToWasm0(regimes_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len2 = WASM_VECTOR_LEN;
+        const ptr3 = passStringToWasm0(options_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len3 = WASM_VECTOR_LEN;
+        const ret = wasm.regime_compare(ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3);
+        deferred5_0 = ret[0];
+        deferred5_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred5_0, deferred5_1, 1);
+    }
+}
+exports.regime_compare = regime_compare;
+
 /**
  * @param {string} submissions_json
  * @param {string} config_json

package/pkg/sharpebench_bg.wasm.d.ts

@@ -10,6 +10,7 @@ export const greeks: (a: number, b: number) => [number, number];
 export const is_my_sharpe_real: (a: number, b: number, c: number, d: number) => [number, number];
 export const is_my_sharpe_real_full: (a: number, b: number, c: number, d: number, e: number) => [number, number];
 export const percentile_selection: (a: number, b: number, c: number, d: number) => [number, number];
+export const regime_compare: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number];
 export const score: (a: number, b: number, c: number, d: number) => [number, number];
 export const score_agent: (a: number, b: number, c: number, d: number) => [number, number];
 export const score_allocation: (a: number, b: number, c: number, d: number) => [number, number];