@adaptic/utils 0.0.1031 → 0.0.1033

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({
@@ -62339,13 +62508,18 @@ const DEFAULT_PAGINATION_DELAY_MS = 300;
  */
 const MAX_ORDERS_PER_REQUEST = 500;
 /**
- * Order statuses that are considered "open"
+ * Order statuses that are considered "open".
+ *
+ * `held` is included because a held conditional leg (a bracket's stop-loss,
+ * say) is a working order resting at the broker, returned by Alpaca's own
+ * `status=open` listing and cancelable like any other open order.
  */
 const OPEN_ORDER_STATUSES = [
     "new",
     "accepted",
     "pending_new",
     "accepted_for_bidding",
+    "held",
     "partially_filled",
 ];
 /**
@@ -62353,13 +62527,15 @@ const OPEN_ORDER_STATUSES = [
  */
 const FILLED_ORDER_STATUSES = ["filled"];
 /**
- * Order statuses that can still potentially be filled
+ * Order statuses that can still potentially be filled. A `held` leg fills once
+ * its parent fills or its trigger is met.
  */
 const FILLABLE_ORDER_STATUSES = [
     "new",
     "accepted",
     "pending_new",
     "accepted_for_bidding",
+    "held",
     "partially_filled",
 ];
 /**
@@ -72167,11 +72343,35 @@ class CircuitBreakerRegistry {
      * Register that an attempt is starting, so half-open probes stay bounded.
      *
      * @param routeKey The route's stable key.
-     * @returns void
+     * @returns Whether the attempt took a half-open probe slot. A caller holding
+     *   one must end the attempt with {@link onSuccess}, {@link onFailure} or
+     *   {@link onAttemptAbandoned}, or the slot is never returned.
      */
     onAttemptStart(routeKey) {
         if (this.stateOf(routeKey) === "half-open") {
             this.recordFor(routeKey).probesInFlight += 1;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Return a half-open probe slot whose attempt ended without a verdict.
+     *
+     * A probe that never tested the provider — refused by the client's own
+     * pacing guard, cancelled by its caller, or found to be the wrong leg for the
+     * request — says nothing about whether the route has recovered, so neither a
+     * success nor a failure is recorded. The slot must still come back. Without
+     * it the half-open route admits no further probe, no probe can ever close or
+     * re-open the breaker, and the route stays excluded for the life of the
+     * process while its traffic is quietly served by the next leg.
+     *
+     * @param routeKey The route's stable key.
+     * @returns void
+     */
+    onAttemptAbandoned(routeKey) {
+        const record = this.records.get(routeKey);
+        if (record !== undefined && record.probesInFlight > 0) {
+            record.probesInFlight -= 1;
         }
     }
     /**
@@ -72442,11 +72642,13 @@ var defaults$1 = {
 var providers$1 = {
 	anthropic: {
 		basis: "conservative-default",
+		scope: "model",
+		scope_source: "https://platform.claude.com/docs/en/api/rate-limits",
 		requests_per_minute: 120,
 		max_concurrent: 12,
 		acquire_timeout_ms: 15000,
 		source: null,
-		note: "Raised 2026-09-15 after the 4-concurrent ceiling was measured starving the live equity decision path: the alias chain reported 'exhausted its fallback chain' with every leg skipped by this guard (deepinfra primary+secondary and the anthropic incumbent), 173 of 473 signal-coordination calls failed (36.6%), and decisions were lost outright. Corroborating evidence at the time: ZERO 429s observed on any provider, the engine's own global fan-out gate permits 100 concurrent with 17 active, and 877 signal-analysis calls had been admitted to that gate. Concurrency and RPM are raised TOGETHER because they bind in series - lifting max_concurrent alone would only move the bottleneck to the token bucket. STILL conservative-default, NOT published: no provider console was read for these numbers, so they remain a deliberate under-estimate of an unknown ceiling. Transcribe the real tier limits (W3-07) and set basis to published."
+		note: "The unit is per model: the scope_source states 'Rate limits are applied separately for each model; therefore you can use different models up to their respective limits simultaneously', measured as requests, input tokens and output tokens per minute for each model class, with no concurrency ceiling. Each model therefore gets its own guard, so traffic on one model class (an Opus incumbent serving background aliases) cannot refuse calls to another (the Haiku incumbent of the hot-path alias). The NUMBERS stay conservative-default: the organisation's usage tier sets the real ceilings and is read only from the Claude Console rate-limits page, which has not been transcribed. The lowest standard tier listed at the source allows 1,000 requests per minute per model; organisations with limited history can start on an evaluation tier below that, which is why these values are held well under it. Transcribe the tier's limits (W3-07) and set basis to published."
 	},
 	openai: {
 		basis: "conservative-default",
@@ -72465,12 +72667,14 @@ var providers$1 = {
 		note: "Raised 2026-09-15 after the 4-concurrent ceiling was measured starving the live equity decision path: the alias chain reported 'exhausted its fallback chain' with every leg skipped by this guard (deepinfra primary+secondary and the anthropic incumbent), 173 of 473 signal-coordination calls failed (36.6%), and decisions were lost outright. Corroborating evidence at the time: ZERO 429s observed on any provider, the engine's own global fan-out gate permits 100 concurrent with 17 active, and 877 signal-analysis calls had been admitted to that gate. Concurrency and RPM are raised TOGETHER because they bind in series - lifting max_concurrent alone would only move the bottleneck to the token bucket. STILL conservative-default, NOT published: no provider console was read for these numbers, so they remain a deliberate under-estimate of an unknown ceiling. Transcribe the real tier limits (W3-07) and set basis to published."
 	},
 	deepinfra: {
-		basis: "conservative-default",
+		basis: "published",
+		scope: "model",
 		requests_per_minute: 240,
-		max_concurrent: 24,
+		requests_per_minute_basis: "conservative-default",
+		max_concurrent: 200,
 		acquire_timeout_ms: 15000,
-		source: null,
-		note: "Raised 2026-09-15 after the 4-concurrent ceiling was measured starving the live equity decision path: the alias chain reported 'exhausted its fallback chain' with every leg skipped by this guard (deepinfra primary+secondary and the anthropic incumbent), 173 of 473 signal-coordination calls failed (36.6%), and decisions were lost outright. Corroborating evidence at the time: ZERO 429s observed on any provider, the engine's own global fan-out gate permits 100 concurrent with 17 active, and 877 signal-analysis calls had been admitted to that gate. Concurrency and RPM are raised TOGETHER because they bind in series - lifting max_concurrent alone would only move the bottleneck to the token bucket. STILL conservative-default, NOT published: no provider console was read for these numbers, so they remain a deliberate under-estimate of an unknown ceiling. Transcribe the real tier limits (W3-07) and set basis to published."
+		source: "https://docs.deepinfra.com/account/rate-limits",
+		note: "Transcribed 2026-09-23 from the source, which states 'Every account has a default limit of 200 concurrent requests per model', that two models queried simultaneously allow 400 in total (200 per model), and that 'The rate limit is on concurrent requests, not per-minute volume.' Concurrency is therefore the bound DeepInfra enforces, and it is enforced per MODEL, so each model gets its own guard at 200. One guard shared by the whole account enforced a ceiling DeepInfra does not impose, and because an alias's primary and secondary are both served from this account, it refused the secondary exactly when the primary's queue was full. DeepInfra publishes no per-minute ceiling, so requests_per_minute is the client's own pacing backstop (requests_per_minute_basis: conservative-default), keyed per model like the bound DeepInfra does enforce. Exceeding the ceiling returns HTTP 429, and a very busy model can return 429 below it. The ceiling belongs to the account and this guard to one process, so every process calling the same model through the same account shares the 200."
 	},
 	fireworks: {
 		basis: "conservative-default",
@@ -72520,7 +72724,10 @@ var limitsConfig = {
  * provider's circuit breaker, fail over to a more expensive leg, and keep doing
  * so — converting a self-inflicted pacing problem into a permanent routing
  * change nobody chose. Pacing at the client is what keeps the breaker measuring
- * the provider rather than measuring us.
+ * the provider rather than measuring us. The same reasoning bounds the guard
+ * from the other side: a client held far BELOW the provider's ceiling refuses
+ * calls the provider would have served, and the chain answers those refusals by
+ * failing over — the same unchosen routing change, arrived at by under-driving.
  *
  * Two distinct bounds are applied because they fail differently. The rate bound
  * (requests per minute) protects the provider's published ceiling. The
@@ -72529,8 +72736,18 @@ var limitsConfig = {
  * every one of them blows its latency budget and the fan-out produces a hundred
  * timeouts instead of a queue.
  *
- * Limits live in `provider-limits.json`, not here. A rate limit discovered
- * during an incident should be correctable by config, not by a release.
+ * Each guard is keyed by the unit its provider enforces limits in. A provider
+ * that publishes its ceilings per model gets one independent guard per model.
+ * Sharing one guard across its models would enforce a ceiling the provider does
+ * not impose, and — when a chain's primary and secondary are served by the same
+ * provider — would refuse the secondary at exactly the moment the primary's
+ * queue is full, so the fallback that exists for that moment is never reached.
+ *
+ * Limits live in `provider-limits.json` rather than in code, each beside the
+ * source it was transcribed from, so a published ceiling and a conservative
+ * guess can never be mistaken for one another in review. The file is bundled
+ * at build time: changing a limit is a release of this package, not a runtime
+ * switch.
  *
  * @module llm/rate-guard
  */
@@ -72570,64 +72787,141 @@ class RateGuardTimeoutError extends Error {
     provider;
     /** Which of the two bounds the caller waited on. */
     bound;
+    /** The model whose guard refused the call, when the provider's limits apply per model. */
+    modelId;
+    /** Whether the caller stopped waiting before the guard's own wait budget ran out. */
+    abandoned;
     /**
      * @param provider The provider.
      * @param bound Which bound was binding.
-     * @param waitedMs How long the caller waited.
+     * @param waitedMs How long the caller was prepared to wait.
+     * @param detail The model, and whether the caller left before the budget ran out.
      */
-    constructor(provider, bound, waitedMs) {
-        super(`client-side ${bound} guard for provider "${provider}" did not admit the call within ${waitedMs} ms. ` +
+    constructor(provider, bound, waitedMs, detail = {}) {
+        const guard = detail.modelId === undefined
+            ? `client-side ${bound} guard for provider "${provider}"`
+            : `client-side ${bound} guard for provider "${provider}", model "${detail.modelId}",`;
+        const outcome = detail.abandoned === true
+            ? `was left by its caller before it could admit the call (wait budget ${waitedMs} ms)`
+            : `did not admit the call within ${waitedMs} ms`;
+        super(`${guard} ${outcome}. ` +
             "The provider was never contacted, so this says nothing about its health.");
         this.name = "RateGuardTimeoutError";
         this.provider = provider;
         this.bound = bound;
+        this.modelId = detail.modelId;
+        this.abandoned = detail.abandoned === true;
     }
 }
+/**
+ * The guard a call is held by.
+ *
+ * A call to a per-model provider that names no model shares one provider-wide
+ * guard held at the per-model ceiling. That is never looser than the limit of
+ * any single model it might reach, so the fallback errs toward pacing.
+ *
+ * @param provider The provider key.
+ * @param modelId The model the call is addressed to, if known.
+ * @returns The guard's identity.
+ */
+function guardIdentity(provider, modelId) {
+    const perModel = limitsFor(provider).scope === "model" && modelId !== undefined && modelId.length > 0;
+    return perModel
+        ? { key: `${provider}/${modelId}`, provider, modelId }
+        : { key: provider, provider, modelId: undefined };
+}
 /**
  * A counting semaphore bounding simultaneous in-flight calls.
  *
- * Written here rather than pulled from a dependency because it is fifteen lines
- * and because the waiting behaviour matters: a waiter that times out must be
- * removed from the queue, or a burst of abandoned callers permanently consumes
- * the permits that later callers need.
+ * Written here rather than pulled from a dependency because the waiting
+ * behaviour is the point. A waiter that times out must be removed from the
+ * queue, or a burst of abandoned callers permanently consumes the permits that
+ * later callers need. And a waiter whose caller has stopped waiting must leave
+ * at once: left queued, it holds its caller until the wait budget expires and
+ * is then handed a permit it can only waste.
  */
 class ConcurrencyGate {
     inFlight = 0;
     waiters = [];
     limit;
-    provider;
+    identity;
     /**
-     * @param provider The provider this gate guards.
+     * @param identity The guard this gate implements.
      * @param limit Maximum simultaneous in-flight calls.
      */
-    constructor(provider, limit) {
-        this.provider = provider;
+    constructor(identity, limit) {
+        this.identity = identity;
         this.limit = limit;
     }
     /**
      * Wait for a permit.
      *
      * @param timeoutMs How long the caller is willing to queue.
+     * @param signal The caller's cancellation; firing it takes the caller out of the queue.
      * @returns A release function the caller must invoke exactly once.
+     * @throws {RateGuardTimeoutError} When no permit was granted in time, or the caller stopped waiting.
      */
-    async acquire(timeoutMs) {
+    async acquire(timeoutMs, signal) {
+        if (signal?.aborted === true) {
+            // Nobody is waiting for this answer. Taking a permit for it would spend
+            // capacity a live caller needs on a call that can only be torn down.
+            throw this.refusal(timeoutMs, true);
+        }
         if (this.inFlight < this.limit) {
             this.inFlight += 1;
             return () => this.release();
         }
         await new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                const index = this.waiters.findIndex((waiter) => waiter.timer === timer);
-                if (index !== -1) {
-                    this.waiters.splice(index, 1);
+            /**
+             * Take this waiter out of the queue and refuse it. A waiter that `release`
+             * has already admitted is no longer queued; it now holds a permit, which
+             * its call returns, so there is nothing to undo here.
+             *
+             * @param abandoned Whether the caller left before the wait budget ran out.
+             * @returns void
+             */
+            const leave = (abandoned) => {
+                const index = this.waiters.indexOf(waiter);
+                if (index === -1) {
+                    return;
                 }
-                reject(new RateGuardTimeoutError(this.provider, "concurrency", timeoutMs));
+                this.waiters.splice(index, 1);
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                reject(this.refusal(timeoutMs, abandoned));
+            };
+            const onAbort = () => {
+                leave(true);
+            };
+            const timer = setTimeout(() => {
+                leave(false);
             }, timeoutMs);
-            this.waiters.push({ resolve, reject, timer });
+            const waiter = {
+                admit: () => {
+                    clearTimeout(timer);
+                    signal?.removeEventListener("abort", onAbort);
+                    resolve();
+                },
+            };
+            this.waiters.push(waiter);
+            signal?.addEventListener("abort", onAbort, { once: true });
         });
         this.inFlight += 1;
         return () => this.release();
     }
+    /**
+     * Build the refusal for a caller this gate did not admit.
+     *
+     * @param timeoutMs The wait budget the caller had.
+     * @param abandoned Whether the caller left before the budget ran out.
+     * @returns The error to raise.
+     */
+    refusal(timeoutMs, abandoned) {
+        return new RateGuardTimeoutError(this.identity.provider, "concurrency", timeoutMs, {
+            modelId: this.identity.modelId,
+            abandoned,
+        });
+    }
     /**
      * Return a permit and admit the next waiter.
      *
@@ -72637,8 +72931,7 @@ class ConcurrencyGate {
         this.inFlight -= 1;
         const next = this.waiters.shift();
         if (next !== undefined) {
-            clearTimeout(next.timer);
-            next.resolve();
+            next.admit();
         }
     }
     /**
@@ -72654,44 +72947,47 @@ class ConcurrencyGate {
         return this.waiters.length;
     }
 }
-/** Per-provider guards, created on first use and shared process-wide. */
+/** Guards, created on first use and shared process-wide, keyed by {@link GuardIdentity.key}. */
 const rateLimiters = new Map();
 const concurrencyGates = new Map();
+const guardIdentities = new Map();
 /**
- * The rate limiter for a provider.
+ * The rate limiter for a guard.
  *
  * Shared process-wide rather than per-call-site, because the provider's ceiling
  * applies to the process as a whole. Per-call-site limiters would each stay
  * under the ceiling while their sum sailed past it.
  *
- * @param provider The provider key.
+ * @param identity The guard.
  * @returns Its limiter.
  */
-function rateLimiterFor(provider) {
-    let limiter = rateLimiters.get(provider);
+function rateLimiterFor(identity) {
+    let limiter = rateLimiters.get(identity.key);
     if (limiter === undefined) {
-        const limits = limitsFor(provider);
+        const limits = limitsFor(identity.provider);
         limiter = new TokenBucketRateLimiter({
             maxTokens: limits.requests_per_minute,
             refillRate: limits.requests_per_minute / SECONDS_PER_MINUTE,
-            label: `llm:${provider}`,
+            label: `llm:${identity.key}`,
             timeoutMs: limits.acquire_timeout_ms,
         });
-        rateLimiters.set(provider, limiter);
+        rateLimiters.set(identity.key, limiter);
+        guardIdentities.set(identity.key, identity);
     }
     return limiter;
 }
 /**
- * The concurrency gate for a provider.
+ * The concurrency gate for a guard.
  *
- * @param provider The provider key.
+ * @param identity The guard.
  * @returns Its gate.
  */
-function concurrencyGateFor(provider) {
-    let gate = concurrencyGates.get(provider);
+function concurrencyGateFor(identity) {
+    let gate = concurrencyGates.get(identity.key);
     if (gate === undefined) {
-        gate = new ConcurrencyGate(provider, limitsFor(provider).max_concurrent);
-        concurrencyGates.set(provider, gate);
+        gate = new ConcurrencyGate(identity, limitsFor(identity.provider).max_concurrent);
+        concurrencyGates.set(identity.key, gate);
+        guardIdentities.set(identity.key, identity);
     }
     return gate;
 }
@@ -72713,21 +73009,26 @@ function concurrencyGateFor(provider) {
  * @param provider The provider key.
  * @param call The work to run once admitted.
  * @param maxWaitMs Ceiling on queue time; the configured guard timeout applies when lower.
+ * @param scope The model the call addresses, and the caller's cancellation.
  * @returns The call's result.
- * @throws {RateGuardTimeoutError} When neither bound admitted the call in time.
+ * @throws {RateGuardTimeoutError} When neither bound admitted the call in time,
+ *   or the caller stopped waiting first.
  */
-async function withProviderGuards(provider, call, maxWaitMs) {
+async function withProviderGuards(provider, call, maxWaitMs, scope = {}) {
     const limits = limitsFor(provider);
+    const identity = guardIdentity(provider, scope.modelId);
     const waitBudgetMs = maxWaitMs === undefined
         ? limits.acquire_timeout_ms
         : Math.min(maxWaitMs, limits.acquire_timeout_ms);
     try {
-        await rateLimiterFor(provider).acquire();
+        await rateLimiterFor(identity).acquire();
     }
     catch {
-        throw new RateGuardTimeoutError(provider, "rate", waitBudgetMs);
+        throw new RateGuardTimeoutError(provider, "rate", waitBudgetMs, {
+            modelId: identity.modelId,
+        });
     }
-    const release = await concurrencyGateFor(provider).acquire(waitBudgetMs);
+    const release = await concurrencyGateFor(identity).acquire(waitBudgetMs, scope.signal);
     try {
         return await call();
     }
@@ -72741,16 +73042,20 @@ async function withProviderGuards(provider, call, maxWaitMs) {
 /**
  * Inspect the guards currently in use.
  *
- * @returns A snapshot per provider that has been used, sorted by provider.
+ * @returns A snapshot per guard that has been used, sorted by guard key.
  */
 function guardSnapshots() {
-    const providers = new Set([...rateLimiters.keys(), ...concurrencyGates.keys()]);
-    return [...providers].sort().map((provider) => {
-        const limits = limitsFor(provider);
-        const limiter = rateLimiters.get(provider);
-        const gate = concurrencyGates.get(provider);
+    return [...guardIdentities.values()]
+        .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+        .map((identity) => {
+        const limits = limitsFor(identity.provider);
+        const limiter = rateLimiters.get(identity.key);
+        const gate = concurrencyGates.get(identity.key);
         return {
-            provider,
+            key: identity.key,
+            provider: identity.provider,
+            modelId: identity.modelId,
+            scope: limits.scope ?? "provider",
             basis: limits.basis,
             requestsPerMinute: limits.requests_per_minute,
             maxConcurrent: limits.max_concurrent,
@@ -72775,6 +73080,105 @@ function resetProviderGuards() {
     }
     rateLimiters.clear();
     concurrencyGates.clear();
+    guardIdentities.clear();
+}
+
+/**
+ * Interpretation of a model's answer to a structured (JSON) request.
+ *
+ * A JSON request is a promise about the answer's SHAPE, and providers keep it
+ * in different ways. An OpenAI-compatible host given `json_object` constrains
+ * its decoder, so its answer is bare JSON. A provider with no schema-less JSON
+ * mode — Anthropic, reached through the gateway, supports structured output
+ * only against a caller-supplied schema — receives nothing but the prompt's
+ * instructions for a `json` request, and a model following them commonly
+ * returns the object inside one markdown code fence. The fence is presentation,
+ * not content: the object inside it is the answer the model gave.
+ *
+ * So exactly ONE enclosing fence is removed before parsing, and nothing else is
+ * forgiven. Prose before or after the fence, two fenced blocks, a fence that
+ * never closes (a truncated answer), and a fence declaring another language all
+ * still fail. Each of those is an answer whose meaning a parser would have to
+ * guess, and a guessed object is a decision made on data no model produced.
+ *
+ * Content that is not fenced is parsed exactly as it always was: JSON cannot
+ * begin with a backtick, so every answer that parsed before this unwrapping
+ * existed takes the same path and yields the same value.
+ *
+ * @module llm/structured-content
+ */
+/**
+ * One markdown fence enclosing the whole answer: an opening line of three
+ * backticks, optionally labelled `json`, then the body, then three closing
+ * backticks, with nothing but whitespace outside them. The body is anchored at
+ * both ends, so an answer holding two fenced blocks captures the text between
+ * them and fails to parse instead of yielding either block.
+ */
+const SINGLE_ENCLOSING_JSON_FENCE = /^\s*```(?:json)?[ \t]*\r?\n([\s\S]*?)\r?\n?[ \t]*```\s*$/i;
+/**
+ * Thrown when a provider answered a structured request with content that does
+ * not parse.
+ *
+ * Carries the usage the provider billed for that answer. The tokens were spent
+ * whether or not the content parsed, and a chain that dropped them would report
+ * a failed attempt as free — understating spend by exactly the calls that went
+ * wrong.
+ */
+class LlmResponseFormatError extends Error {
+    /** The format the caller asked for. */
+    responseFormat;
+    /** What the provider billed for the answer that did not parse. */
+    usage;
+    /** Whether the answer sat inside one enclosing fence that was removed before parsing. */
+    fenced;
+    /**
+     * @param responseFormat The format the caller asked for.
+     * @param usage What the provider billed for the answer.
+     * @param fenced Whether one enclosing fence was removed before parsing.
+     * @param cause The parser's own complaint.
+     */
+    constructor(responseFormat, usage, fenced, cause) {
+        super(`LLM returned content that is not valid JSON for a ${responseFormat} request` +
+            (fenced ? " (inside one enclosing markdown fence)" : "") +
+            `: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = "LlmResponseFormatError";
+        this.responseFormat = responseFormat;
+        this.usage = usage;
+        this.fenced = fenced;
+    }
+}
+/**
+ * The body of the one markdown fence that encloses an answer, if exactly one does.
+ *
+ * @param text The model's answer.
+ * @returns The fenced body, or null when the answer is not wholly one fenced block.
+ */
+function unwrapSingleJsonFence(text) {
+    const match = SINGLE_ENCLOSING_JSON_FENCE.exec(text);
+    return match === null ? null : match[1];
+}
+/**
+ * Parse a model's answer to a structured request.
+ *
+ * A JSON format that does not parse is an error, not an empty object. Returning
+ * a default here would hand the caller a well-typed value that means nothing,
+ * and the failure would surface much later as a decision made on absent data.
+ *
+ * @param content The raw content of the model's message.
+ * @param responseFormat The structured format the caller asked for.
+ * @param usage What the provider billed for this answer, carried on failure.
+ * @returns The parsed value.
+ * @throws {LlmResponseFormatError} When the content is not JSON, fenced or not.
+ */
+function parseStructuredContent(content, responseFormat, usage) {
+    const text = typeof content === "string" ? content : "";
+    const fencedBody = unwrapSingleJsonFence(text);
+    try {
+        return JSON.parse(fencedBody ?? text);
+    }
+    catch (error) {
+        throw new LlmResponseFormatError(typeof responseFormat === "string" ? responseFormat : "json_schema", usage, fencedBody !== null, error);
+    }
 }
 
 /**
@@ -72911,7 +73315,9 @@ async function runLeg(leg, params, execution) {
         // The guards wrap the transport rather than the whole leg, so the per-leg
         // timeout above still bounds the total wait: a caller queued behind the
         // rate limiter is spending its budget just as surely as one waiting on the
-        // provider, and only one clock should govern both.
+        // provider, and only one clock should govern both. The leg's own signal is
+        // handed to the guard as well, so a leg whose budget or caller is gone
+        // leaves the queue at once instead of holding its place in it.
         return await withProviderGuards(leg.route.providerName, () => leg.transport.execute({
             route: leg.route,
             content: execution.content,
@@ -72921,7 +73327,7 @@ async function runLeg(leg, params, execution) {
             context: execution.context,
             signal: controller.signal,
             correlationId: execution.correlationId,
-        }), budgetMs);
+        }), budgetMs, { modelId: leg.route.modelId, signal: controller.signal });
     }
     finally {
         clearTimeout(timer);
@@ -73033,7 +73439,7 @@ async function executeChain(alias, execution) {
             continue;
         }
         const startedAt = now();
-        execution.breakers.onAttemptStart(route.routeKey);
+        const holdsProbe = execution.breakers.onAttemptStart(route.routeKey);
         try {
             const response = await runLeg(leg, leg.params, execution);
             execution.breakers.onSuccess(route.routeKey);
@@ -73056,6 +73462,15 @@ async function executeChain(alias, execution) {
             if (countsAgainstHealth) {
                 execution.breakers.onFailure(route.routeKey);
             }
+            else if (holdsProbe) {
+                // No verdict on the route's health, but the probe slot this attempt
+                // took must come back, or a half-open route admits no probe ever again.
+                execution.breakers.onAttemptAbandoned(route.routeKey);
+            }
+            // A provider that answered with unparseable content still billed for the
+            // answer; the spend belongs in the total whether or not a later leg serves.
+            const billed = error instanceof LlmResponseFormatError ? error.usage : undefined;
+            totalUsage = sumUsage(totalUsage, billed);
             const record = {
                 routeKey: route.routeKey,
                 role: route.role,
@@ -73064,6 +73479,7 @@ async function executeChain(alias, execution) {
                 outcome,
                 durationMs: now() - startedAt,
                 reason,
+                ...(billed === undefined ? {} : { usage: billed }),
             };
             attempts.push(record);
             execution.onAttempt?.(record);
@@ -74357,9 +74773,13 @@ function createGatewayTransport(config) {
             const payload = (await response.json());
             const choices = payload.choices;
             const message = choices?.[0]?.message;
+            // Usage is read before the content is interpreted. The provider billed for
+            // this answer whether or not it parses, and a parse failure that dropped
+            // the count would report the attempt as free.
+            const usage = readUsage(payload, request);
             return {
-                response: parseContent(message?.content, request.responseFormat),
-                usage: readUsage(payload, request),
+                response: interpretContent(message?.content, request.responseFormat, usage),
+                usage,
                 tool_calls: Array.isArray(message?.tool_calls)
                     ? message.tool_calls
                     : undefined,
@@ -74394,25 +74814,22 @@ function buildMessages(request) {
 /**
  * Interpret the model's content according to the requested format.
  *
- * A JSON format that does not parse is an error, not an empty object. Returning
- * a default here would hand the caller a well-typed value that means nothing,
- * and the failure would surface much later as a decision made on absent data.
+ * Text is returned as sent. A structured format is parsed under the strict
+ * single-fence rule of {@link parseStructuredContent}; a structured answer that
+ * does not parse is an error carrying what the provider billed for it, never an
+ * empty object.
  *
  * @param content The raw content.
  * @param responseFormat The format the caller asked for.
- * @returns The parsed value.
+ * @param usage What the provider billed for this answer.
+ * @returns The interpreted value.
+ * @throws {LlmResponseFormatError} When a structured answer does not parse.
  */
-function parseContent(content, responseFormat) {
-    const text = typeof content === "string" ? content : "";
+function interpretContent(content, responseFormat, usage) {
     if (responseFormat === "text") {
-        return text;
-    }
-    try {
-        return JSON.parse(text);
-    }
-    catch (error) {
-        throw new Error(`LLM returned content that is not valid JSON for a ${typeof responseFormat === "string" ? responseFormat : "json_schema"} request: ${error instanceof Error ? error.message : String(error)}`);
+        return (typeof content === "string" ? content : "");
     }
+    return parseStructuredContent(content, responseFormat, usage);
 }
 
 /**
@@ -78507,6 +78924,7 @@ const OrderStatusSchema = enumType([
     "accepted",
     "pending_new",
     "accepted_for_bidding",
+    "held",
     "stopped",
     "rejected",
     "suspended",
@@ -80163,6 +80581,7 @@ exports.GatewayUnreachableError = GatewayUnreachableError;
 exports.HttpClientError = HttpClientError;
 exports.HttpServerError = HttpServerError;
 exports.KEEP_ALIVE_DEFAULTS = KEEP_ALIVE_DEFAULTS;
+exports.LlmResponseFormatError = LlmResponseFormatError;
 exports.MARKET_DATA_API = MARKET_DATA_API;
 exports.MassiveAggregatesResponseSchema = MassiveAggregatesResponseSchema;
 exports.MassiveApiError = MassiveApiError;
@@ -80210,6 +80629,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 +80803,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 +80850,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 +80864,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;