@insiderfinance/totalfinance 0.1.0

package/modules/risk/dist/kelly.js

@@ -0,0 +1,731 @@
+import { ensureFiniteWhenPresent } from './options-internal.js';
+/**
+ * Kelly bet-sizing pack (spec: `docs/specs/kelly-sizing.md`, roadmap Tier 2 → Sizing). One call that
+ * turns a trade's edge — a binary win/loss bet, a discrete payoff distribution, a Gaussian `μ/σ²`, or a
+ * raw return sample — into a sane position size: the growth-optimal fraction `f*`, then scaled down by
+ * fractional-Kelly (half by default), an explicit drawdown budget, and a hard cap, with the
+ * growth/drawdown tradeoff and the fat-tail correction disclosed.
+ *
+ * This is the single-bankroll bet-sizing question, orthogonal to the portfolio `kelly()` in
+ * `optimize.ts` (which allocates `Σ⁻¹μ` weights across correlated assets). Full Kelly maximizes long-run
+ * log-growth `g(f) = E[ln(1 + f·r)]`; the drawdown model is the running-minimum law of the wealth GBM.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, ensureFinite, ensureKnownKeys, ensurePositive, requireArgumentArray, requireArgumentObject, warning, WarningCode, } from '../../core/dist/index.js';
+import { brentMin, cholesky, choleskySolve, variance } from '../../math/dist/index.js';
+/** The documented {@link KellyBetInput} keys — Law 12: an unknown field must throw, never no-op. */
+const KELLY_BET_INPUT_KEYS = [
+    'edge',
+    'fraction',
+    'drawdownLimit',
+    'maxFraction',
+    'horizonPeriods',
+];
+const f2 = (n) => Number.isFinite(n) ? Number(n.toFixed(2)).toString() : n > 0 ? '∞' : '−∞';
+const f3 = (n) => (Number.isFinite(n) ? Number(n.toFixed(3)).toString() : f2(n));
+const pct = (p) => `${(p * 100).toFixed(p < 0.1 ? 1 : 0)}%`;
+/**
+ * `P(wealth ever falls to a fraction `b` of the starting bankroll)` at an applied Kelly multiple `κ`.
+ * From the running-minimum (first-passage) law of the wealth GBM: `b^(2/κ − 1)`, clamped to `[0, 1]`
+ * (`κ ≥ 2` ⇒ the log-drift is non-positive ⇒ ruin is certain). `κ ≤ 0` (not betting) ⇒ no drawdown.
+ * NOTE: this is relative to STARTING capital (the Thorp/MacLean–Ziemba result), not the running peak.
+ */
+function drawdownProbability(b, kappa) {
+    if (!(kappa > 0))
+        return 0;
+    const exponent = 2 / kappa - 1;
+    if (exponent <= 0)
+        return 1; // κ ≥ 2 — non-positive growth drift, certain drawdown.
+    const p = b ** exponent;
+    return p < 0 ? 0 : p > 1 ? 1 : p;
+}
+/**
+ * The largest applied Kelly multiple `κ` keeping `P(drawdown to b) ≤ p`: `κ_max = 2/(1 + ln p/ln b)`.
+ * `Infinity` when the limit is non-binding (`1 + ln p/ln b ≤ 0`).
+ */
+function drawdownConstrainedKappa(b, p) {
+    const denom = 1 + Math.log(p) / Math.log(b);
+    return denom > 0 ? 2 / denom : Infinity;
+}
+/**
+ * Numerically maximize a strictly concave log-growth `g` on `(0, fMax)` (Brent on `−g`). Returns 0 when
+ * `g'(0) = μ ≤ 0` (no edge). `fMax = 1/L` is the leverage at which the worst loss wipes out the stake.
+ */
+function maximizeGrowth(g, mu, fMax) {
+    if (!(mu > 0))
+        return 0;
+    const hi = fMax * (1 - 1e-9);
+    const lo = fMax * 1e-9;
+    const res = brentMin((f) => -g(f), lo, hi, { tolerance: 1e-12, maximumIterations: 300 });
+    return res.argMin > 0 ? res.argMin : 0;
+}
+/** Resolve the four edge specifications to a common `ResolvedEdge`. */
+function resolveEdge(edge, functionName) {
+    requireArgumentObject(functionName, 'edge', edge);
+    if ('binary' in edge) {
+        const b = edge.binary;
+        requireArgumentObject(functionName, 'edge.binary', b);
+        const p = b.winProbability;
+        const win = b.winAmount;
+        ensureFiniteWhenPresent(b.lossAmount, 'edge.binary.lossAmount', 'kelly');
+        const loss = b.lossAmount ?? 1;
+        ensureFinite(p, 'edge.binary.winProbability', functionName);
+        ensureFinite(win, 'edge.binary.winAmount', functionName);
+        ensureFinite(loss, 'edge.binary.lossAmount', functionName);
+        if (!(p > 0 && p < 1)) {
+            throw new InputError(`${functionName}: winProbability must be in (0, 1); got ${p}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { winProbability: p },
+            });
+        }
+        if (!(win > 0) || !(loss > 0)) {
+            throw new InputError(`${functionName}: winAmount and lossAmount must be positive; got ${win}, ${loss}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { winAmount: win, lossAmount: loss },
+            });
+        }
+        const q = 1 - p;
+        const fullKelly = p / loss - q / win; // f* = (p·b − q·a)/(a·b)
+        return {
+            edgeType: 'binary',
+            fullKelly,
+            growth: (f) => p * Math.log(1 + f * win) + q * Math.log(1 - f * loss),
+            warnings: [],
+        };
+    }
+    if ('outcomes' in edge) {
+        requireArgumentArray(functionName, 'edge.outcomes', edge.outcomes);
+        const os = edge.outcomes;
+        if (os.length < 2) {
+            throw new InputError(`${functionName}: edge.outcomes needs ≥ 2 outcomes; got ${os.length}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { outcomes: os.length },
+            });
+        }
+        let probSum = 0;
+        let mu = 0;
+        let worstLoss = 0;
+        for (let i = 0; i < os.length; i++) {
+            const o = os[i];
+            requireArgumentObject(functionName, `edge.outcomes[${i}]`, o);
+            ensureFinite(o.probability, `edge.outcomes[${i}].probability`, functionName);
+            ensureFinite(o.payoff, `edge.outcomes[${i}].payoff`, functionName);
+            if (!(o.probability >= 0)) {
+                throw new InputError(`${functionName}: outcome probabilities must be ≥ 0; got ${o.probability}.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { index: i, probability: o.probability },
+                });
+            }
+            probSum += o.probability;
+            mu += o.probability * o.payoff;
+            if (-o.payoff > worstLoss)
+                worstLoss = -o.payoff;
+        }
+        if (Math.abs(probSum - 1) > 1e-6) {
+            throw new InputError(`${functionName}: outcome probabilities must sum to 1; got ${probSum}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { probabilitySum: probSum },
+            });
+        }
+        const growth = (f) => {
+            let g = 0;
+            for (let i = 0; i < os.length; i++) {
+                const o = os[i];
+                if (o.probability > 0)
+                    g += o.probability * Math.log(1 + f * o.payoff);
+            }
+            return g;
+        };
+        if (worstLoss <= 0) {
+            // No losing outcome — g increases without bound; f* is unbounded.
+            return {
+                edgeType: 'outcomes',
+                fullKelly: Infinity,
+                growth,
+                warnings: [noDownsideWarning(functionName)],
+            };
+        }
+        return {
+            edgeType: 'outcomes',
+            fullKelly: maximizeGrowth(growth, mu, 1 / worstLoss),
+            growth,
+            warnings: [],
+        };
+    }
+    if ('gaussian' in edge) {
+        const g = edge.gaussian;
+        requireArgumentObject(functionName, 'edge.gaussian', g);
+        ensureFinite(g.mean, 'edge.gaussian.mean', functionName);
+        ensureFinite(g.variance, 'edge.gaussian.variance', functionName);
+        if (!(g.variance > 0)) {
+            throw new InputError(`${functionName}: edge.gaussian.variance must be positive; got ${g.variance}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { variance: g.variance },
+            });
+        }
+        const mu = g.mean;
+        const v = g.variance;
+        return {
+            edgeType: 'gaussian',
+            fullKelly: mu / v,
+            // Continuous log-growth of a GBM with arithmetic drift μ and variance σ²: g(f) = f·μ − ½f²σ².
+            growth: (f) => f * mu - 0.5 * f * f * v,
+            warnings: [],
+        };
+    }
+    if ('returns' in edge) {
+        requireArgumentArray(functionName, 'edge.returns', edge.returns);
+        const r = edge.returns;
+        const n = r.length;
+        if (n < 2) {
+            throw new InputError(`${functionName}: edge.returns needs ≥ 2 observations; got ${n}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { observations: n },
+            });
+        }
+        let mu = 0;
+        let worstLoss = 0;
+        for (let i = 0; i < n; i++) {
+            const x = r[i];
+            ensureFinite(x, `edge.returns[${i}]`, functionName);
+            mu += x;
+            if (-x > worstLoss)
+                worstLoss = -x;
+        }
+        mu /= n;
+        const v = variance(r, { population: true });
+        // C (hygiene): a zero-variance sample is a degenerate edge, not a malformed one. Every return
+        // is the same number: a positive one is an edge with no downside (unbounded, capped below), a
+        // non-positive one is no edge at all. The Gaussian approximation μ/σ² has no value either way,
+        // so it is omitted and the diagnostic says why.
+        const degenerate = !(v > 0);
+        const gaussianKelly = degenerate ? undefined : mu / v;
+        const zeroVariance = degenerate ? [zeroVarianceWarning(functionName, r[0])] : [];
+        const growth = (f) => {
+            let g = 0;
+            for (let i = 0; i < n; i++)
+                g += Math.log(1 + f * r[i]);
+            return g / n;
+        };
+        if (worstLoss <= 0) {
+            return {
+                edgeType: 'returns',
+                fullKelly: Infinity,
+                growth,
+                ...(gaussianKelly === undefined ? {} : { gaussianKelly }),
+                warnings: [...zeroVariance, noDownsideWarning(functionName)],
+            };
+        }
+        return {
+            edgeType: 'returns',
+            fullKelly: maximizeGrowth(growth, mu, 1 / worstLoss),
+            growth,
+            ...(gaussianKelly === undefined ? {} : { gaussianKelly }),
+            warnings: zeroVariance,
+        };
+    }
+    throw new InputError(`${functionName}: edge must specify exactly one of binary / outcomes / gaussian / returns.`, { code: ErrorCode.InputMissingField, context: { keys: Object.keys(edge) } });
+}
+function zeroVarianceWarning(functionName, value) {
+    return warning(WarningCode.RiskKellyZeroVariance, `${functionName}: edge.returns have zero variance (every return is ${value}); the Gaussian Kelly approximation μ/σ² is undefined and omitted — the sizing below rests on the empirical growth curve alone.`, 'warn', { value });
+}
+function noDownsideWarning(functionName) {
+    return warning(WarningCode.RiskKellyUnbounded, `${functionName}: the edge has no losing outcome, so log-growth increases without bound and full Kelly is infinite. Cap the size with maxFraction; the recommendation defaults to that cap.`, 'warn');
+}
+/**
+ * Size a single bet by the Kelly criterion — compute the growth-optimal fraction from the edge, then
+ * scale it down sanely (half-Kelly by default, a drawdown budget, a hard cap) with the growth, the
+ * drawdown risk, and the fat-tail correction all disclosed. See `docs/specs/kelly-sizing.md`.
+ */
+export function kellyBet(input) {
+    const functionName = 'kellyBet';
+    requireArgumentObject(functionName, 'input', input);
+    // Law 12: a misspelled knob (`maxFracton: 1` leaving the size uncapped) must throw, never no-op.
+    ensureKnownKeys(functionName, 'input', input, KELLY_BET_INPUT_KEYS);
+    ensureFiniteWhenPresent(input.fraction, 'fraction', 'kellyBet');
+    const fraction = input.fraction ?? 0.5;
+    if (!(fraction > 0)) {
+        throw new InputError(`${functionName}: fraction must be positive (0.5 = half-Kelly); got ${fraction}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { fraction },
+        });
+    }
+    ensureFinite(fraction, 'fraction', functionName);
+    if (input.maxFraction !== undefined && !(input.maxFraction > 0)) {
+        throw new InputError(`${functionName}: maxFraction must be positive; got ${input.maxFraction}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { maxFraction: input.maxFraction },
+        });
+    }
+    if (input.horizonPeriods !== undefined && !(input.horizonPeriods > 0)) {
+        throw new InputError(`${functionName}: horizonPeriods must be positive; got ${input.horizonPeriods}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { horizonPeriods: input.horizonPeriods },
+        });
+    }
+    let ddToFraction = 0.5;
+    let ddMaxProb;
+    if (input.drawdownLimit !== undefined) {
+        const dl = input.drawdownLimit;
+        requireArgumentObject(functionName, 'drawdownLimit', dl);
+        if (!(dl.toFraction > 0 && dl.toFraction < 1)) {
+            throw new InputError(`${functionName}: drawdownLimit.toFraction must be in (0, 1); got ${dl.toFraction}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { toFraction: dl.toFraction },
+            });
+        }
+        if (!(dl.maxProbability > 0 && dl.maxProbability < 1)) {
+            throw new InputError(`${functionName}: drawdownLimit.maxProbability must be in (0, 1); got ${dl.maxProbability}.`, { code: ErrorCode.InputOutOfRange, context: { maxProbability: dl.maxProbability } });
+        }
+        ddToFraction = dl.toFraction;
+        ddMaxProb = dl.maxProbability;
+    }
+    const resolved = resolveEdge(input.edge, functionName);
+    const { fullKelly, growth, edgeType } = resolved;
+    const warnings = [...resolved.warnings];
+    // ── No edge: f* ≤ 0 ⇒ do not bet (never a hedged small number, never a short) ──
+    if (fullKelly <= 0) {
+        warnings.push(warning(WarningCode.RiskKellyNoEdge, `${functionName}: the edge is non-positive (full Kelly ${f3(fullKelly)} ≤ 0), so the growth-optimal action is to not bet.`, 'warn'));
+        const rationale = `No edge: the growth-optimal Kelly fraction is ${f3(fullKelly)} ≤ 0, so this bet loses money on average — do not bet. Sizing anything above zero has negative expected log-growth.`;
+        return assemble({
+            fullKelly,
+            recommendedFraction: 0,
+            appliedFraction: 0,
+            growthRate: 0,
+            growthRateFull: 0,
+            periodsToDouble: Infinity,
+            drawdownRisk: { toFraction: ddToFraction, probability: 0 },
+            bindingConstraint: 'no-edge',
+            gaussianKelly: resolved.gaussianKelly,
+            horizonGrowth: undefined,
+            rationale,
+            fraction,
+            edgeType,
+            warnings,
+        });
+    }
+    // ── No downside: g increases without bound ⇒ no finite full-Kelly optimum (finite-success law) ──
+    // `resolveEdge` already attached the `risk.kelly_unbounded` diagnostic. Represent the state with a
+    // null unconstrained fraction + discriminant rather than Infinity; a finite recommendation exists
+    // only if the caller supplied an explicit, finite cap. A no-downside edge never draws down.
+    if (!Number.isFinite(fullKelly)) {
+        const cap = input.maxFraction;
+        const capped = cap !== undefined && Number.isFinite(cap);
+        const rec = capped ? cap : null;
+        const gRate = rec !== null ? growth(rec) : null;
+        const rationale = capped
+            ? `No downside: full Kelly is unbounded, so the recommendation is the hard maxFraction cap of ${pct(cap)} of bankroll (expected log-growth ${f3(gRate)} per period).`
+            : `No downside: log-growth increases without bound, so there is no finite Kelly optimum. Supply an explicit maxFraction to get a finite, capped recommendation.`;
+        return assemble({
+            fullKelly: null,
+            recommendedFraction: rec,
+            appliedFraction: null,
+            growthRate: gRate,
+            growthRateFull: null,
+            periodsToDouble: gRate !== null ? (gRate > 0 ? Math.LN2 / gRate : Infinity) : null,
+            drawdownRisk: { toFraction: ddToFraction, probability: 0 },
+            bindingConstraint: capped ? 'max-fraction' : 'no-downside',
+            gaussianKelly: resolved.gaussianKelly,
+            horizonGrowth: capped && input.horizonPeriods !== undefined && gRate !== null
+                ? {
+                    horizonPeriods: input.horizonPeriods,
+                    logGrowth: input.horizonPeriods * gRate,
+                    growthMultiple: Math.exp(input.horizonPeriods * gRate),
+                }
+                : undefined,
+            rationale,
+            fraction,
+            edgeType,
+            warnings,
+        });
+    }
+    // ── Caps (in fraction-of-bankroll terms) — fullKelly is finite and > 0 past this point ──
+    const finite = Number.isFinite(fullKelly);
+    const capFractional = finite ? fraction * fullKelly : Infinity; // undefined for f*=∞ → non-binding
+    const kappaMax = ddMaxProb !== undefined ? drawdownConstrainedKappa(ddToFraction, ddMaxProb) : Infinity;
+    const capDrawdown = finite && Number.isFinite(kappaMax) ? kappaMax * fullKelly : Infinity;
+    const capMax = input.maxFraction ?? Infinity;
+    const caps = [
+        { label: 'fraction', value: capFractional },
+        { label: 'drawdown-limit', value: capDrawdown },
+        { label: 'max-fraction', value: capMax },
+    ];
+    let recommendedFraction = Infinity;
+    let bindingConstraint = 'fraction';
+    for (const c of caps) {
+        if (c.value < recommendedFraction) {
+            recommendedFraction = c.value;
+            bindingConstraint = c.label;
+        }
+    }
+    if (!Number.isFinite(recommendedFraction)) {
+        // No-downside edge with no maxFraction/finite cap — honest ∞ rather than a fabricated number.
+        recommendedFraction = Infinity;
+    }
+    if (recommendedFraction < 0)
+        recommendedFraction = 0;
+    const appliedFraction = finite ? recommendedFraction / fullKelly : Infinity; // κ
+    const growthRate = Number.isFinite(recommendedFraction) ? growth(recommendedFraction) : Infinity;
+    const growthRateFull = finite ? growth(fullKelly) : Infinity;
+    const periodsToDouble = growthRate > 0 ? Math.LN2 / growthRate : Infinity;
+    const ddProbability = drawdownProbability(ddToFraction, appliedFraction);
+    if (appliedFraction > 1) {
+        warnings.push(warning(WarningCode.RiskKellyOver, `${functionName}: the applied fraction is ${f2(appliedFraction)}× full Kelly (> 1); drawdown risk is severe (P(ever falling to ${pct(ddToFraction)} of start) ≈ ${pct(ddProbability)}).`, 'warn'));
+    }
+    // Fat-tail disclosure (returns path): the Gaussian μ/σ² vs the exact empirical f*.
+    if (resolved.gaussianKelly !== undefined &&
+        Number.isFinite(fullKelly) &&
+        resolved.gaussianKelly > fullKelly * 1.15) {
+        warnings.push(warning(WarningCode.RiskKellyFatTails, `${functionName}: the exact empirical full Kelly (${f3(fullKelly)}) is below the Gaussian μ/σ² estimate (${f3(resolved.gaussianKelly)}) — the return sample's tails cut the safe size.`, 'info'));
+    }
+    let horizonGrowth;
+    if (input.horizonPeriods !== undefined && Number.isFinite(growthRate)) {
+        const logGrowth = input.horizonPeriods * growthRate;
+        horizonGrowth = {
+            horizonPeriods: input.horizonPeriods,
+            logGrowth,
+            growthMultiple: Math.exp(logGrowth),
+        };
+    }
+    const rationale = composeRationale({
+        edgeType,
+        fullKelly,
+        recommendedFraction,
+        appliedFraction,
+        fraction,
+        bindingConstraint,
+        growthRate,
+        growthRateFull,
+        periodsToDouble,
+        ddToFraction,
+        ddProbability,
+        gaussianKelly: resolved.gaussianKelly,
+        horizonGrowth,
+    });
+    return assemble({
+        fullKelly,
+        recommendedFraction,
+        appliedFraction,
+        growthRate,
+        growthRateFull,
+        periodsToDouble,
+        drawdownRisk: { toFraction: ddToFraction, probability: ddProbability },
+        bindingConstraint,
+        gaussianKelly: resolved.gaussianKelly,
+        horizonGrowth,
+        rationale,
+        fraction,
+        edgeType,
+        warnings,
+    });
+}
+function assemble(p) {
+    return {
+        fullKelly: p.fullKelly,
+        recommendedFraction: p.recommendedFraction,
+        appliedFraction: p.appliedFraction,
+        growthRate: p.growthRate,
+        growthRateFull: p.growthRateFull,
+        periodsToDouble: p.periodsToDouble,
+        drawdownRisk: p.drawdownRisk,
+        bindingConstraint: p.bindingConstraint,
+        ...(p.gaussianKelly !== undefined ? { gaussianKelly: p.gaussianKelly } : {}),
+        ...(p.horizonGrowth !== undefined ? { horizonGrowth: p.horizonGrowth } : {}),
+        rationale: p.rationale,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            fraction: p.fraction,
+            drawdownModel: 'continuous-gbm',
+            edgeType: p.edgeType,
+        },
+        diagnostics: {
+            engine: 'kelly-bet',
+            method: p.edgeType === 'binary' || p.edgeType === 'gaussian' ? 'closed-form' : 'brent',
+            converged: true,
+            warnings: p.warnings,
+        },
+    };
+}
+/** Compose the prose rationale from the sizing decision and its supporting numbers. */
+function composeRationale(p) {
+    const size = Number.isFinite(p.recommendedFraction)
+        ? `${pct(p.recommendedFraction)} of bankroll`
+        : 'an unbounded fraction (cap it with maxFraction)';
+    const full = Number.isFinite(p.fullKelly) ? `${pct(p.fullKelly)}` : 'unbounded (no downside)';
+    const why = {
+        fraction: `${f2(p.fraction)}× fractional-Kelly cap (full Kelly is ${full})`,
+        'drawdown-limit': `drawdown budget (kept at ${f2(p.appliedFraction)}× full Kelly so P(ever falling to ${pct(p.ddToFraction)} of start) ≤ target)`,
+        'max-fraction': `the hard maxFraction cap`,
+        'no-edge': 'no edge',
+        'no-downside': 'no downside (unbounded full Kelly)',
+    };
+    const drawdown = `At this size the chance of ever falling to ${pct(p.ddToFraction)} of the starting bankroll is ≈ ${pct(p.ddProbability)}.`;
+    const growth = Number.isFinite(p.periodsToDouble)
+        ? `Expected log-growth ${f3(p.growthRate)} per period (~${Math.ceil(p.periodsToDouble)} periods to double); full Kelly would grow at ${f3(p.growthRateFull)}.`
+        : `Expected log-growth ${f3(p.growthRate)} per period.`;
+    const tail = p.gaussianKelly !== undefined &&
+        Number.isFinite(p.fullKelly) &&
+        p.gaussianKelly > p.fullKelly * 1.15
+        ? ` The Gaussian μ/σ² estimate (${pct(p.gaussianKelly)}) is larger — the sample's tails cut the safe size.`
+        : '';
+    const horizonPeriods = p.horizonGrowth
+        ? ` Over ${p.horizonGrowth.horizonPeriods} periods the median growth multiple is ~${f2(p.horizonGrowth.growthMultiple)}×.`
+        : '';
+    return `Bet ${size} — set by the ${why[p.bindingConstraint]}. ${growth} ${drawdown}${tail}${horizonPeriods}`;
+}
+/**
+ * Estimation-error-shrunk portfolio Kelly. The plug-in weights `Σ̂⁻¹μ̂` overbet because `μ̂`/`Σ̂` are
+ * estimated from a finite sample; this scales them by the growth-optimal factor
+ * `c* = max(0, 1 − (n/T)/θ̂²)` (`θ̂² = μ̂ᵀΣ̂⁻¹μ̂`), returns a zero book when the estimated edge is
+ * indistinguishable from sampling noise (`n/T ≥ θ̂²`), and discloses the biased-vs-corrected Sharpe and
+ * the naive book's (often negative) expected out-of-sample growth. See `docs/specs/shrunk-kelly.md`.
+ */
+export function shrunkKelly(input) {
+    const functionName = 'shrunkKelly';
+    requireArgumentObject(functionName, 'input', input);
+    // Law 12: a misspelled knob (`samplesize` silently missing) must throw, never no-op.
+    ensureKnownKeys(functionName, 'input', input, ['mean', 'covariance', 'sampleSize', 'fraction']);
+    requireArgumentArray(functionName, 'input.mean', input.mean);
+    requireArgumentArray(functionName, 'input.covariance', input.covariance);
+    const n = input.mean.length;
+    if (n === 0) {
+        throw new InputError(`${functionName}: mean must have at least one asset.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { assets: 0 },
+        });
+    }
+    for (let i = 0; i < n; i++)
+        ensureFinite(input.mean[i], `mean[${i}]`, functionName);
+    if (input.covariance.length !== n) {
+        throw new InputError(`${functionName}: covariance must be ${n}×${n} to match mean (got ${input.covariance.length} rows).`, { code: ErrorCode.InputOutOfRange, context: { rows: input.covariance.length, expected: n } });
+    }
+    for (let i = 0; i < n; i++) {
+        requireArgumentArray(functionName, `covariance[${i}]`, input.covariance[i]);
+        if (input.covariance[i].length !== n) {
+            throw new InputError(`${functionName}: covariance row ${i} has length ${input.covariance[i].length}, expected ${n}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { row: i, length: input.covariance[i].length },
+            });
+        }
+        for (let j = 0; j < n; j++)
+            ensureFinite(input.covariance[i][j], `covariance[${i}][${j}]`, functionName);
+    }
+    ensurePositive(input.sampleSize, 'sampleSize', functionName);
+    ensureFiniteWhenPresent(input.fraction, 'fraction', 'shrunkKelly');
+    const fraction = input.fraction ?? 1;
+    ensurePositive(fraction, 'fraction', functionName);
+    const T = input.sampleSize;
+    // Σ̂⁻¹μ̂ via Cholesky — throws a typed LinalgNotPositiveDefinite if Σ̂ is not SPD.
+    const L = cholesky(input.covariance);
+    const naiveWeights = choleskySolve(L, input.mean);
+    const inSampleSharpeSquared = input.mean.reduce((s, m, i) => s + m * naiveWeights[i], 0);
+    const nOverT = n / T;
+    const correctedSharpeSquared = inSampleSharpeSquared - nOverT;
+    const shrinkage = inSampleSharpeSquared > 0 ? Math.max(0, 1 - nOverT / inSampleSharpeSquared) : 0;
+    const appliedScaling = fraction * shrinkage;
+    const weights = naiveWeights.map((w) => appliedScaling * w);
+    // Expected OOS log-growth g(a) = a·θ²_corrected − ½a²·θ² (θ² the in-sample plug-in squared Sharpe).
+    const growthAt = (a) => a * correctedSharpeSquared - 0.5 * a * a * inSampleSharpeSquared;
+    const expectedGrowth = growthAt(appliedScaling);
+    const naiveExpectedGrowth = growthAt(1);
+    const warnings = [];
+    if (correctedSharpeSquared <= 0) {
+        warnings.push(warning(WarningCode.RiskKellyEstimationNoEdge, `${functionName}: n/T = ${nOverT.toFixed(4)} ≥ the in-sample squared Sharpe ${inSampleSharpeSquared.toFixed(4)}, so the estimated edge is indistinguishable from sampling noise — the shrunk book is zero. Don't bet on this estimate.`, 'warn', { nOverT, inSampleSharpeSquared, correctedSharpeSquared }));
+    }
+    else if (naiveExpectedGrowth < 0) {
+        warnings.push(warning(WarningCode.RiskKellyNaiveOverbet, `${functionName}: the naive Kelly book would erode capital out-of-sample (expected growth ${naiveExpectedGrowth.toFixed(4)} < 0); shrinking to c* = ${shrinkage.toFixed(3)} restores positive expected growth (${expectedGrowth.toFixed(4)}).`, 'warn', { naiveExpectedGrowth, shrinkage, expectedGrowth }));
+    }
+    if (T <= 2 * n) {
+        warnings.push(warning(WarningCode.RiskKellyEstimationThinSample, `${functionName}: only ${T} observations for ${n} assets (T ≤ 2n) — the shrinkage is extreme and the estimates are unreliable; treat the sizing as indicative.`, 'warn', { sampleSize: T, assets: n }));
+    }
+    return {
+        shrinkage,
+        appliedScaling,
+        weights,
+        naiveWeights,
+        inSampleSharpeSquared,
+        correctedSharpeSquared,
+        expectedGrowth,
+        naiveExpectedGrowth,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            assets: n,
+            sampleSize: T,
+            fraction,
+        },
+        diagnostics: {
+            engine: 'shrunk-kelly',
+            method: 'estimation-error shrinkage',
+            converged: shrinkage > 0,
+            warnings,
+        },
+    };
+}
+/** Fraction of gross growth consumed by costs above which the high-drag warning fires. */
+const HIGH_COST_DRAG = 0.25;
+/** Resolve the continuous edge to (μ, σ²), matching `kellyBet`'s Gaussian / returns conventions. */
+function resolveContinuousEdge(edge, functionName) {
+    requireArgumentObject(functionName, 'edge', edge);
+    if ('gaussian' in edge) {
+        const g = edge.gaussian;
+        requireArgumentObject(functionName, 'edge.gaussian', g);
+        ensureFinite(g.mean, 'edge.gaussian.mean', functionName);
+        ensureFinite(g.variance, 'edge.gaussian.variance', functionName);
+        // C (hygiene): a zero variance is a degenerate edge (null sizing, below), a negative one is
+        // not a variance at all.
+        if (g.variance < 0) {
+            throw new InputError(`${functionName}: edge.gaussian.variance must be non-negative; got ${g.variance}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { variance: g.variance },
+            });
+        }
+        return { mu: g.mean, v: g.variance, edgeType: 'gaussian' };
+    }
+    if ('returns' in edge) {
+        requireArgumentArray(functionName, 'edge.returns', edge.returns);
+        const r = edge.returns;
+        const n = r.length;
+        if (n < 2) {
+            throw new InputError(`${functionName}: edge.returns needs ≥ 2 observations; got ${n}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { observations: n },
+            });
+        }
+        let mu = 0;
+        for (let i = 0; i < n; i++) {
+            ensureFinite(r[i], `edge.returns[${i}]`, functionName);
+            mu += r[i];
+        }
+        mu /= n;
+        const v = variance(r, { population: true });
+        return { mu, v, edgeType: 'returns' };
+    }
+    throw new InputError(`${functionName}: edge must supply { gaussian } or { returns }.`, {
+        code: ErrorCode.InputMissingField,
+        context: { edge },
+    });
+}
+/**
+ * Cost-aware Kelly for a continuous edge. Costs — a per-period holding cost plus an amortized round-trip
+ * cost, `c = holdingCost + roundTripCost/horizonPeriods` — reduce the drift (`μ → μ − c`, variance unchanged),
+ * so the growth-optimal size shrinks to `netKelly = max(0, (μ−c)/σ²)` and below the breakeven cost `μ`
+ * the edge is not worth betting. Reports gross vs net Kelly, the growth drag, the penalty for naively
+ * betting gross while paying costs, and refuses a losing bet. See `docs/specs/cost-aware-kelly.md`.
+ */
+export function costAwareKelly(input) {
+    const functionName = 'costAwareKelly';
+    requireArgumentObject(functionName, 'input', input);
+    // Law 12: a misspelled knob (`holdingcost` silently costless) must throw, never no-op.
+    ensureKnownKeys(functionName, 'input', input, [
+        'edge',
+        'holdingCost',
+        'roundTripCost',
+        'horizonPeriods',
+        'fraction',
+    ]);
+    const { mu, v, edgeType } = resolveContinuousEdge(input.edge, functionName);
+    ensureFiniteWhenPresent(input.holdingCost, 'holdingCost', 'costAwareKelly');
+    ensureFiniteWhenPresent(input.horizonPeriods, 'horizonPeriods', 'costAwareKelly');
+    const holdingCost = input.holdingCost ?? 0;
+    ensureFiniteWhenPresent(input.roundTripCost, 'roundTripCost', 'costAwareKelly');
+    const roundTripCost = input.roundTripCost ?? 0;
+    ensureFinite(holdingCost, 'holdingCost', functionName);
+    ensureFinite(roundTripCost, 'roundTripCost', functionName);
+    if (holdingCost < 0 || roundTripCost < 0) {
+        throw new InputError(`${functionName}: holdingCost and roundTripCost must be ≥ 0.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { holdingCost, roundTripCost },
+        });
+    }
+    let amortizedRoundTrip = 0;
+    if (roundTripCost > 0) {
+        if (input.horizonPeriods === undefined || !(input.horizonPeriods > 0)) {
+            throw new InputError(`${functionName}: a positive roundTripCost needs a positive horizonPeriods to amortize over; got ${input.horizonPeriods}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { roundTripCost, horizonPeriods: input.horizonPeriods },
+            });
+        }
+        amortizedRoundTrip = roundTripCost / input.horizonPeriods;
+    }
+    ensureFiniteWhenPresent(input.fraction, 'fraction', 'costAwareKelly');
+    const fraction = input.fraction ?? 0.5;
+    ensureFinite(fraction, 'fraction', functionName);
+    if (!(fraction > 0)) {
+        throw new InputError(`${functionName}: fraction must be positive; got ${fraction}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { fraction },
+        });
+    }
+    const c = holdingCost + amortizedRoundTrip;
+    const netEdge = mu - c;
+    if (!(v > 0)) {
+        // C (hygiene): a zero-variance edge has no growth-optimal size — μ/σ² is undefined. The
+        // costs and the edge are still reported; every size is null beside the diagnostic.
+        const isProfitable = c < mu;
+        return {
+            costPerPeriod: c,
+            grossKelly: null,
+            netKelly: null,
+            recommendedFraction: null,
+            breakevenCost: mu,
+            isProfitable,
+            grossGrowth: null,
+            netGrowth: null,
+            growthDrag: null,
+            ignoringCostsGrowth: null,
+            mean: mu,
+            variance: v,
+            rationale: `No size: the edge has zero variance (mean ${f3(mu)}, variance 0), so the growth-optimal fraction μ/σ² is undefined. Costs of ${f3(c)}/period ${isProfitable ? 'leave a positive net edge' : 'meet or exceed the edge'}; size it by a policy cap, not by Kelly.`,
+            assumptions: { conventionsVersion: CONVENTIONS_VERSION, fraction, edgeType },
+            diagnostics: {
+                engine: 'cost-aware-kelly',
+                method: 'continuous-edge drift adjustment',
+                converged: true,
+                warnings: [
+                    warning(WarningCode.RiskKellyZeroVariance, `${functionName}: the edge has zero variance; the Kelly fraction is undefined and every size is null.`, 'warn', { mean: mu, variance: v }),
+                ],
+            },
+        };
+    }
+    const grossKelly = mu / v;
+    const netKelly = Math.max(0, netEdge / v);
+    const recommendedFraction = fraction * netKelly;
+    const grossGrowth = (mu * mu) / (2 * v);
+    const netGrowth = netEdge > 0 ? (netEdge * netEdge) / (2 * v) : 0;
+    const growthDrag = grossGrowth - netGrowth;
+    // Log-growth of betting the (cost-blind) gross Kelly while actually paying c: g_net(grossKelly).
+    const ignoringCostsGrowth = grossKelly * netEdge - 0.5 * grossKelly * grossKelly * v;
+    const isProfitable = c < mu;
+    const warnings = [];
+    if (!isProfitable) {
+        warnings.push(warning(WarningCode.RiskCostExceedsEdge, `${functionName}: the per-period cost ${f3(c)} ≥ the edge ${f3(mu)} — costs consume the entire edge, so don't bet (netKelly 0).`, 'warn', { cost: c, edge: mu }));
+    }
+    else if (grossGrowth > 0 && growthDrag / grossGrowth > HIGH_COST_DRAG) {
+        warnings.push(warning(WarningCode.RiskHighCostDrag, `${functionName}: costs consume ${pct(growthDrag / grossGrowth)} of the gross log-growth (${f3(growthDrag)} of ${f3(grossGrowth)}); size shrinks from ${f3(grossKelly)} to ${f3(netKelly)}.`, 'warn', { growthDrag, grossGrowth, fraction: growthDrag / grossGrowth }));
+    }
+    const rationale = isProfitable
+        ? `Costs of ${f3(c)}/period cut the growth-optimal size from ${f3(grossKelly)} (gross) to ${f3(netKelly)} (net) — a ${pct(1 - netKelly / grossKelly)} reduction; at ${pct(fraction)}-Kelly, bet ${f3(recommendedFraction)}. They consume ${pct(growthDrag / grossGrowth)} of the gross log-growth, and naively betting the gross size while paying them gives up a further ${pct((netGrowth - ignoringCostsGrowth) / netGrowth)} of the achievable growth.`
+        : `Don't bet: costs of ${f3(c)}/period meet or exceed the edge ${f3(mu)}, so the net edge is non-positive — there is no growth-optimal position with these costs.`;
+    return {
+        costPerPeriod: c,
+        grossKelly,
+        netKelly,
+        recommendedFraction,
+        breakevenCost: mu,
+        isProfitable,
+        grossGrowth,
+        netGrowth,
+        growthDrag,
+        ignoringCostsGrowth,
+        mean: mu,
+        variance: v,
+        rationale,
+        assumptions: { conventionsVersion: CONVENTIONS_VERSION, fraction, edgeType },
+        diagnostics: {
+            engine: 'cost-aware-kelly',
+            method: 'continuous-edge drift adjustment',
+            converged: true,
+            warnings,
+        },
+    };
+}
+//# sourceMappingURL=kelly.js.map