@general-liquidity/sharpebench 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { AgentSubmission, AllocationPolicy, AllocationReport, AllocationTrajectory, Briefing, BriefingAudit, BriefingPolicy, Canary, CompositeScore, FullVerdict, GreeksParams, GreeksResult, HonestyOpts, HonestyVerdict, ScoreConfig, SelfAuditReport } from "./types.js";
+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";
 export * from "./types.js";
 /**
  * Score and rank a field of submissions on the luck-robust composite. Returns the
@@ -37,3 +37,44 @@ export declare function isMySharpeReal(returns: number[], opts: HonestyOpts): Ho
  * whose LITE verdict is reported.
  */
 export declare function isMySharpeRealFull(field: number[][], winnerIdx: number, opts: HonestyOpts): FullVerdict;
+/**
+ * Rank candidate return streams on a percentile of their bootstrapped utility
+ * instead of the point-estimate argmax, so the winner has to be good on most
+ * resampled histories rather than on the one that happened to be observed.
+ *
+ * `candidates` is one per-period return array per candidate. The result names
+ * both the point winner and the percentile winner; disagreement between them is
+ * the interesting case, and the point winner's `optimism_gap` is the number to
+ * report next to any headline utility. An `alpha` below 0.3 still computes but
+ * sets `alpha_warning` (the extreme lower tail is decided by a handful of
+ * unlucky resamples). Deterministic given (candidates, seed).
+ */
+export declare function percentileSelection(candidates: number[][], opts?: PercentileSelectionOpts): PercentileSelectionResult;
+/**
+ * Decompose the uncertainty behind one scored case into three legs, reported
+ * side by side and never summed: aleatoric (irreducible outcome noise; stop
+ * looking), epistemic (reducible ignorance; keep looking), and distributional
+ * (the reference cannot vouch for this case). Any input may be omitted; the
+ * matching leg then reports what it honestly can on no evidence.
+ *
+ * The result's `epistemic_caveat` is load-bearing: the epistemic leg is a lower
+ * bound, never an upper one, because unanimous or correlated signals understate
+ * it. Treat only high readings as informative.
+ */
+export declare function decomposeUncertainty(input: UncertaintyInput): UncertaintySplit;
+/**
+ * Expected edge half-life under a crowding decay model:
+ * `ln2 / (theta + deltaMax * adoption^curvature)`, in periods of the caller's
+ * IC series. The output is a model prior, reported never gating: it comes out
+ * of a model, not out of a dataset, and nothing should rank on it. There is
+ * deliberately no default calibration; the caller owns every rate.
+ */
+export declare function crowdingHalfLife(adoption: number, params: CrowdingParams): CrowdingDecayPrior;
+/**
+ * Name every disqualification/quality signal that fired for each agent in a
+ * field of submissions (the same input {@link score} takes). Pure legibility
+ * over the composite score: the first five reasons mirror the scorer's hard
+ * eligibility gates, the advisory ones (high_selection_gap, is_rediscovery,
+ * oos_decay) never gate, and nothing here changes eligibility semantics.
+ */
+export declare function classifyDisqualification(submissions: AgentSubmission[], config?: ScoreConfig): DisqualificationReport[];

package/dist/index.js

@@ -45,6 +45,10 @@ exports.greeks = greeks;
 exports.canary = canary;
 exports.isMySharpeReal = isMySharpeReal;
 exports.isMySharpeRealFull = isMySharpeRealFull;
+exports.percentileSelection = percentileSelection;
+exports.decomposeUncertainty = decomposeUncertainty;
+exports.crowdingHalfLife = crowdingHalfLife;
+exports.classifyDisqualification = classifyDisqualification;
 /**
  * `@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
@@ -166,3 +170,75 @@ function isMySharpeRealFull(field, winnerIdx, opts) {
         pbo: raw.pbo,
     };
 }
+/**
+ * Rank candidate return streams on a percentile of their bootstrapped utility
+ * instead of the point-estimate argmax, so the winner has to be good on most
+ * resampled histories rather than on the one that happened to be observed.
+ *
+ * `candidates` is one per-period return array per candidate. The result names
+ * both the point winner and the percentile winner; disagreement between them is
+ * the interesting case, and the point winner's `optimism_gap` is the number to
+ * report next to any headline utility. An `alpha` below 0.3 still computes but
+ * sets `alpha_warning` (the extreme lower tail is decided by a handful of
+ * unlucky resamples). Deterministic given (candidates, seed).
+ */
+function percentileSelection(candidates, opts) {
+    const params = {};
+    if (opts?.utility !== undefined)
+        params.utility = opts.utility;
+    if (opts?.alpha !== undefined)
+        params.alpha = opts.alpha;
+    if (opts?.seed !== undefined)
+        params.seed = opts.seed;
+    if (opts?.nBoot !== undefined)
+        params.n_boot = opts.nBoot;
+    if (opts?.blockProb !== undefined)
+        params.block_prob = opts.blockProb;
+    return parse(kernel.percentile_selection(JSON.stringify(candidates), optJson(params)));
+}
+/**
+ * Decompose the uncertainty behind one scored case into three legs, reported
+ * side by side and never summed: aleatoric (irreducible outcome noise; stop
+ * looking), epistemic (reducible ignorance; keep looking), and distributional
+ * (the reference cannot vouch for this case). Any input may be omitted; the
+ * matching leg then reports what it honestly can on no evidence.
+ *
+ * The result's `epistemic_caveat` is load-bearing: the epistemic leg is a lower
+ * bound, never an upper one, because unanimous or correlated signals understate
+ * it. Treat only high readings as informative.
+ */
+function decomposeUncertainty(input) {
+    return parse(kernel.decompose_uncertainty(JSON.stringify({
+        outcomes: input.outcomes,
+        signals: input.signals,
+        case_returns: input.caseReturns,
+        reference_returns: input.referenceReturns,
+    })));
+}
+/**
+ * Expected edge half-life under a crowding decay model:
+ * `ln2 / (theta + deltaMax * adoption^curvature)`, in periods of the caller's
+ * IC series. The output is a model prior, reported never gating: it comes out
+ * of a model, not out of a dataset, and nothing should rank on it. There is
+ * deliberately no default calibration; the caller owns every rate.
+ */
+function crowdingHalfLife(adoption, params) {
+    const cfg = {
+        adoption,
+        theta: params.theta,
+        delta_max: params.deltaMax,
+    };
+    if (params.curvature !== undefined)
+        cfg.curvature = params.curvature;
+    return parse(kernel.crowding_half_life(JSON.stringify(cfg)));
+}
+/**
+ * Name every disqualification/quality signal that fired for each agent in a
+ * field of submissions (the same input {@link score} takes). Pure legibility
+ * over the composite score: the first five reasons mirror the scorer's hard
+ * eligibility gates, the advisory ones (high_selection_gap, is_rediscovery,
+ * oos_decay) never gate, and nothing here changes eligibility semantics.
+ */
+function classifyDisqualification(submissions, config) {
+    return parse(kernel.classify_disqualification(JSON.stringify(submissions), optJson(config)));
+}

package/dist/types.d.ts

@@ -165,6 +165,129 @@ export interface HonestyVerdict {
     methodologyVersion: string;
     [k: string]: unknown;
 }
+/** What a candidate is scored on inside {@link percentileSelection}. */
+export type SelectionUtility = "mean_return" | "sharpe";
+/** Options for {@link percentileSelection}. Omit for the recommended defaults. */
+export interface PercentileSelectionOpts {
+    /** Utility each candidate is scored on. Default `"mean_return"`. */
+    utility?: SelectionUtility;
+    /**
+     * Percentile of the bootstrapped utility distribution to rank on, in [0, 1].
+     * Default 0.5 (the middle of the band). Below 0.3 the result carries
+     * `alphaWarning: true`: the extreme lower tail is decided by a handful of
+     * unlucky resamples. The result is still computed; the warning flags a
+     * choice, it does not veto one.
+     */
+    alpha?: number;
+    /** PRNG seed; the result is deterministic given (data, seed). Default 0. */
+    seed?: number;
+    /** Bootstrap resamples per candidate. Default 2000. */
+    nBoot?: number;
+    /** Stationary-bootstrap block-restart probability. Default 0.1. */
+    blockProb?: number;
+}
+/** Per-candidate result inside a {@link PercentileSelectionResult}. */
+export interface CandidateUtility {
+    /** Position of this candidate in the input array. */
+    index: number;
+    /** Utility on the observed path: the number a naive argmax would rank on. */
+    point_utility: number;
+    /** The alpha percentile of the bootstrapped utility distribution. */
+    percentile_utility: number;
+    /** `point_utility - percentile_utility`: how much of the headline number fails to survive resampling. */
+    optimism_gap: number;
+}
+/** Selection on a percentile of a bootstrapped utility distribution. */
+export interface PercentileSelectionResult {
+    /** The percentile actually used, clamped to [0, 1]. */
+    alpha: number;
+    /** True when alpha sits below the recommended floor of 0.3. */
+    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. */
+    selected: number | null;
+    /** Index of the candidate with the best point utility (the naive pick), or null for empty input. */
+    point_argmax: number | 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. */
+    point_winner_optimism: number;
+    [k: string]: unknown;
+}
+/** Inputs for {@link decomposeUncertainty}. Every field is optional; a missing leg's input reads as empty. */
+export interface UncertaintyInput {
+    /** Realized binary outcomes (true or 1 = the call was right). Drives the aleatoric leg. */
+    outcomes?: Array<boolean | number>;
+    /** Independent per-decision confidence streams for the same decisions. Drives the epistemic leg. */
+    signals?: number[][];
+    /** The case's per-period returns. Drives the distributional leg (with the reference). */
+    caseReturns?: number[];
+    /** The reference per-period returns the case is compared against. */
+    referenceReturns?: number[];
+}
+/**
+ * The three legs of uncertainty behind one scored case, each on [0, 1] and
+ * reported side by side, never summed. High aleatoric says stop looking, high
+ * epistemic says keep looking, high distributional says the case is outside
+ * what the reference can speak to.
+ */
+export interface UncertaintySplit {
+    /** Irreducible outcome noise (base-rate variance; 1 = a fair coin). */
+    aleatoric: number;
+    /** Reducible ignorance, from signal disagreement plus evidence thinness. */
+    epistemic: number;
+    /** Unlikeness to the reference series (location or dispersion shift). */
+    distributional: number;
+    /**
+     * Load-bearing limitation, spelled out by the kernel: the epistemic leg is a
+     * lower bound, never an upper one. Unanimous or correlated signals understate
+     * it, so treat only high readings as informative.
+     */
+    epistemic_caveat: string;
+    [k: string]: unknown;
+}
+/**
+ * Parameters of the crowding decay model. All rates are per period of the
+ * caller's IC series; there is deliberately no default calibration, because a
+ * stock calibration would smuggle a modelled number in as if it were measured.
+ */
+export interface CrowdingParams {
+    /** Natural mean-reversion rate of the edge at zero adoption. */
+    theta: number;
+    /** Crowding decay rate at full adoption. */
+    deltaMax: number;
+    /** Exponent on adoption (1 = linear). Default 1. */
+    curvature?: number;
+}
+/** The expected half-life implied by the crowding model: a prior, not a measurement. */
+export interface CrowdingDecayPrior {
+    /** Adoption used, clamped to [0, 1]. */
+    adoption: number;
+    /** theta, echoed back. */
+    natural_reversion: number;
+    /** The adoption-driven decay component delta(phi). */
+    crowding_decay: number;
+    /** `ln2 / (theta + delta(phi))` in periods, or null when the model says the edge never decays. */
+    expected_half_life: number | null;
+    /** Names what this is: a model prior, reported never gating. */
+    note: string;
+    [k: string]: unknown;
+}
+/**
+ * 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.
+ */
+export type FailReason = "failed_pass_k" | "dsr_below_bar" | "process_violation" | "bootstrap_insignificant" | "mandate_breached" | "high_selection_gap" | "is_rediscovery" | "oos_decay";
+/** Every disqualification/quality signal that fired for one scored agent. */
+export interface DisqualificationReport {
+    agent_id: string;
+    rank_eligible: boolean;
+    /** Reasons in stable order; empty means no signal fired. */
+    reasons: FailReason[];
+    [k: string]: unknown;
+}
 /** The FULL verdict: LITE on the winner plus the multiple-testing family + PBO. */
 export interface FullVerdict {
     honesty: HonestyVerdict;

package/package.json

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

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

package/pkg/sharpebench.d.ts

@@ -5,12 +5,20 @@ export function audit_briefing(briefing_json: string, policy_json: string): stri
 
 export function canary(seed: string): string;
 
+export function classify_disqualification(submissions_json: string, config_json: string): string;
+
+export function crowding_half_life(params_json: string): string;
+
+export function decompose_uncertainty(input_json: 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 percentile_selection(candidates_json: string, params_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

@@ -43,6 +43,69 @@ function canary(seed) {
 }
 exports.canary = canary;
 
+/**
+ * @param {string} submissions_json
+ * @param {string} config_json
+ * @returns {string}
+ */
+function classify_disqualification(submissions_json, config_json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(submissions_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.classify_disqualification(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.classify_disqualification = classify_disqualification;
+
+/**
+ * @param {string} params_json
+ * @returns {string}
+ */
+function crowding_half_life(params_json) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ptr0 = passStringToWasm0(params_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.crowding_half_life(ptr0, len0);
+        deferred2_0 = ret[0];
+        deferred2_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+exports.crowding_half_life = crowding_half_life;
+
+/**
+ * @param {string} input_json
+ * @returns {string}
+ */
+function decompose_uncertainty(input_json) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ptr0 = passStringToWasm0(input_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.decompose_uncertainty(ptr0, len0);
+        deferred2_0 = ret[0];
+        deferred2_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+exports.decompose_uncertainty = decompose_uncertainty;
+
 /**
  * @param {string} params_json
  * @returns {string}
@@ -110,6 +173,29 @@ function is_my_sharpe_real_full(field_json, winner_idx, config_json) {
 }
 exports.is_my_sharpe_real_full = is_my_sharpe_real_full;
 
+/**
+ * @param {string} candidates_json
+ * @param {string} params_json
+ * @returns {string}
+ */
+function percentile_selection(candidates_json, params_json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(candidates_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(params_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.percentile_selection(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.percentile_selection = percentile_selection;
+
 /**
  * @param {string} submissions_json
  * @param {string} config_json

package/pkg/sharpebench_bg.wasm.d.ts

@@ -3,9 +3,13 @@
 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 classify_disqualification: (a: number, b: number, c: number, d: number) => [number, number];
+export const crowding_half_life: (a: number, b: number) => [number, number];
+export const decompose_uncertainty: (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 percentile_selection: (a: number, b: number, c: number, d: 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];