@adaptic/utils 0.0.1031 → 0.0.1032

package/dist/index.cjs

@@ -20243,6 +20243,93 @@ function getEquityValues(equityData, portfolioHistory, marketTimeUtil, period) {
     };
 }
 
+/**
+ * A measured statistic and the cohort it was measured on, carried as one
+ * inseparable value.
+ *
+ * A ratio is meaningless without the population it was taken over: the same
+ * `0.42` is a strong result on 2,000 trades and noise on five, and a `0.0`
+ * returned because nothing could be computed is indistinguishable from a `0.0`
+ * that was genuinely measured. Both confusions are the same error — a number
+ * read apart from its unit and its cohort — and both have produced wrong
+ * conclusions from correct arithmetic.
+ *
+ * This type removes the option. Every statistic shaped by a population carries
+ * `sampleCount` (how many observations actually entered the computation) and
+ * `coverage` (what fraction of the observations the caller offered were usable),
+ * on BOTH branches: an unavailable statistic still reports how much data it
+ * saw, because "we had nothing" and "we had 900 rows and still could not
+ * compute it" are different facts with different responses.
+ *
+ * Absence is a branch of the union rather than a sentinel value. There is no
+ * number a caller can read without first proving the statistic exists, which is
+ * what keeps an unknown from silently becoming a zero on its way to a decision.
+ *
+ * @module sample-statistic
+ */
+/**
+ * Build the cohort descriptor for a computation.
+ *
+ * `coverage` is derived here rather than supplied, so it cannot drift from the
+ * counts it claims to summarise. A zero request yields zero coverage: no
+ * observations were asked for, so none were covered, and the alternative (`1`)
+ * would report a vacuous computation as fully covered.
+ *
+ * @param requestedCount - Observations offered, or the window width requested.
+ * @param sampleCount - Observations that entered the computation.
+ * @returns The cohort descriptor with `coverage` derived from the two counts.
+ * @throws When either count is negative or non-finite, which is a programming
+ *         error rather than a data condition.
+ */
+function sampleCohort(requestedCount, sampleCount) {
+    if (!Number.isFinite(requestedCount) || requestedCount < 0) {
+        throw new Error(`sampleCohort: requestedCount must be a non-negative finite number (got ${requestedCount})`);
+    }
+    if (!Number.isFinite(sampleCount) || sampleCount < 0) {
+        throw new Error(`sampleCohort: sampleCount must be a non-negative finite number (got ${sampleCount})`);
+    }
+    const NOTHING_REQUESTED_COVERAGE = 0;
+    const FULL_COVERAGE = 1;
+    const coverage = requestedCount === 0
+        ? NOTHING_REQUESTED_COVERAGE
+        : Math.min(FULL_COVERAGE, sampleCount / requestedCount);
+    return { sampleCount, requestedCount, coverage };
+}
+/**
+ * Wrap a computed value with its cohort.
+ *
+ * @param value - The measured statistic.
+ * @param cohort - The cohort it was measured on.
+ * @returns The available branch of {@link SampleStatistic}.
+ */
+function availableStatistic(value, cohort) {
+    return { available: true, value, ...cohort };
+}
+/**
+ * Record that a statistic could not be computed, and what was seen instead.
+ *
+ * @param reason - Which class of failure prevented the computation.
+ * @param detail - Specifics for logs; never machine-parsed.
+ * @param cohort - What data was available when the attempt was abandoned.
+ * @returns The unavailable branch of {@link SampleStatistic}.
+ */
+function unavailableStatistic(reason, detail, cohort) {
+    return { available: false, reason, detail, ...cohort };
+}
+/**
+ * Narrow a statistic to its available branch.
+ *
+ * Exists so consumers in other packages can discriminate without restating the
+ * predicate, and so the discriminant stays a single named concept if the shape
+ * ever grows a third branch.
+ *
+ * @param statistic - The statistic to test.
+ * @returns Whether the statistic carries a value.
+ */
+function isAvailable(statistic) {
+    return statistic.available;
+}
+
 // risk-free-rate.ts
 /**
  * Conservative fallback annual risk-free rate used when no live rate has been
@@ -20601,57 +20688,60 @@ function alignReturns(tradeBars, benchmarkBars) {
     });
     return { alignedTradeReturns, alignedBenchmarkReturns, alignedDates };
 }
-/*
- * Calculate Beta from Returns
- * @param portfolioReturns - Array of portfolio returns
- * @param benchmarkReturns - Array of benchmark returns
- * @returns Object containing beta, covariance, variance, and average returns
+/**
+ * Beta of a portfolio against a benchmark, from paired period returns.
+ *
+ * Non-finite rows are dropped pairwise — a return that is `NaN` on either leg
+ * cannot contribute to a covariance — and the count that survives is reported
+ * as the cohort rather than discarded. That reporting is the point: silently
+ * computing a beta on the 12 rows that happened to be clean, and returning it
+ * with the same shape as a beta over all 900, is how a statistic measured on
+ * one population gets applied to another.
+ *
+ * When beta cannot be computed the result is the unavailable branch, never a
+ * numeric stand-in. A beta of `0` asserts that the portfolio does not move with
+ * the market, which is a strong and consequential claim; emitting it to mean
+ * "we could not tell" makes every alpha derived from it wrong by the whole
+ * benchmark term.
+ *
+ * @param portfolioReturns - Portfolio period returns.
+ * @param benchmarkReturns - Benchmark period returns, index-aligned to the portfolio.
+ * @returns The beta components with their cohort, or a typed unavailable result.
  * @example
- * const portfolioReturns = [0.05, -0.02, 0.03];
- * const benchmarkReturns = [0.03, -0.01, 0.02];
- * const beta = calculateBetaFromReturns(portfolioReturns, benchmarkReturns);
- * // beta = { beta: 1.5, covariance: 0.0005, variance: 0.0003, averagePortfolioReturn: 0.02, averageBenchmarkReturn: 0.02 }
- * @throws Will log warnings if input data is invalid or insufficient
- * @throws Will log warnings if benchmark variance is effectively zero
- * @throws Will log warnings if beta calculation results in a non-finite value
- * @throws Will log warnings if there are not enough valid data points for calculation
- * @throws Will log warnings if benchmark variance is zero or non-finite
+ * const result = calculateBetaFromReturns([0.05, -0.02, 0.03], [0.03, -0.01, 0.02]);
+ * if (result.available) {
+ *   // result.value.beta, alongside result.sampleCount and result.coverage
+ * }
  */
 function calculateBetaFromReturns$1(portfolioReturns, benchmarkReturns) {
-    // Input validation
-    if (!Array.isArray(portfolioReturns) ||
-        !Array.isArray(benchmarkReturns) ||
-        portfolioReturns.length !== benchmarkReturns.length ||
-        portfolioReturns.length < 2) {
-        getLogger().warn("Invalid or insufficient return data for beta calculation");
-        return {
-            beta: 0,
-            covariance: 0,
-            variance: 0,
-            averagePortfolioReturn: 0,
-            averageBenchmarkReturn: 0,
-        };
-    }
-    // Filter out any non-finite values before calculations
-    const validIndices = [...Array(portfolioReturns.length).keys()].filter((i) => isFinite(portfolioReturns[i]) && isFinite(benchmarkReturns[i]));
-    if (validIndices.length < 2) {
-        getLogger().warn("Not enough valid data points for beta calculation");
-        return {
-            beta: 0,
-            covariance: 0,
-            variance: 0,
-            averagePortfolioReturn: 0,
-            averageBenchmarkReturn: 0,
-        };
+    // A covariance is defined over PAIRS, so the offered cohort is the number of
+    // index positions both series can supply. Ragged input is a caller defect
+    // rather than a data condition, and it is reported as such instead of being
+    // silently truncated to the shorter series.
+    if (!Array.isArray(portfolioReturns) || !Array.isArray(benchmarkReturns)) {
+        return unavailableStatistic("invalid_input", "portfolioReturns and benchmarkReturns must both be arrays", sampleCohort(0, 0));
+    }
+    const requestedCount = portfolioReturns.length;
+    if (portfolioReturns.length !== benchmarkReturns.length) {
+        return unavailableStatistic("invalid_input", `series lengths differ: portfolio ${portfolioReturns.length}, benchmark ${benchmarkReturns.length}`, sampleCohort(requestedCount, 0));
+    }
+    // Pairwise finiteness filter. Both legs must be usable for the pair to
+    // contribute; keeping a pair on the strength of one leg would mix a real
+    // observation with a fabricated one.
+    const validIndices = [...Array(requestedCount).keys()].filter((i) => isFinite(portfolioReturns[i]) && isFinite(benchmarkReturns[i]));
+    const cohort = sampleCohort(requestedCount, validIndices.length);
+    // Bessel-corrected estimators need at least one degree of freedom, so two
+    // usable pairs is the floor below which no sample variance exists.
+    const MIN_PAIRS_FOR_SAMPLE_VARIANCE = 2;
+    if (validIndices.length < MIN_PAIRS_FOR_SAMPLE_VARIANCE) {
+        getLogger().warn(`Beta unavailable: ${validIndices.length} usable pairs of ${requestedCount} offered.`);
+        return unavailableStatistic(validIndices.length === 0 ? "no_usable_samples" : "insufficient_samples", `beta needs at least ${MIN_PAIRS_FOR_SAMPLE_VARIANCE} finite pairs; ${validIndices.length} of ${requestedCount} were usable`, cohort);
     }
-    // Use validated indices only
     const validPortfolioReturns = validIndices.map((i) => portfolioReturns[i]);
     const validBenchmarkReturns = validIndices.map((i) => benchmarkReturns[i]);
-    // Calculate means
     const n = validIndices.length;
     const averagePortfolioReturn = validPortfolioReturns.reduce((sum, ret) => sum + ret, 0) / n;
     const averageBenchmarkReturn = validBenchmarkReturns.reduce((sum, ret) => sum + ret, 0) / n;
-    // Calculate covariance and variance with Welford's online algorithm for numerical stability
     let covariance = 0;
     let variance = 0;
     for (let i = 0; i < n; i++) {
@@ -20660,30 +20750,26 @@ function calculateBetaFromReturns$1(portfolioReturns, benchmarkReturns) {
         covariance += portfolioDiff * benchmarkDiff;
         variance += benchmarkDiff * benchmarkDiff;
     }
-    // Finalize calculations using sample (Bessel-corrected) estimators —
-    // divide by (n - 1), not n. The guard above (validIndices.length < 2)
-    // already ensures n >= 2, so (n - 1) is always safe.
+    // Sample (Bessel-corrected) estimators — divide by (n - 1), not n. The guard
+    // above ensures n >= 2, so (n - 1) is always safe.
     covariance /= n - 1;
     variance /= n - 1;
-    // Handle zero variance case
-    if (Math.abs(variance) < 1e-10) {
-        getLogger().warn("Benchmark variance is effectively zero. Setting beta to 0.");
-        return {
-            beta: 0,
-            covariance,
-            variance,
-            averagePortfolioReturn,
-            averageBenchmarkReturn,
-        };
-    }
-    const beta = covariance / variance;
-    return {
-        beta,
+    // A benchmark that never moved has no variance to regress against, so beta is
+    // undefined rather than zero. VARIANCE_NOISE_FLOOR absorbs the case where a
+    // constant series still produces a tiny positive variance because the computed
+    // mean differs from the constant by a rounding unit.
+    const VARIANCE_NOISE_FLOOR = 1e-10;
+    if (Math.abs(variance) < VARIANCE_NOISE_FLOOR) {
+        getLogger().warn("Beta unavailable: benchmark variance is effectively zero.");
+        return unavailableStatistic("degenerate_population", `benchmark variance ${variance} is below the noise floor ${VARIANCE_NOISE_FLOOR}; beta is undefined`, cohort);
+    }
+    return availableStatistic({
+        beta: covariance / variance,
         covariance,
         variance,
         averagePortfolioReturn,
         averageBenchmarkReturn,
-    };
+    }, cohort);
 }
 /**
  * Calculates the total return for a position, respecting position direction
@@ -20767,7 +20853,18 @@ async function calculateAlphaAndBeta$1(tradeBars, benchmarkBars, isShort) {
         : rawTradeReturns;
     // Calculate beta with position-adjusted returns
     const beta = calculateBetaFromReturns$1(alignedTradeReturns, alignedBenchmarkReturns);
-    if (!isFinite(beta.beta)) {
+    // Alpha is the return left over after the benchmark term, so an unknown beta
+    // makes alpha unknown too. Substituting any number here — zero most of all —
+    // would credit the whole benchmark move to the strategy.
+    if (!beta.available) {
+        getLogger().warn(`Alpha unavailable: beta could not be computed (${beta.reason}: ${beta.detail}).`);
+        return {
+            alpha: "N/A",
+            alphaAnnualized: "N/A",
+            beta: "N/A",
+        };
+    }
+    if (!isFinite(beta.value.beta)) {
         getLogger().warn("Beta calculation resulted in a non-finite value.");
         return {
             alpha: "N/A",
@@ -20778,7 +20875,7 @@ async function calculateAlphaAndBeta$1(tradeBars, benchmarkBars, isShort) {
     // For short positions, the interpretation of beta changes
     // A positive beta on a short means the position moves with the market,
     // which is bad for a short. We invert it for consistency.
-    const positionAwareBeta = isShort ? -beta.beta : beta.beta;
+    const positionAwareBeta = isShort ? -beta.value.beta : beta.value.beta;
     const avgTradeReturn = alignedTradeReturns.reduce((sum, ret) => sum + ret, 0) /
         alignedTradeReturns.length;
     const avgBenchmarkReturn = alignedBenchmarkReturns.reduce((sum, ret) => sum + ret, 0) /
@@ -21397,7 +21494,18 @@ async function calculateAlphaAndBeta(portfolioHistory, benchmarkBars) {
     const benchmarkAvgReturn = alignedBenchmarkReturns.reduce((sum, ret) => sum + ret, 0) / n;
     // **Calculate beta**
     const beta = calculateBetaFromReturns(alignedPortfolioReturns, alignedBenchmarkReturns);
-    if (!isFinite(beta.beta)) {
+    // Alpha is what remains after subtracting the benchmark term, so an unknown
+    // beta leaves alpha unknown. Any numeric stand-in — zero above all — would
+    // attribute the entire benchmark move to the strategy.
+    if (!beta.available) {
+        getLogger().warn(`Alpha unavailable: beta could not be computed (${beta.reason}: ${beta.detail}).`);
+        return {
+            alpha: "N/A",
+            alphaAnnualized: "N/A",
+            beta: "N/A",
+        };
+    }
+    if (!isFinite(beta.value.beta)) {
         getLogger().warn("Beta calculation resulted in a non-finite value.");
         return {
             alpha: "N/A",
@@ -21412,7 +21520,7 @@ async function calculateAlphaAndBeta(portfolioHistory, benchmarkBars) {
     const tradingDaysPerYear = 252;
     const riskFreeRateDaily = riskFreeRateAnnual / tradingDaysPerYear;
     const alpha = portfolioAvgReturn -
-        (riskFreeRateDaily + beta.beta * (benchmarkAvgReturn - riskFreeRateDaily));
+        (riskFreeRateDaily + beta.value.beta * (benchmarkAvgReturn - riskFreeRateDaily));
     const alphaAnnualized = alpha * tradingDaysPerYear;
     if (!isFinite(alphaAnnualized)) {
         getLogger().warn("Alpha calculation resulted in a non-finite value.");
@@ -21425,7 +21533,7 @@ async function calculateAlphaAndBeta(portfolioHistory, benchmarkBars) {
     return {
         alpha: `${(alpha * 100).toFixed(2)}`,
         alphaAnnualized: `${(alphaAnnualized * 100).toFixed(2)}`,
-        beta: `${(beta.beta * 100).toFixed(2)}`,
+        beta: `${(beta.value.beta * 100).toFixed(2)}`,
     };
 }
 // **Helper function to calculate daily returns with Unix millisecond timestamps**
@@ -21648,27 +21756,40 @@ function alignReturnsByDate(portfolioHistory, benchmarkBars) {
     return { alignedPortfolioReturns, alignedBenchmarkReturns };
 }
 /**
- * Calculates the beta of the portfolio compared to a benchmark.
- * @param portfolioReturns - Array of portfolio returns.
- * @param benchmarkReturns - Array of benchmark returns.
- * @returns An object containing beta and intermediate calculations.
+ * Beta of a portfolio against a benchmark, from paired period returns.
+ *
+ * The two series are index-aligned pairs by contract: every mean, covariance
+ * and variance below is taken over the SAME row set. A length mismatch is
+ * therefore reported as invalid input rather than absorbed, because dividing
+ * one series' sum by the other series' length produces a mean of a population
+ * that does not exist — a number with no cohort, which is the failure this
+ * return type exists to make impossible.
+ *
+ * An uncomputable beta is returned as the unavailable branch, never as `0`.
+ * Zero beta is a claim of no market exposure, and downstream alpha attributes
+ * the entire benchmark move to the strategy when it believes that claim.
+ *
+ * @param portfolioReturns - Portfolio period returns.
+ * @param benchmarkReturns - Benchmark period returns, index-aligned to the portfolio.
+ * @returns The beta components with their cohort, or a typed unavailable result.
  */
 function calculateBetaFromReturns(portfolioReturns, benchmarkReturns) {
-    const n = portfolioReturns.length;
-    if (n === 0) {
-        getLogger().warn("No returns to calculate beta.");
-        return {
-            beta: 0,
-            covariance: 0,
-            variance: 0,
-            averagePortfolioReturn: 0,
-            averageBenchmarkReturn: 0,
-        };
-    }
-    // Calculate average returns
+    const requestedCount = portfolioReturns.length;
+    if (portfolioReturns.length !== benchmarkReturns.length) {
+        getLogger().warn(`Beta unavailable: series lengths differ (portfolio ${portfolioReturns.length}, benchmark ${benchmarkReturns.length}).`);
+        return unavailableStatistic("invalid_input", `series lengths differ: portfolio ${portfolioReturns.length}, benchmark ${benchmarkReturns.length}`, sampleCohort(requestedCount, 0));
+    }
+    // Bessel-corrected estimators need one degree of freedom, so two paired
+    // observations is the floor below which no sample variance exists.
+    const MIN_PAIRS_FOR_SAMPLE_VARIANCE = 2;
+    const n = requestedCount;
+    if (n < MIN_PAIRS_FOR_SAMPLE_VARIANCE) {
+        getLogger().warn(`Beta unavailable: ${n} paired returns offered.`);
+        return unavailableStatistic(n === 0 ? "no_usable_samples" : "insufficient_samples", `beta needs at least ${MIN_PAIRS_FOR_SAMPLE_VARIANCE} paired returns; ${n} were offered`, sampleCohort(requestedCount, n));
+    }
+    const cohort = sampleCohort(requestedCount, n);
     const averagePortfolioReturn = portfolioReturns.reduce((sum, ret) => sum + ret, 0) / n;
     const averageBenchmarkReturn = benchmarkReturns.reduce((sum, ret) => sum + ret, 0) / n;
-    // Calculate covariance and variance
     let covariance = 0;
     let variance = 0;
     for (let i = 0; i < n; i++) {
@@ -21678,37 +21799,26 @@ function calculateBetaFromReturns(portfolioReturns, benchmarkReturns) {
         variance += benchmarkDiff ** 2;
     }
     // Use sample (Bessel-corrected) estimators — divide by (n - 1), not n.
-    // For n === 1 there is no degrees-of-freedom left; treat as zero variance
-    // so beta falls through to the zero-variance guard below.
-    const denom = n > 1 ? n - 1 : 1;
-    covariance /= denom;
-    variance /= denom;
-    // Handle zero (or numerically-degenerate) variance. A constant benchmark
-    // series can still produce a tiny nonzero variance because the computed
-    // mean differs from the constant by an ulp; dividing covariance by that
-    // rounding noise yields a meaningless beta. Treat any variance at or
-    // below the summation noise floor — (n * eps * |mean|)^2, the square of
-    // the worst-case naive-summation error — as zero. When the mean is
-    // exactly 0 this reduces to the exact zero check.
+    covariance /= n - 1;
+    variance /= n - 1;
+    // A constant benchmark series can still produce a tiny nonzero variance
+    // because the computed mean differs from the constant by an ulp; dividing
+    // covariance by that rounding noise yields a meaningless beta. Treat any
+    // variance at or below the summation noise floor — (n * eps * |mean|)^2, the
+    // square of the worst-case naive-summation error — as no variance at all.
+    // When the mean is exactly 0 this reduces to the exact zero check.
     const varianceNoiseFloor = (n * Number.EPSILON * Math.abs(averageBenchmarkReturn)) ** 2;
     if (variance <= varianceNoiseFloor) {
-        getLogger().warn("Benchmark variance is zero or below the floating-point noise floor. Setting beta to 0.");
-        return {
-            beta: 0,
-            covariance,
-            variance,
-            averagePortfolioReturn,
-            averageBenchmarkReturn,
-        };
+        getLogger().warn("Beta unavailable: benchmark variance is zero or below the floating-point noise floor.");
+        return unavailableStatistic("degenerate_population", `benchmark variance ${variance} is at or below the summation noise floor ${varianceNoiseFloor}; beta is undefined`, cohort);
     }
-    const beta = covariance / variance;
-    return {
-        beta,
+    return availableStatistic({
+        beta: covariance / variance,
         covariance,
         variance,
         averagePortfolioReturn,
         averageBenchmarkReturn,
-    };
+    }, cohort);
 }
 /**
  * Calculates the information ratio of the portfolio compared to a benchmark.
@@ -22187,7 +22297,14 @@ var riskNs = /*#__PURE__*/Object.freeze({
  * Conventions:
  * - tradePnls / tradeReturns is an array of per-trade realised P&L or return
  *   (positive = win, negative = loss, zero = breakeven).
- * - All "rolling*" functions return null when fewer than `windowSize` trades exist.
+ * - Every statistic here is a ratio or a mean over a WINDOW, so every one is
+ *   returned as a {@link SampleStatistic}: the value cannot be read without the
+ *   `sampleCount` it was taken over and the `coverage` of the window that was
+ *   asked for. A hit-rate is a different claim on 5 trades than on 500, and a
+ *   window that could only be half-filled is a different cohort from a full
+ *   one — a caller holding a bare number can tell neither apart.
+ * - A window that cannot support the statistic returns the unavailable branch
+ *   with a reason, never a numeric stand-in. Zero is a measurement.
  * - All public functions reject non-finite inputs (NaN, Infinity) by throwing.
  *   Callers must pre-validate or filter their inputs.
  */
@@ -22203,21 +22320,38 @@ function assertFiniteArray(name, arr) {
         }
     }
 }
+/**
+ * Report a window that holds fewer trades than it asked for.
+ *
+ * Shared so every rolling function describes a short window the same way — the
+ * cohort is `(requested = windowSize, sampled = what exists)`, which is the
+ * pair a caller needs to distinguish a warm-up from a data gap.
+ *
+ * @param name - The calling function, for the detail string.
+ * @param available - Trades actually present.
+ * @param windowSize - Trades the window asked for.
+ * @returns The unavailable branch describing the short window.
+ */
+function insufficientWindow(name, available, windowSize) {
+    return unavailableStatistic("insufficient_samples", `${name}: window of ${windowSize} requested, only ${available} trades available`, sampleCohort(windowSize, available));
+}
 /**
  * Rolling expectancy: mean P&L over the most-recent `windowSize` trades.
  *
  * @param tradePnls - Array of per-trade realised P&L values.
  * @param windowSize - Number of most-recent trades to include. Must be a positive integer.
- * @returns Mean P&L of the last `windowSize` trades, or null when fewer than `windowSize` exist.
+ * @returns Mean P&L of the last `windowSize` trades with its cohort, or a typed
+ *          unavailable result when fewer than `windowSize` trades exist.
  * @throws When `windowSize` is not a positive integer or any input is non-finite.
  */
 function calculateRollingExpectancy(tradePnls, windowSize) {
     assertWindowSize("calculateRollingExpectancy", windowSize);
-    if (tradePnls.length < windowSize)
-        return null;
+    if (tradePnls.length < windowSize) {
+        return insufficientWindow("calculateRollingExpectancy", tradePnls.length, windowSize);
+    }
     assertFiniteArray("calculateRollingExpectancy", tradePnls);
     const slice = tradePnls.slice(-windowSize);
-    return slice.reduce((a, b) => a + b, 0) / windowSize;
+    return availableStatistic(slice.reduce((a, b) => a + b, 0) / windowSize, sampleCohort(windowSize, windowSize));
 }
 /**
  * Rolling hit-rate: fraction of strictly-positive P&L trades in the most-recent
@@ -22225,42 +22359,53 @@ function calculateRollingExpectancy(tradePnls, windowSize) {
  *
  * @param tradePnls - Array of per-trade realised P&L values.
  * @param windowSize - Number of most-recent trades to include. Must be a positive integer.
- * @returns Fraction of winning trades in the window, or null when fewer than `windowSize` exist.
+ * @returns Fraction of winning trades in the window with its cohort, or a typed
+ *          unavailable result when fewer than `windowSize` trades exist.
  * @throws When `windowSize` is not a positive integer or any input is non-finite.
  */
 function calculateRollingHitRate(tradePnls, windowSize) {
     assertWindowSize("calculateRollingHitRate", windowSize);
-    if (tradePnls.length < windowSize)
-        return null;
+    if (tradePnls.length < windowSize) {
+        return insufficientWindow("calculateRollingHitRate", tradePnls.length, windowSize);
+    }
     assertFiniteArray("calculateRollingHitRate", tradePnls);
     const slice = tradePnls.slice(-windowSize);
     const wins = slice.filter((p) => p > 0).length;
-    return wins / windowSize;
+    return availableStatistic(wins / windowSize, sampleCohort(windowSize, windowSize));
 }
 /**
  * Rolling profit factor: sum(wins) / |sum(losses)| over the most-recent `windowSize` trades.
  *
  * Edge cases:
- * - no losses and at least one win → +Infinity
- * - no wins and no losses (all zeros) → 0
- * - fewer than windowSize trades → null
+ * - no losses and at least one win → +Infinity (an unbounded but real ratio)
+ * - no wins and no losses (all zeros) → unavailable: `0 / 0` is undefined, and a
+ *   window of breakeven trades has no profit factor rather than a profit factor
+ *   of zero
+ * - fewer than windowSize trades → unavailable
  *
  * @param tradePnls - Array of per-trade realised P&L values.
  * @param windowSize - Number of most-recent trades to include. Must be a positive integer.
- * @returns Profit factor for the rolling window, or null when fewer than `windowSize` exist.
+ * @returns Profit factor for the rolling window with its cohort, or a typed
+ *          unavailable result.
  * @throws When `windowSize` is not a positive integer or any input is non-finite.
  */
 function calculateRollingProfitFactor(tradePnls, windowSize) {
     assertWindowSize("calculateRollingProfitFactor", windowSize);
-    if (tradePnls.length < windowSize)
-        return null;
+    if (tradePnls.length < windowSize) {
+        return insufficientWindow("calculateRollingProfitFactor", tradePnls.length, windowSize);
+    }
     assertFiniteArray("calculateRollingProfitFactor", tradePnls);
+    const cohort = sampleCohort(windowSize, windowSize);
     const slice = tradePnls.slice(-windowSize);
     const wins = slice.filter((p) => p > 0).reduce((a, b) => a + b, 0);
     const losses = slice.filter((p) => p < 0).reduce((a, b) => a + Math.abs(b), 0);
-    if (losses === 0)
-        return wins > 0 ? Number.POSITIVE_INFINITY : 0;
-    return wins / losses;
+    if (losses === 0) {
+        if (wins > 0) {
+            return availableStatistic(Number.POSITIVE_INFINITY, cohort);
+        }
+        return unavailableStatistic("degenerate_population", `calculateRollingProfitFactor: window of ${windowSize} contains neither wins nor losses; the ratio is undefined`, cohort);
+    }
+    return availableStatistic(wins / losses, cohort);
 }
 /**
  * Rolling Sortino: delegate to `calculateSortino` over the most-recent `windowSize` returns.
@@ -22268,34 +22413,58 @@ function calculateRollingProfitFactor(tradePnls, windowSize) {
  * @param tradeReturns - Array of per-trade return values.
  * @param windowSize - Number of most-recent trades to include. Must be a positive integer.
  * @param riskFreeRate - Risk-free rate to subtract from returns (default 0).
- * @returns Sortino ratio for the rolling window, or null when fewer than `windowSize` exist.
+ * @returns Sortino ratio for the rolling window with its cohort, or a typed
+ *          unavailable result.
  * @throws When `windowSize` is not a positive integer or any input is non-finite.
  */
 function calculateRollingSortino(tradeReturns, windowSize, riskFreeRate = 0) {
     assertWindowSize("calculateRollingSortino", windowSize);
-    if (tradeReturns.length < windowSize)
-        return null;
+    if (tradeReturns.length < windowSize) {
+        return insufficientWindow("calculateRollingSortino", tradeReturns.length, windowSize);
+    }
     assertFiniteArray("calculateRollingSortino", tradeReturns);
-    return calculateSortino(tradeReturns.slice(-windowSize), riskFreeRate);
+    const cohort = sampleCohort(windowSize, windowSize);
+    const sortino = calculateSortino(tradeReturns.slice(-windowSize), riskFreeRate);
+    if (sortino === null) {
+        // `calculateSortino` returns null only for a window it cannot form a
+        // dispersion over — fewer than two samples. That is a property of the
+        // window, so it is reported as one rather than as a ratio of zero.
+        return unavailableStatistic("insufficient_samples", `calculateRollingSortino: window of ${windowSize} cannot support a dispersion estimate`, cohort);
+    }
+    return availableStatistic(sortino, cohort);
 }
 /**
  * Z-score of live-expectancy vs backtest-expectancy, scaled by the backtest stddev.
  * Positive Z = live outperforming; negative Z = live underperforming.
  *
- * @param liveExpectancy - Mean P&L per trade in the live window.
+ * The live expectancy is taken as a {@link SampleStatistic} rather than a bare
+ * number so the z-score inherits the cohort it was actually derived from. A
+ * z-score is a statement about how surprising a sample mean is, and how
+ * surprising it is depends entirely on how many trades produced it — quoting
+ * the z alone is the exact substitution this type exists to block. An
+ * unavailable live expectancy yields an unavailable z, because there is no
+ * mean to compare.
+ *
+ * @param liveExpectancy - Mean P&L per trade in the live window, with its cohort.
  * @param backtestExpectancy - Mean P&L per trade from the calibration backtest.
  * @param backtestStddev - Stddev of per-trade P&L in the backtest. Must be > 0.
- * @returns Z-score measuring divergence between live and backtest performance.
- * @throws When any input is non-finite or `backtestStddev` is not positive.
+ * @returns Z-score measuring live-vs-backtest divergence, carrying the live cohort.
+ * @throws When the backtest inputs are non-finite or `backtestStddev` is not positive.
  */
 function calculateBacktestDivergenceZ(liveExpectancy, backtestExpectancy, backtestStddev) {
-    if (!Number.isFinite(liveExpectancy) || !Number.isFinite(backtestExpectancy) || !Number.isFinite(backtestStddev)) {
+    if (!Number.isFinite(backtestExpectancy) || !Number.isFinite(backtestStddev)) {
         throw new Error("calculateBacktestDivergenceZ: inputs must be finite numbers");
     }
     if (backtestStddev <= 0) {
         throw new Error("calculateBacktestDivergenceZ: stddev must be > 0");
     }
-    return (liveExpectancy - backtestExpectancy) / backtestStddev;
+    if (!liveExpectancy.available) {
+        return unavailableStatistic(liveExpectancy.reason, `calculateBacktestDivergenceZ: live expectancy unavailable (${liveExpectancy.detail})`, sampleCohort(liveExpectancy.requestedCount, liveExpectancy.sampleCount));
+    }
+    if (!Number.isFinite(liveExpectancy.value)) {
+        throw new Error("calculateBacktestDivergenceZ: inputs must be finite numbers");
+    }
+    return availableStatistic((liveExpectancy.value - backtestExpectancy) / backtestStddev, sampleCohort(liveExpectancy.requestedCount, liveExpectancy.sampleCount));
 }
 
 var strategyNs = /*#__PURE__*/Object.freeze({
@@ -80210,6 +80379,7 @@ exports.alpaca = alpaca;
 exports.analyzeBars = analyzeBars;
 exports.approximateImpliedVolatility = approximateImpliedVolatility;
 exports.atr = atrNs;
+exports.availableStatistic = availableStatistic;
 exports.bracketOrders = bracketOrders;
 exports.buildOCCSymbol = buildOCCSymbol;
 exports.buildOptionSymbol = buildOptionSymbol;
@@ -80383,6 +80553,7 @@ exports.hasSufficientVolume = hasSufficientVolume;
 exports.httpAgent = httpAgent;
 exports.httpsAgent = httpsAgent;
 exports.isAlpacaBrokerCredentials = isAlpacaBrokerCredentials;
+exports.isAvailable = isAvailable;
 exports.isContractTradable = isContractTradable;
 exports.isCryptoPair = isCryptoPair;
 exports.isExpiringWithin = isExpiringWithin;
@@ -80429,6 +80600,7 @@ exports.routeKeyFor = routeKeyFor;
 exports.routeSupports = routeSupports;
 exports.routeTable = routeTable;
 exports.safeValidateResponse = safeValidateResponse;
+exports.sampleCohort = sampleCohort;
 exports.searchNews = searchNews;
 exports.sellAllCrypto = sellAllCrypto;
 exports.sellCryptoNotional = sellCryptoNotional;
@@ -80442,6 +80614,7 @@ exports.strategy = strategyNs;
 exports.sumUsage = sumUsage;
 exports.tradingPolicy = index;
 exports.trailingStops = trailingStops;
+exports.unavailableStatistic = unavailableStatistic;
 exports.updateAccountConfiguration = updateAccountConfiguration;
 exports.updateTrailingStop = updateTrailingStop;
 exports.validateAlpacaCredentials = validateAlpacaCredentials;