@general-liquidity/sharpebench 0.0.6 → 0.0.12

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { AgentSubmission, AllocationPolicy, AllocationReport, AllocationTrajectory, Briefing, BriefingAudit, BriefingPolicy, Canary, CompositeScore, GreeksParams, GreeksResult, ScoreConfig, SelfAuditReport } from "./types.js";
+import type { AgentSubmission, AllocationPolicy, AllocationReport, AllocationTrajectory, Briefing, BriefingAudit, BriefingPolicy, Canary, CompositeScore, FullVerdict, GreeksParams, GreeksResult, HonestyOpts, HonestyVerdict, ScoreConfig, SelfAuditReport } from "./types.js";
 export * from "./types.js";
 /**
  * Score and rank a field of submissions on the luck-robust composite. Returns the
@@ -21,3 +21,19 @@ export declare function scoreAllocation(trajectory: AllocationTrajectory, policy
 export declare function greeks(params: GreeksParams): GreeksResult;
 /** Derive a deterministic do-not-train contamination tripwire from seed material. */
 export declare function canary(seed: string): Canary;
+/**
+ * "Is my Sharpe real, or an artifact of luck and multiple testing?" — the LITE
+ * backtest-honesty verdict over one per-period return series. Deflates the observed
+ * Sharpe for `nTrials` (the search footprint), then renders Pass / Borderline / Fail
+ * with PSR, expected-max-Sharpe, haircut, and MinTRL.
+ */
+export declare function isMySharpeReal(returns: number[], opts: HonestyOpts): HonestyVerdict;
+/**
+ * The FULL verdict: the winner's LITE verdict plus the multiple-testing family
+ * (White's Reality Check, Hansen's SPA + consistent variant, Romano-Wolf step-down)
+ * and the CSCV Probability of Backtest Overfitting over the whole field.
+ *
+ * `field` is N rows (candidate strategies) × T cols (time); `winnerIdx` is the row
+ * whose LITE verdict is reported.
+ */
+export declare function isMySharpeRealFull(field: number[][], winnerIdx: number, opts: HonestyOpts): FullVerdict;

package/dist/index.js

@@ -43,6 +43,8 @@ exports.auditBriefing = auditBriefing;
 exports.scoreAllocation = scoreAllocation;
 exports.greeks = greeks;
 exports.canary = canary;
+exports.isMySharpeReal = isMySharpeReal;
+exports.isMySharpeRealFull = isMySharpeRealFull;
 /**
  * `@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
@@ -103,3 +105,64 @@ function greeks(params) {
 function canary(seed) {
     return parse(kernel.canary(seed));
 }
+/** Map camelCase {@link HonestyOpts} → the snake_case `HonestyConfig` JSON the kernel reads. */
+function honestyConfigJson(opts) {
+    const cfg = { n_trials: opts.nTrials };
+    if (opts.trialsSrStd !== undefined)
+        cfg.trials_sr_std = opts.trialsSrStd;
+    if (opts.confidence !== undefined)
+        cfg.confidence = opts.confidence;
+    if (opts.borderline !== undefined)
+        cfg.borderline = opts.borderline;
+    if (opts.srBenchmark !== undefined)
+        cfg.sr_benchmark = opts.srBenchmark;
+    return JSON.stringify(cfg);
+}
+/** Map the kernel's snake_case HonestyVerdict JSON → the camelCase {@link HonestyVerdict}. */
+function toHonestyVerdict(raw) {
+    return {
+        sharpe: raw.sharpe,
+        nObs: raw.n_obs,
+        skew: raw.skew,
+        kurtosis: raw.kurtosis,
+        nTrials: raw.n_trials,
+        expectedMaxSharpe: raw.expected_max_sharpe,
+        deflatedSharpe: raw.deflated_sharpe,
+        probabilisticSharpe: raw.probabilistic_sharpe,
+        haircut: raw.haircut,
+        haircutSharpe: raw.haircut_sharpe,
+        minTrackRecordLen: raw.min_track_record_len,
+        verdict: raw.verdict,
+        explanation: raw.explanation,
+        methodologyVersion: raw.methodology_version,
+    };
+}
+/**
+ * "Is my Sharpe real, or an artifact of luck and multiple testing?" — the LITE
+ * backtest-honesty verdict over one per-period return series. Deflates the observed
+ * Sharpe for `nTrials` (the search footprint), then renders Pass / Borderline / Fail
+ * with PSR, expected-max-Sharpe, haircut, and MinTRL.
+ */
+function isMySharpeReal(returns, opts) {
+    const raw = parse(kernel.is_my_sharpe_real(JSON.stringify(returns), honestyConfigJson(opts)));
+    return toHonestyVerdict(raw);
+}
+/**
+ * The FULL verdict: the winner's LITE verdict plus the multiple-testing family
+ * (White's Reality Check, Hansen's SPA + consistent variant, Romano-Wolf step-down)
+ * and the CSCV Probability of Backtest Overfitting over the whole field.
+ *
+ * `field` is N rows (candidate strategies) × T cols (time); `winnerIdx` is the row
+ * whose LITE verdict is reported.
+ */
+function isMySharpeRealFull(field, winnerIdx, opts) {
+    const raw = parse(kernel.is_my_sharpe_real_full(JSON.stringify(field), winnerIdx, honestyConfigJson(opts)));
+    return {
+        honesty: toHonestyVerdict(raw.honesty),
+        realityCheckP: raw.reality_check_p,
+        spaP: raw.spa_p,
+        spaConsistentP: raw.spa_consistent_p,
+        stepDown: raw.step_down,
+        pbo: raw.pbo,
+    };
+}

package/dist/types.d.ts

@@ -126,3 +126,57 @@ export interface Canary {
     id: string;
     token: string;
 }
+/** The headline call: does the edge survive deflation for the search? */
+export type Verdict = "Pass" | "Borderline" | "Fail";
+/**
+ * Options for {@link isMySharpeReal}. `nTrials` is the multiple-testing footprint
+ * (how many strategies/configs were tried before this one was kept) and is the one
+ * the caller must think about — `nTrials = 1` is almost always a lie.
+ */
+export interface HonestyOpts {
+    /** Number of strategy trials behind this result. REQUIRED. */
+    nTrials: number;
+    /** Cross-trial Sharpe dispersion. Omit → estimated at 0.5 and flagged. */
+    trialsSrStd?: 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. */
+    srBenchmark?: number;
+}
+/** The LITE verdict: everything derivable from one return series. */
+export interface HonestyVerdict {
+    sharpe: number;
+    nObs: number;
+    skew: number;
+    kurtosis: number;
+    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;
+    verdict: Verdict;
+    explanation: string;
+    methodologyVersion: string;
+    [k: string]: unknown;
+}
+/** The FULL verdict: LITE on the winner plus the multiple-testing family + PBO. */
+export interface FullVerdict {
+    honesty: HonestyVerdict;
+    /** White's Reality Check p-value over the field. */
+    realityCheckP: number;
+    /** Hansen's SPA p-value (liberal/lower studentized variant). */
+    spaP: number;
+    /** Hansen's consistent SPA p-value. */
+    spaConsistentP: number;
+    /** Romano-Wolf step-down: which field members are significant at α. */
+    stepDown: boolean[];
+    /** CSCV Probability of Backtest Overfitting over the field. */
+    pbo: number;
+    [k: string]: unknown;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@general-liquidity/sharpebench",
-  "version": "0.0.6",
+  "version": "0.0.12",
   "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",

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.0.6",
+  "version": "0.0.12",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",

package/pkg/sharpebench.d.ts

@@ -7,6 +7,10 @@ export function canary(seed: string): string;
 
 export function greeks(params_json: string): string;
 
+export function is_my_sharpe_real(returns_json: string, config_json: string): string;
+
+export function is_my_sharpe_real_full(field_json: string, winner_idx: number, config_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

@@ -63,6 +63,53 @@ function greeks(params_json) {
 }
 exports.greeks = greeks;
 
+/**
+ * @param {string} returns_json
+ * @param {string} config_json
+ * @returns {string}
+ */
+function is_my_sharpe_real(returns_json, config_json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(returns_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(config_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.is_my_sharpe_real(ptr0, len0, ptr1, len1);
+        deferred3_0 = ret[0];
+        deferred3_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+exports.is_my_sharpe_real = is_my_sharpe_real;
+
+/**
+ * @param {string} field_json
+ * @param {number} winner_idx
+ * @param {string} config_json
+ * @returns {string}
+ */
+function is_my_sharpe_real_full(field_json, winner_idx, config_json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(field_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(config_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.is_my_sharpe_real_full(ptr0, len0, winner_idx, ptr1, len1);
+        deferred3_0 = ret[0];
+        deferred3_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+exports.is_my_sharpe_real_full = is_my_sharpe_real_full;
+
 /**
  * @param {string} submissions_json
  * @param {string} config_json

package/pkg/sharpebench_bg.wasm.d.ts

@@ -4,6 +4,8 @@ export const memory: WebAssembly.Memory;
 export const audit_briefing: (a: number, b: number, c: number, d: number) => [number, number];
 export const canary: (a: number, b: number) => [number, number];
 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 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];