@insiderfinance/totalfinance 0.1.0

package/modules/risk/dist/research.js

@@ -0,0 +1,752 @@
+import { ensureBooleanWhenPresent, ensureEnumWhenPresent, ensureFiniteWhenPresent, } from './options-internal.js';
+/**
+ * Research hygiene (spec §15.5) — the statistics that keep a backtest honest.
+ *
+ * Selecting the best of many strategy configurations inflates the in-sample Sharpe; reusing data
+ * across train/test boundaries leaks the future into the past. This module provides the standard
+ * defences:
+ *
+ *   • **Probabilistic / deflated Sharpe** (Bailey & López de Prado) — the probability that the true
+ *     Sharpe exceeds a benchmark, adjusted for sample length, skew/kurtosis, and the number of trials.
+ *   • **Multiple-testing correction** — Bonferroni, Šidák, Holm (FWER) and Benjamini–Hochberg (FDR).
+ *   • **Walk-forward** and **purged & embargoed K-fold** splitters for leakage-free evaluation.
+ *   • **Parameter-sweep diagnostics**, **train/test leakage** checks, and a **survivorship-bias** flag.
+ *
+ * Depends only on `@insiderfinance/totalfinance/core` and `@insiderfinance/totalfinance/math`.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, ensureFinite, ensureKnownKeys, requireArgumentArray, requireArgumentObject, seriesFacade, WarningCode, warning, } from '../../core/dist/index.js';
+import { kurtosis as mathKurtosis, mean, normalCdf, normalInverseCdf, skewness, standardDeviation, } from '../../math/dist/index.js';
+/** Euler–Mascheroni constant, used in the expected-maximum-Sharpe formula. */
+const EULER_MASCHERONI = 0.5772156649015329;
+/** The documented `sharpeStatistics` option keys. */
+const SHARPE_STATS_OPTIONS_KEYS = ['riskFreeRate'];
+/**
+ * Sample Sharpe statistics of a return series: the per-observation (non-annualized) Sharpe plus the
+ * skewness and (non-excess) kurtosis that the probabilistic-Sharpe adjustment needs.
+ */
+export function sharpeStatistics(returns, options = {}) {
+    const functionName = 'sharpeStatistics';
+    // `null` slips past the `= {}` default and would die on the first option read — reject it typed.
+    requireArgumentObject(functionName, 'options', options);
+    // Law 12: a misspelled knob (`riskfreeRate` running at the 0 default) must throw, never no-op.
+    ensureKnownKeys(functionName, 'options', options, SHARPE_STATS_OPTIONS_KEYS);
+    requireArgumentArray('sharpeStatistics', 'returns', returns);
+    const n = returns.length;
+    if (n < 3) {
+        throw new InputError(`${functionName}: need ≥ 3 returns, got ${n}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { observations: n },
+        });
+    }
+    ensureFiniteWhenPresent(options.riskFreeRate, 'riskFreeRate', 'sharpeStatistics');
+    const rf = options.riskFreeRate ?? 0;
+    ensureFinite(rf, 'riskFreeRate', functionName);
+    const excess = new Array(n);
+    for (let i = 0; i < n; i++) {
+        ensureFinite(returns[i], `returns[${i}]`, functionName);
+        excess[i] = returns[i] - rf;
+    }
+    const sd = standardDeviation(returns);
+    const degenerate = !(sd > 0);
+    return {
+        sharpe: degenerate ? null : mean(excess) / sd,
+        observations: n,
+        skewness: skewness(returns),
+        kurtosis: mathKurtosis(returns, { excess: false }),
+        // The applied risk-free default and units (dx §2.4): per-observation, never annualized here.
+        ...researchReport({ riskFreeRate: rf, units: 'per-observation', observations: n }, degenerate
+            ? [
+                warning(WarningCode.RiskSharpeUndefined, `${functionName}: returns have zero variance (standard deviation ${sd}); the Sharpe ratio is undefined and reported as null.`, 'warn', { standardDeviation: sd, observations: n }),
+            ]
+            : []),
+    };
+}
+/** The PSR number itself — shared by the public envelope and the deflation/protocol callers. */
+/**
+ * The PSR kernel; `null` when the statistics carry no Sharpe (a zero-variance series): the
+ * probability of an undefined ratio beating a benchmark is not a number (C hygiene).
+ */
+function psrKernel(stats, benchmarkSharpe, functionName) {
+    requireArgumentObject(functionName, 'stats', stats);
+    const { sharpe: sr, observations: n, skewness: g3, kurtosis: g4 } = stats;
+    if (sr === null)
+        return null;
+    ensureFinite(sr, 'sharpe', functionName);
+    ensureFinite(benchmarkSharpe, 'benchmarkSharpe', functionName);
+    if (n < 2) {
+        throw new InputError(`${functionName}: need ≥ 2 observations, got ${n}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { observations: n },
+        });
+    }
+    // standard error of the Sharpe estimator under non-normality
+    const denom = 1 - g3 * sr + ((g4 - 1) / 4) * sr * sr;
+    if (!(denom > 0)) {
+        throw new InputError(`${functionName}: the Sharpe estimator variance is non-positive (1 − γ₃·SR + (γ₄−1)/4·SR² = ${denom.toFixed(4)}); the moment estimates are inconsistent.`, { code: ErrorCode.InputOutOfRange, context: { denom } });
+    }
+    return normalCdf(((sr - benchmarkSharpe) * Math.sqrt(n - 1)) / Math.sqrt(denom));
+}
+function undefinedSharpeWarning(functionName) {
+    return warning(WarningCode.RiskSharpeUndefined, `${functionName}: the statistics carry no Sharpe ratio (a zero-variance series); the result is null.`, 'warn');
+}
+/**
+ * Probabilistic Sharpe Ratio (Bailey & López de Prado 2012): the probability that the true Sharpe
+ * exceeds `benchmarkSharpe`, given the observed Sharpe, sample length, and return non-normality.
+ * `benchmarkSharpe` is in the same per-observation units as `statistics.sharpe` (default 0). Returns the
+ * standard `Computed` envelope (`value` = the probability); the applied `benchmarkSharpe: 0`
+ * default is echoed in `assumptions` (dx §2.4, never silently applied).
+ */
+function probabilisticSharpeRatioResult(statistics, benchmarkSharpe = 0) {
+    const value = psrKernel(statistics, benchmarkSharpe, 'probabilisticSharpeRatio');
+    return {
+        value,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            benchmarkSharpe,
+            observations: statistics.observations,
+        },
+        diagnostics: {
+            warnings: value === null ? [undefinedSharpeWarning('probabilisticSharpeRatio')] : [],
+        },
+    };
+}
+/** Plain probability; use `.explain()` for the benchmark and observation count. */
+export const probabilisticSharpeRatio = seriesFacade('probabilisticSharpeRatio', (stats, benchmarkSharpe = 0) => probabilisticSharpeRatioResult(stats, benchmarkSharpe).value, probabilisticSharpeRatioResult);
+/** The two documented shapes of `deflatedSharpeRatio`'s `trials` union, guarded per branch. */
+const TRIAL_SHARPES_KEYS = ['trialSharpes'];
+const TRIAL_COUNT_KEYS = ['trialCount', 'varianceSharpe'];
+/** Law 2 report grammar (D5): every research answer carries its conventions and a warnings channel. */
+function researchReport(assumptions, warnings = []) {
+    return {
+        assumptions: { conventionsVersion: CONVENTIONS_VERSION, ...assumptions },
+        diagnostics: { warnings },
+    };
+}
+/**
+ * Deflated Sharpe Ratio (Bailey & López de Prado 2014): the PSR evaluated against the *expected
+ * maximum* Sharpe that `N` independent trials would produce by chance, so selecting the best of a
+ * parameter sweep is penalised. Pass the trial Sharpes (variance computed for you) or `trialCount` plus
+ * their variance directly.
+ */
+export function deflatedSharpeRatio(statistics, trials) {
+    requireArgumentObject('deflatedSharpeRatio', 'trials', trials);
+    requireArgumentObject('deflatedSharpeRatio', 'statistics', statistics);
+    // The trials union is discriminated by `trialSharpes`; guard against the resolved branch so a
+    // stray `trialCount` beside `trialSharpes` (which would be silently ignored) throws too.
+    ensureKnownKeys('deflatedSharpeRatio', 'trials', trials, 'trialSharpes' in trials ? TRIAL_SHARPES_KEYS : TRIAL_COUNT_KEYS);
+    const functionName = 'deflatedSharpeRatio';
+    let trialCount;
+    let varSharpe;
+    if ('trialSharpes' in trials) {
+        if (trials.trialSharpes === null || typeof trials.trialSharpes?.length !== 'number') {
+            throw new InputError(`deflatedSharpeRatio: trials.trialSharpes must be an array of Sharpe ratios. Received ${trials.trialSharpes === null ? 'null' : typeof trials.trialSharpes}.`, { code: ErrorCode.InputWrongType, context: { field: 'trials.trialSharpes' } });
+        }
+        const m = trials.trialSharpes.length;
+        if (m < 2) {
+            throw new InputError(`${functionName}: need ≥ 2 trial Sharpes to estimate their variance, got ${m}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { trials: m },
+            });
+        }
+        trialCount = m;
+        varSharpe = variance(trials.trialSharpes);
+    }
+    else {
+        trialCount = trials.trialCount;
+        varSharpe = trials.varianceSharpe;
+        // Safe integer (2026-08-23 review, P0): trialCount only feeds the closed-form Gumbel
+        // approximation (no loop, no allocation), but above 2^53 the count itself is no longer exact —
+        // an inexact "how many trials did you run" is a corrupted input, not a big one.
+        if (!Number.isSafeInteger(trialCount) || trialCount < 2) {
+            throw new InputError(`${functionName}: trialCount must be an integer ≥ 2, got ${trialCount}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { trialCount },
+            });
+        }
+        ensureFinite(varSharpe, 'varianceSharpe', functionName);
+        // A variance can't be negative; reject it rather than silently clamping to 0 (which would make
+        // the deflated Sharpe collapse to the un-deflated PSR and quietly defeat the diagnostic).
+        if (varSharpe < 0) {
+            throw new InputError(`${functionName}: varianceSharpe must be ≥ 0, got ${varSharpe}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { varianceSharpe: varSharpe },
+            });
+        }
+    }
+    // Expected maximum of N i.i.d. Gaussians (Gumbel approximation), scaled by the trial-Sharpe stddev:
+    //   SR₀ = √V · [ (1−γ)·Z⁻¹(1 − 1/N) + γ·Z⁻¹(1 − 1/(N·e)) ]
+    const sd = Math.sqrt(varSharpe);
+    const sr0 = sd *
+        ((1 - EULER_MASCHERONI) * normalInverseCdf(1 - 1 / trialCount) +
+            EULER_MASCHERONI * normalInverseCdf(1 - 1 / (trialCount * Math.E)));
+    return {
+        deflatedSharpe: psrKernel(statistics, sr0, functionName),
+        probabilisticSharpe: psrKernel(statistics, 0, functionName),
+        expectedMaxSharpe: sr0,
+        trialCount,
+        // Which branch of the `trials` union was resolved, and against what sample sizes (dx §2.4):
+        // a serialized result says whether the trial-Sharpe variance was estimated or supplied.
+        ...researchReport({
+            trialsFrom: 'trialSharpes' in trials ? 'trialSharpes' : 'trialCount+varianceSharpe',
+            trialCount,
+            varianceSharpe: varSharpe,
+            observations: statistics.observations,
+        }, statistics.sharpe === null ? [undefinedSharpeWarning(functionName)] : []),
+    };
+}
+/** Sample variance helper (n−1) used for trial-Sharpe dispersion. */
+function variance(xs) {
+    const n = xs.length;
+    const mu = mean(xs);
+    let acc = 0;
+    for (let i = 0; i < n; i++)
+        acc += (xs[i] - mu) ** 2;
+    return acc / (n - 1);
+}
+const MULTIPLE_TEST_METHODS = [
+    'bonferroni',
+    'sidak',
+    'holm',
+    'benjaminiHochberg',
+];
+const MULTIPLE_TEST_OPTIONS_KEYS = ['method', 'alpha'];
+/**
+ * Adjust a set of p-values for multiple testing. Bonferroni/Šidák/Holm control the family-wise error
+ * rate; Benjamini–Hochberg controls the false-discovery rate. Returns adjusted p-values (input order)
+ * and the rejection decisions at `alpha`.
+ */
+export function adjustPValues(pValues, options = {}) {
+    requireArgumentArray('adjustPValues', 'pValues', pValues);
+    const functionName = 'adjustPValues';
+    requireArgumentObject(functionName, 'options', options);
+    ensureKnownKeys(functionName, 'options', options, MULTIPLE_TEST_OPTIONS_KEYS);
+    const m = pValues.length;
+    if (m === 0) {
+        throw new InputError(`${functionName}: p-values must be non-empty.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { count: 0 },
+        });
+    }
+    const p = new Array(m);
+    for (let i = 0; i < m; i++) {
+        const v = pValues[i];
+        if (!(v >= 0 && v <= 1)) {
+            throw new InputError(`${functionName}: p-value[${i}] must be in [0, 1], got ${v}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { index: i, value: v },
+            });
+        }
+        p[i] = v;
+    }
+    ensureEnumWhenPresent(options.method, 'adjustPValues', 'method', [
+        'bonferroni',
+        'sidak',
+        'holm',
+        'benjaminiHochberg',
+    ]);
+    ensureFiniteWhenPresent(options.alpha, 'alpha', functionName);
+    const method = options.method ?? 'holm';
+    if (!MULTIPLE_TEST_METHODS.includes(method)) {
+        throw new InputError(`${functionName}: method must be one of ${MULTIPLE_TEST_METHODS.join(', ')}; got "${method}".`, { code: ErrorCode.InputInvalidEnum, context: { method } });
+    }
+    const alpha = options.alpha ?? 0.05;
+    if (!(alpha > 0 && alpha < 1)) {
+        throw new InputError(`${functionName}: alpha must be in (0, 1), got ${alpha}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { alpha },
+        });
+    }
+    const adjusted = new Array(m);
+    if (method === 'bonferroni') {
+        for (let i = 0; i < m; i++)
+            adjusted[i] = Math.min(1, p[i] * m);
+    }
+    else if (method === 'sidak') {
+        for (let i = 0; i < m; i++)
+            adjusted[i] = 1 - (1 - p[i]) ** m;
+    }
+    else {
+        // Holm (step-down) and Benjamini–Hochberg (step-up) both work on the sorted p-values.
+        const order = Array.from({ length: m }, (_, i) => i).sort((a, b) => p[a] - p[b]);
+        const sorted = order.map((i) => p[i]);
+        const adjSorted = new Array(m);
+        if (method === 'holm') {
+            let running = 0;
+            for (let k = 0; k < m; k++) {
+                running = Math.max(running, Math.min(1, (m - k) * sorted[k]));
+                adjSorted[k] = running;
+            }
+        }
+        else {
+            // benjaminiHochberg
+            let running = 1;
+            for (let k = m - 1; k >= 0; k--) {
+                running = Math.min(running, Math.min(1, (m / (k + 1)) * sorted[k]));
+                adjSorted[k] = running;
+            }
+        }
+        for (let k = 0; k < m; k++)
+            adjusted[order[k]] = adjSorted[k];
+    }
+    return { method, alpha, adjusted, rejected: adjusted.map((a) => a <= alpha) };
+}
+/**
+ * Hard cap on the TOTAL index entries a splitter may materialize (2026-08-23 review, P0). The
+ * splitters take `observationCount` as a NUMBER, not data, so a call like
+ * `purgedKFold(1e12, { folds: 1e6 })` was an absurd allocation the old integer checks happily
+ * accepted (`Number.isInteger(1e12)` is `true`). Every emitted index is one array slot (~8 bytes)
+ * and one loop iteration (a few ns), so 5·10^7 entries is ~400 MB at the very worst and well under
+ * a second to generate — already past any realistic design (50 folds over a decade of minute bars
+ * ≈ 5·10^7). Beyond it the caller is asking for an allocation, not a split plan.
+ */
+const MAX_SPLIT_INDEX_ENTRIES = 50_000_000;
+/** The documented {@link WalkForwardOptions} keys. */
+const WALK_FORWARD_OPTIONS_KEYS = ['trainSize', 'testSize', 'step', 'mode'];
+/** Generate walk-forward (rolling or anchored) train/test splits over `n` ordered observations. */
+export function walkForwardSplits(observationCount, options) {
+    ensureFinite(observationCount, 'observationCount', 'walkForwardSplits');
+    requireArgumentObject('walkForwardSplits', 'options', options);
+    ensureKnownKeys('walkForwardSplits', 'options', options, WALK_FORWARD_OPTIONS_KEYS);
+    const functionName = 'walkForwardSplits';
+    requirePositiveInt(observationCount, 'observationCount', functionName);
+    const { trainSize, testSize } = options;
+    requirePositiveInt(trainSize, 'trainSize', functionName);
+    requirePositiveInt(testSize, 'testSize', functionName);
+    ensureFiniteWhenPresent(options.step, 'step', 'walkForwardSplits');
+    const step = options.step ?? testSize;
+    requirePositiveInt(step, 'step', functionName);
+    ensureEnumWhenPresent(options.mode, 'walkForwardSplits', 'mode', ['rolling', 'anchored']);
+    const mode = options.mode ?? 'rolling';
+    if (mode !== 'rolling' && mode !== 'anchored') {
+        // Reject an unknown mode rather than silently behaving as rolling.
+        throw new InputError(`${functionName}: mode must be 'rolling' or 'anchored', got "${mode}".`, {
+            code: ErrorCode.InputInvalidEnum,
+            context: { mode },
+        });
+    }
+    // Bound the PRODUCT before the loop (2026-08-23 review, P0): observationCount, trainSize,
+    // testSize, and step are each safe positive integers by now, but the WORK is their combination —
+    // `walkForwardSplits(1e12, { trainSize: 1, testSize: 2, step: 1 })` would materialize ~3·10^12
+    // index entries. Count the splits and the entries they emit arithmetically (exact closed forms,
+    // no loop) and refuse an absurd total with the bound and its price.
+    const splitCount = trainSize + testSize > observationCount
+        ? 0
+        : Math.floor((observationCount - trainSize - testSize) / step) + 1;
+    const totalIndexEntries = mode === 'anchored'
+        ? // k-th anchored split trains on [0, trainSize + k·step): Σ = c·(train+test) + step·c(c−1)/2.
+            splitCount * (trainSize + testSize) + (step * splitCount * (splitCount - 1)) / 2
+        : splitCount * (trainSize + testSize);
+    if (totalIndexEntries > MAX_SPLIT_INDEX_ENTRIES) {
+        throw new InputError(`${functionName}: this request would materialize ${totalIndexEntries.toLocaleString('en-US')} split index entries (${splitCount.toLocaleString('en-US')} ${mode} splits over ${observationCount.toLocaleString('en-US')} observations), above the ${MAX_SPLIT_INDEX_ENTRIES.toLocaleString('en-US')} cap — each entry is an array slot and a loop iteration, so the cap keeps the largest request under a second and a few hundred MB. Use a larger step, smaller windows, or fewer observations.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: {
+                observationCount,
+                trainSize,
+                testSize,
+                step,
+                mode,
+                splitCount,
+                totalIndexEntries,
+                max: MAX_SPLIT_INDEX_ENTRIES,
+            },
+        });
+    }
+    const splits = [];
+    for (let trainEnd = trainSize; trainEnd + testSize <= observationCount; trainEnd += step) {
+        const trainStart = mode === 'anchored' ? 0 : trainEnd - trainSize;
+        splits.push({
+            train: range(trainStart, trainEnd),
+            test: range(trainEnd, trainEnd + testSize),
+        });
+    }
+    return splits;
+}
+/** The documented {@link PurgedKFoldOptions} keys. */
+const PURGED_K_FOLD_OPTIONS_KEYS = ['folds', 'embargo', 'purgeGap'];
+/**
+ * Purged & embargoed K-fold cross-validation (López de Prado, *Advances in Financial ML* ch. 7).
+ * Each fold's test set is a contiguous block; training drops any observation within `purgeGap` of the
+ * test block (label-overlap purge) and within the trailing `embargo·n` window after it.
+ *
+ * Throws a typed `input.out_of_range` naming the largest viable `purgeGap` when the requested purge
+ * (with the embargo) would leave a fold with an empty training set — an unusable split is an error,
+ * not an empty array to be discovered downstream.
+ */
+export function purgedKFold(observationCount, options) {
+    ensureFinite(observationCount, 'observationCount', 'purgedKFold');
+    requireArgumentObject('purgedKFold', 'options', options);
+    ensureKnownKeys('purgedKFold', 'options', options, PURGED_K_FOLD_OPTIONS_KEYS);
+    const functionName = 'purgedKFold';
+    requirePositiveInt(observationCount, 'observationCount', functionName);
+    const { folds } = options;
+    // Safe integer (2026-08-23 review, P0); the ≤ observationCount bound below keeps folds
+    // data-scaled, and the PRODUCT check after it bounds the actual work.
+    if (!Number.isSafeInteger(folds) || folds < 2 || folds > observationCount) {
+        throw new InputError(`${functionName}: folds must be an integer in [2, observationCount=${observationCount}], got ${folds}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { folds, observationCount },
+        });
+    }
+    // Bound the PRODUCT (2026-08-23 review, P0): the generator visits every observation once PER
+    // FOLD (folds × observationCount iterations) and materializes nearly that many train indices, so
+    // two individually-plausible counts can multiply into an absurd allocation —
+    // `purgedKFold(10_000_000, { folds: 5_000 })` is 5·10^10 entries. See MAX_SPLIT_INDEX_ENTRIES
+    // for the cap's price.
+    if (folds * observationCount > MAX_SPLIT_INDEX_ENTRIES) {
+        throw new InputError(`${functionName}: folds × observationCount = ${(folds * observationCount).toLocaleString('en-US')} exceeds the ${MAX_SPLIT_INDEX_ENTRIES.toLocaleString('en-US')} cap on materialized split index entries — every fold's training array revisits (almost) the whole sample, so the work and memory scale with the product, and the cap keeps the largest request under a second and a few hundred MB. Use fewer folds or fewer observations.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { folds, observationCount, max: MAX_SPLIT_INDEX_ENTRIES },
+        });
+    }
+    ensureFiniteWhenPresent(options.embargo, 'embargo', 'purgedKFold');
+    const embargo = options.embargo ?? 0;
+    if (!(embargo >= 0 && embargo < 1)) {
+        throw new InputError(`${functionName}: embargo must be in [0, 1), got ${embargo}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { embargo },
+        });
+    }
+    ensureFiniteWhenPresent(options.purgeGap, 'purgeGap', 'purgedKFold');
+    const purgeGap = options.purgeGap ?? 0;
+    // Safe integer (2026-08-23 review, P0); the maxViablePurgeGap check below additionally bounds it
+    // by the sample, so it can never widen any loop.
+    if (!Number.isSafeInteger(purgeGap) || purgeGap < 0) {
+        throw new InputError(`${functionName}: purgeGap must be a non-negative integer, got ${purgeGap}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { purgeGap },
+        });
+    }
+    const embargoSize = Math.floor(embargo * observationCount);
+    const foldSize = Math.floor(observationCount / folds);
+    // A purge window wide enough to swallow a fold's whole complement leaves that fold with an EMPTY
+    // training set — and an empty train set is not a cross-validation split, it is a silently
+    // unusable one (every downstream fit sees zero rows and either throws far from here or "learns"
+    // nothing). Compute the largest purgeGap that still leaves at least one training observation in
+    // every fold, and teach it.
+    const maxViablePurgeGap = () => {
+        let bound = Infinity;
+        for (let k = 0; k < folds; k++) {
+            const testStart = k * foldSize;
+            const testEnd = k === folds - 1 ? observationCount : testStart + foldSize;
+            // Left side survives while `purgeGap ≤ testStart − 1`; the right side additionally has to
+            // clear the embargo, which no purgeGap can shrink.
+            const left = testStart - 1;
+            const right = embargoSize <= observationCount - 1 - testEnd ? observationCount - 1 - testEnd : -1;
+            bound = Math.min(bound, Math.max(left, right));
+        }
+        return bound;
+    };
+    const maxGap = maxViablePurgeGap();
+    if (purgeGap > maxGap) {
+        throw new InputError(maxGap < 0
+            ? `${functionName}: embargo=${embargo} already purges every training observation of at least one fold (embargoSize=${embargoSize} over ${observationCount} observations in ${folds} folds) — no purgeGap can produce a usable split. Lower the embargo or the fold count.`
+            : `${functionName}: purgeGap=${purgeGap} leaves at least one fold with an EMPTY training set (fold span ${foldSize} of ${observationCount} observations, embargoSize=${embargoSize}). The largest viable purgeGap for folds=${folds}, embargo=${embargo} is ${maxGap}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: {
+                purgeGap,
+                maxViablePurgeGap: maxGap,
+                folds,
+                foldSize,
+                embargoSize,
+                observationCount,
+            },
+        });
+    }
+    const splits = [];
+    for (let k = 0; k < folds; k++) {
+        const testStart = k * foldSize;
+        const testEnd = k === folds - 1 ? observationCount : testStart + foldSize; // last fold absorbs the remainder
+        const test = range(testStart, testEnd);
+        const purgeLo = testStart - purgeGap;
+        const purgeHi = testEnd + purgeGap;
+        const embargoHi = testEnd + embargoSize;
+        const train = [];
+        for (let i = 0; i < observationCount; i++) {
+            if (i >= testStart && i < testEnd)
+                continue; // the test block itself
+            if (i >= purgeLo && i < purgeHi)
+                continue; // purge around the boundaries
+            if (i >= testEnd && i < embargoHi)
+                continue; // embargo after the test block
+            train.push(i);
+        }
+        splits.push({ train, test });
+    }
+    return splits;
+}
+/**
+ * Summarize a parameter sweep: given the per-trial Sharpes and the sample statistics of the *selected*
+ * (best) configuration's return series, report the dispersion of the trials and the deflated Sharpe —
+ * the honest probability the winner is real rather than the luckiest of many.
+ */
+export function parameterSweepDiagnostics(trialSharpes, selected) {
+    requireArgumentArray('parameterSweepDiagnostics', 'trialSharpes', trialSharpes);
+    requireArgumentObject('parameterSweepDiagnostics', 'selected', selected);
+    const functionName = 'parameterSweepDiagnostics';
+    const m = trialSharpes.length;
+    if (m < 2) {
+        throw new InputError(`${functionName}: need ≥ 2 trial Sharpes, got ${m}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { trials: m },
+        });
+    }
+    let best = -Infinity;
+    for (let i = 0; i < m; i++) {
+        ensureFinite(trialSharpes[i], `trialSharpes[${i}]`, functionName);
+        if (trialSharpes[i] > best)
+            best = trialSharpes[i];
+    }
+    const dsr = deflatedSharpeRatio(selected, { trialSharpes });
+    return {
+        trialCount: m,
+        bestSharpe: best,
+        meanSharpe: mean(trialSharpes),
+        varianceSharpe: variance(trialSharpes),
+        expectedMaxSharpe: dsr.expectedMaxSharpe,
+        deflatedSharpe: dsr.deflatedSharpe,
+        probabilisticSharpe: dsr.probabilisticSharpe,
+    };
+}
+/**
+ * Flag any split whose train and test index sets overlap (look-ahead leakage). The findings are
+ * `research.train_test_leakage` warnings on `diagnostics.warnings` (one per leaking split), with the
+ * structured per-split detail mirrored on `leaks` and a `clean` verdict.
+ */
+export function checkLeakage(splits) {
+    requireArgumentArray('checkLeakage', 'splits', splits);
+    if (splits.length > 0) {
+        const first = splits[0];
+        if (first === null ||
+            typeof first !== 'object' ||
+            !Array.isArray(first.train) ||
+            !Array.isArray(first.test)) {
+            throw new InputError('checkLeakage: each split is { train: number[], test: number[] } (see walkForwardSplits/purgedKFold).', { code: ErrorCode.InputWrongType, context: {} });
+        }
+    }
+    const warnings = [];
+    const leaks = [];
+    splits.forEach((s, i) => {
+        const testSet = new Set(s.test);
+        const overlap = s.train.filter((x) => testSet.has(x));
+        if (overlap.length > 0) {
+            const issue = {
+                split: i,
+                overlapCount: overlap.length,
+                sample: overlap.slice(0, 10),
+            };
+            leaks.push(issue);
+            warnings.push({
+                code: WarningCode.ResearchTrainTestLeakage,
+                message: `Split ${i}: ${overlap.length} index(es) appear in both train and test — look-ahead leakage.`,
+                severity: 'error',
+                context: { ...issue },
+            });
+        }
+    });
+    return {
+        clean: leaks.length === 0,
+        leaks,
+        ...researchReport({ splits: splits.length }, warnings),
+    };
+}
+/**
+ * Return a survivorship-bias warning when the backtest universe excludes delisted names or is not
+ * point-in-time — both bias results upward — or `null` when neither concern applies.
+ */
+export function survivorshipWarning(context) {
+    requireArgumentObject('survivorshipWarning', 'context', context);
+    // Law 12 + boolean ladders: `{ includesDelisted: 'no' }` is truthy, so it silently REMOVED the
+    // survivorship warning the flag exists to raise.
+    ensureKnownKeys('survivorshipWarning', 'context', context, [
+        'includesDelisted',
+        'pointInTimeUniverse',
+        'universeSource',
+    ]);
+    ensureBooleanWhenPresent(context.includesDelisted, 'survivorshipWarning', 'includesDelisted');
+    ensureBooleanWhenPresent(context.pointInTimeUniverse, 'survivorshipWarning', 'pointInTimeUniverse');
+    const issues = [];
+    if (context.includesDelisted === false)
+        issues.push('excludes delisted/inactive instruments');
+    if (context.pointInTimeUniverse === false)
+        issues.push('uses a non-point-in-time universe');
+    if (issues.length === 0)
+        return null;
+    return {
+        code: WarningCode.ResearchSurvivorshipBias,
+        message: `Backtest universe ${issues.join(' and ')}; results are likely survivorship-biased (upward).`,
+        severity: 'warn',
+        context: { ...context },
+    };
+}
+/** Sharpe of a union of blocks (mean/σ, population σ — ranking is invariant to the ddof). */
+function unionSharpe(blocks, picks, n) {
+    let s = 0;
+    let ss = 0;
+    let rows = 0;
+    for (const b of picks) {
+        s += blocks[b].sum[n];
+        ss += blocks[b].sumSq[n];
+        rows += blocks[b].rows;
+    }
+    const m = s / rows;
+    const variance = ss / rows - m * m;
+    return variance > 0 ? m / Math.sqrt(variance) : 0;
+}
+/**
+ * **Probability of backtest overfitting** (Bailey & López de Prado's CSCV). Given a `T × N` matrix of
+ * per-period returns — `T` time observations (rows) × `N` strategy configurations you selected among
+ * (columns) — split the rows into `S` blocks, and over **every** `C(S, S/2)` symmetric partition into an
+ * in-sample and an out-of-sample half: pick the IS-best configuration, then measure its OOS rank. PBO is
+ * the fraction of splits where the IS winner lands **below the OOS median** — the probability that
+ * picking the best backtest buys you a below-average live result. `≈ 0.5` means the selection is worthless
+ * out of sample; `≈ 0` means a genuinely persistent edge. Depends only on `@insiderfinance/totalfinance/core`/`math`.
+ */
+export function probabilityOfBacktestOverfitting(returns, options = {}) {
+    const functionName = 'probabilityOfBacktestOverfitting';
+    requireArgumentArray(functionName, 'returns', returns);
+    requireArgumentObject(functionName, 'options', options);
+    ensureKnownKeys(functionName, 'options', options, PBO_OPTIONS_KEYS);
+    ensureFiniteWhenPresent(options.splits, 'splits', 'probabilityOfBacktestOverfitting');
+    const S = options.splits ?? 16;
+    // isSafeInteger for uniformity (2026-08-23 review, P0) — the ≤ 16 bound already rejects any
+    // unsafe magnitude, so C(S, S/2) stays ≤ C(16, 8) = 12,870 partitions.
+    if (!Number.isSafeInteger(S) || S < 4 || S > 16 || S % 2 !== 0) {
+        throw new InputError(`${functionName}: splits must be an even integer in [4, 16], got ${S}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { splits: S },
+        });
+    }
+    const T = returns.length;
+    if (T < S) {
+        throw new InputError(`${functionName}: need at least splits=${S} observations (rows), got ${T}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { observations: T, splits: S },
+        });
+    }
+    const N = Array.isArray(returns[0]) ? returns[0].length : 0;
+    if (N < 2) {
+        throw new InputError(`${functionName}: need at least 2 strategy configurations (columns) to rank; got ${N}.`, { code: ErrorCode.InputOutOfRange, context: { trials: N } });
+    }
+    const block = Math.floor(T / S);
+    const used = block * S;
+    const offset = T - used; // drop the oldest `offset` rows to make T a multiple of S
+    const warnings = [];
+    if (offset > 0) {
+        warnings.push({
+            code: WarningCode.ResearchBacktestOverfittingProbabilityTrimmed,
+            message: `${functionName}: trimmed the oldest ${offset} observation(s) so T=${used} divides into ${S} blocks.`,
+            severity: 'info',
+            context: { dropped: offset, used, splits: S },
+        });
+    }
+    // Per-block sufficient statistics (validating the matrix is rectangular + finite as we go).
+    const blocks = [];
+    for (let s = 0; s < S; s++) {
+        const sum = new Array(N).fill(0);
+        const sumSq = new Array(N).fill(0);
+        for (let r = 0; r < block; r++) {
+            const row = returns[offset + s * block + r];
+            if (!Array.isArray(row) || row.length !== N) {
+                throw new InputError(`${functionName}: returns must be a rectangular T×N matrix (row ${offset + s * block + r} has a different width).`, {
+                    code: ErrorCode.InputWrongShape,
+                    context: { expectedWidth: N, row: offset + s * block + r },
+                });
+            }
+            for (let n = 0; n < N; n++) {
+                const x = row[n];
+                ensureFinite(x, `returns[${offset + s * block + r}][${n}]`, functionName);
+                sum[n] += x;
+                sumSq[n] += x * x;
+            }
+        }
+        blocks.push({ sum, sumSq, rows: block });
+    }
+    const combos = choose(range(0, S), S / 2);
+    const all = new Set(range(0, S));
+    const logits = [];
+    let overfit = 0;
+    for (const isPicks of combos) {
+        const isSet = new Set(isPicks);
+        const oosPicks = [...all].filter((b) => !isSet.has(b));
+        // IS-best configuration.
+        let best = 0;
+        let bestSharpe = -Infinity;
+        for (let n = 0; n < N; n++) {
+            const sh = unionSharpe(blocks, isPicks, n);
+            if (sh > bestSharpe) {
+                bestSharpe = sh;
+                best = n;
+            }
+        }
+        // Its OOS relative rank r̄ = (#configs with OOS Sharpe ≤ the winner's) / (N+1).
+        const winnerOos = unionSharpe(blocks, oosPicks, best);
+        let le = 0;
+        for (let n = 0; n < N; n++)
+            if (unionSharpe(blocks, oosPicks, n) <= winnerOos)
+                le++;
+        const rBar = le / (N + 1); // ∈ (0, 1); logit is always finite
+        const lambda = Math.log(rBar / (1 - rBar));
+        logits.push(lambda);
+        if (lambda < 0)
+            overfit++;
+    }
+    return {
+        backtestOverfittingProbability: overfit / combos.length,
+        combinations: combos.length,
+        splits: S,
+        observations: used,
+        trials: N,
+        medianLogit: median(logits),
+        assumptions: { conventionsVersion: CONVENTIONS_VERSION, method: 'cscv', splits: S },
+        diagnostics: { warnings },
+    };
+}
+/** {@link BacktestOverfittingProbabilityOptions} keys (Law 12). */
+const PBO_OPTIONS_KEYS = ['splits'];
+// ───────────────────────── helpers ─────────────────────────
+/** All `C(items.length, k)` combinations of `k` items, as index arrays (lexicographic). */
+function choose(items, k) {
+    const S = items.length;
+    const out = [];
+    const idx = range(0, k);
+    for (;;) {
+        out.push(idx.map((i) => items[i]));
+        let i = k - 1;
+        while (i >= 0 && idx[i] === S - k + i)
+            i--;
+        if (i < 0)
+            break;
+        idx[i]++;
+        for (let j = i + 1; j < k; j++)
+            idx[j] = idx[j - 1] + 1;
+    }
+    return out;
+}
+/** Median of a numeric array (does not mutate the input). */
+function median(xs) {
+    const sorted = [...xs].sort((a, b) => a - b);
+    const n = sorted.length;
+    if (n === 0)
+        return NaN;
+    const mid = Math.floor(n / 2);
+    return n % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+function range(start, end) {
+    const out = new Array(Math.max(0, end - start));
+    for (let i = start; i < end; i++)
+        out[i - start] = i;
+    return out;
+}
+// Safe integer, not just integer (2026-08-23 review, P0): every caller feeds a splitter whose loop
+// bounds and allocations these values drive — `Number.isInteger(1e308)` is `true`, and above 2^53
+// a loop counter stops advancing. The splitters additionally bound the PRODUCT of their counts
+// (MAX_SPLIT_INDEX_ENTRIES); this gate keeps each count exact on its own.
+function requirePositiveInt(value, field, functionName) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new InputError(`${functionName}: ${field} must be a positive integer, got ${value}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { [field]: value },
+        });
+    }
+}
+//# sourceMappingURL=research.js.map