@adaptic/utils 0.0.1030 → 0.0.1032

package/dist/types/schemas/massive-schemas.d.ts

@@ -3,37 +3,46 @@
  * Validates API responses against expected shapes to catch breaking API changes early.
  */
 import { z } from "zod";
-/** Schema for raw Massive price data (as returned from aggregates endpoint) */
+/**
+ * Raw bar as the aggregates endpoints return it.
+ *
+ * Only OHLC, volume and timestamp are guaranteed. `T` names the ticker and is
+ * carried by the grouped-daily endpoint, which returns many symbols in one
+ * payload, but not by single-ticker aggregates, where the symbol is on the
+ * envelope instead. `vw` and `n` are derived statistics the vendor omits for
+ * bars with too little activity to compute them. Requiring any of the three
+ * would reject payloads that are entirely valid.
+ */
 export declare const RawMassivePriceDataSchema: z.ZodObject<{
-    T: z.ZodString;
+    T: z.ZodOptional<z.ZodString>;
     c: z.ZodNumber;
     h: z.ZodNumber;
     l: z.ZodNumber;
-    n: z.ZodNumber;
+    n: z.ZodOptional<z.ZodNumber>;
     o: z.ZodNumber;
     t: z.ZodNumber;
     v: z.ZodNumber;
-    vw: z.ZodNumber;
+    vw: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     t: number;
-    T: string;
     o: number;
     h: number;
     l: number;
     c: number;
     v: number;
-    vw: number;
-    n: number;
+    T?: string | undefined;
+    vw?: number | undefined;
+    n?: number | undefined;
 }, {
     t: number;
-    T: string;
     o: number;
     h: number;
     l: number;
     c: number;
     v: number;
-    vw: number;
-    n: number;
+    T?: string | undefined;
+    vw?: number | undefined;
+    n?: number | undefined;
 }>;
 /** Schema for Massive ticker info response */
 export declare const MassiveTickerInfoSchema: z.ZodObject<{
@@ -43,7 +52,7 @@ export declare const MassiveTickerInfoSchema: z.ZodObject<{
     description: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     locale: z.ZodString;
     market: z.ZodEnum<["stocks", "crypto", "indices", "fx", "otc"]>;
-    market_cap: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    market_cap: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     name: z.ZodString;
     primary_exchange: z.ZodString;
     share_class_shares_outstanding: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -57,10 +66,10 @@ export declare const MassiveTickerInfoSchema: z.ZodObject<{
     description: string;
     currency_name: string;
     locale: string;
-    market_cap: number;
     primary_exchange: string;
     ticker: string;
     delisted_utc?: string | undefined;
+    market_cap?: number | null | undefined;
     share_class_shares_outstanding?: number | null | undefined;
 }, {
     type: string;
@@ -73,7 +82,7 @@ export declare const MassiveTickerInfoSchema: z.ZodObject<{
     ticker: string;
     description?: string | undefined;
     delisted_utc?: string | undefined;
-    market_cap?: number | undefined;
+    market_cap?: number | null | undefined;
     share_class_shares_outstanding?: number | null | undefined;
 }>;
 /** Schema for the wrapper around ticker details API response */
@@ -85,7 +94,7 @@ export declare const MassiveTickerDetailsResponseSchema: z.ZodObject<{
         description: z.ZodDefault<z.ZodOptional<z.ZodString>>;
         locale: z.ZodString;
         market: z.ZodEnum<["stocks", "crypto", "indices", "fx", "otc"]>;
-        market_cap: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        market_cap: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         name: z.ZodString;
         primary_exchange: z.ZodString;
         share_class_shares_outstanding: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -99,10 +108,10 @@ export declare const MassiveTickerDetailsResponseSchema: z.ZodObject<{
         description: string;
         currency_name: string;
         locale: string;
-        market_cap: number;
         primary_exchange: string;
         ticker: string;
         delisted_utc?: string | undefined;
+        market_cap?: number | null | undefined;
         share_class_shares_outstanding?: number | null | undefined;
     }, {
         type: string;
@@ -115,7 +124,7 @@ export declare const MassiveTickerDetailsResponseSchema: z.ZodObject<{
         ticker: string;
         description?: string | undefined;
         delisted_utc?: string | undefined;
-        market_cap?: number | undefined;
+        market_cap?: number | null | undefined;
         share_class_shares_outstanding?: number | null | undefined;
     }>;
     status: z.ZodString;
@@ -130,10 +139,10 @@ export declare const MassiveTickerDetailsResponseSchema: z.ZodObject<{
         description: string;
         currency_name: string;
         locale: string;
-        market_cap: number;
         primary_exchange: string;
         ticker: string;
         delisted_utc?: string | undefined;
+        market_cap?: number | null | undefined;
         share_class_shares_outstanding?: number | null | undefined;
     };
     request_id: string;
@@ -150,7 +159,7 @@ export declare const MassiveTickerDetailsResponseSchema: z.ZodObject<{
         ticker: string;
         description?: string | undefined;
         delisted_utc?: string | undefined;
-        market_cap?: number | undefined;
+        market_cap?: number | null | undefined;
         share_class_shares_outstanding?: number | null | undefined;
     };
     request_id: string;
@@ -163,68 +172,68 @@ export declare const MassiveGroupedDailyResponseSchema: z.ZodObject<{
     resultsCount: z.ZodNumber;
     status: z.ZodString;
     results: z.ZodArray<z.ZodObject<{
-        T: z.ZodString;
+        T: z.ZodOptional<z.ZodString>;
         c: z.ZodNumber;
         h: z.ZodNumber;
         l: z.ZodNumber;
-        n: z.ZodNumber;
+        n: z.ZodOptional<z.ZodNumber>;
         o: z.ZodNumber;
         t: z.ZodNumber;
         v: z.ZodNumber;
-        vw: z.ZodNumber;
+        vw: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         t: number;
-        T: string;
         o: number;
         h: number;
         l: number;
         c: number;
         v: number;
-        vw: number;
-        n: number;
+        T?: string | undefined;
+        vw?: number | undefined;
+        n?: number | undefined;
     }, {
         t: number;
-        T: string;
         o: number;
         h: number;
         l: number;
         c: number;
         v: number;
-        vw: number;
-        n: number;
+        T?: string | undefined;
+        vw?: number | undefined;
+        n?: number | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     status: string;
     results: {
         t: number;
-        T: string;
         o: number;
         h: number;
         l: number;
         c: number;
         v: number;
-        vw: number;
-        n: number;
+        T?: string | undefined;
+        vw?: number | undefined;
+        n?: number | undefined;
     }[];
-    adjusted: boolean;
     request_id: string;
+    adjusted: boolean;
     queryCount: number;
     resultsCount: number;
 }, {
     status: string;
     results: {
         t: number;
-        T: string;
         o: number;
         h: number;
         l: number;
         c: number;
         v: number;
-        vw: number;
-        n: number;
+        T?: string | undefined;
+        vw?: number | undefined;
+        n?: number | undefined;
     }[];
-    adjusted: boolean;
     request_id: string;
+    adjusted: boolean;
     queryCount: number;
     resultsCount: number;
 }>;
@@ -279,26 +288,26 @@ export declare const MassiveTradeSchema: z.ZodObject<{
     trf_timestamp: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     id: string;
-    size: number;
-    price: number;
-    exchange: number;
     conditions: number[];
+    exchange: number;
     participant_timestamp: number;
+    price: number;
     sequence_number: number;
     sip_timestamp: number;
+    size: number;
     correction?: number | undefined;
     tape?: number | undefined;
     trf_id?: number | undefined;
     trf_timestamp?: number | undefined;
 }, {
     id: string;
-    size: number;
-    price: number;
-    exchange: number;
     conditions: number[];
+    exchange: number;
     participant_timestamp: number;
+    price: number;
     sequence_number: number;
     sip_timestamp: number;
+    size: number;
     correction?: number | undefined;
     tape?: number | undefined;
     trf_id?: number | undefined;
@@ -324,26 +333,26 @@ export declare const MassiveTradesResponseSchema: z.ZodObject<{
         trf_timestamp: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         id: string;
-        size: number;
-        price: number;
-        exchange: number;
         conditions: number[];
+        exchange: number;
         participant_timestamp: number;
+        price: number;
         sequence_number: number;
         sip_timestamp: number;
+        size: number;
         correction?: number | undefined;
         tape?: number | undefined;
         trf_id?: number | undefined;
         trf_timestamp?: number | undefined;
     }, {
         id: string;
-        size: number;
-        price: number;
-        exchange: number;
         conditions: number[];
+        exchange: number;
         participant_timestamp: number;
+        price: number;
         sequence_number: number;
         sip_timestamp: number;
+        size: number;
         correction?: number | undefined;
         tape?: number | undefined;
         trf_id?: number | undefined;
@@ -353,13 +362,13 @@ export declare const MassiveTradesResponseSchema: z.ZodObject<{
     status: "OK";
     results: {
         id: string;
-        size: number;
-        price: number;
-        exchange: number;
         conditions: number[];
+        exchange: number;
         participant_timestamp: number;
+        price: number;
         sequence_number: number;
         sip_timestamp: number;
+        size: number;
         correction?: number | undefined;
         tape?: number | undefined;
         trf_id?: number | undefined;
@@ -371,13 +380,13 @@ export declare const MassiveTradesResponseSchema: z.ZodObject<{
     status: "OK";
     results: {
         id: string;
-        size: number;
-        price: number;
-        exchange: number;
         conditions: number[];
+        exchange: number;
         participant_timestamp: number;
+        price: number;
         sequence_number: number;
         sip_timestamp: number;
+        size: number;
         correction?: number | undefined;
         tape?: number | undefined;
         trf_id?: number | undefined;
@@ -405,12 +414,12 @@ export declare const MassiveLastTradeResponseSchema: z.ZodObject<{
         trf_timestamp: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         id: string;
-        size: number;
-        price: number;
         exchange: number;
         participant_timestamp: number;
+        price: number;
         sequence_number: number;
         sip_timestamp: number;
+        size: number;
         conditions?: number[] | undefined;
         correction?: number | undefined;
         tape?: number | undefined;
@@ -418,12 +427,12 @@ export declare const MassiveLastTradeResponseSchema: z.ZodObject<{
         trf_timestamp?: number | undefined;
     }, {
         id: string;
-        size: number;
-        price: number;
         exchange: number;
         participant_timestamp: number;
+        price: number;
         sequence_number: number;
         sip_timestamp: number;
+        size: number;
         conditions?: number[] | undefined;
         correction?: number | undefined;
         tape?: number | undefined;
@@ -434,12 +443,12 @@ export declare const MassiveLastTradeResponseSchema: z.ZodObject<{
     status: string;
     results: {
         id: string;
-        size: number;
-        price: number;
         exchange: number;
         participant_timestamp: number;
+        price: number;
         sequence_number: number;
         sip_timestamp: number;
+        size: number;
         conditions?: number[] | undefined;
         correction?: number | undefined;
         tape?: number | undefined;
@@ -451,12 +460,12 @@ export declare const MassiveLastTradeResponseSchema: z.ZodObject<{
     status: string;
     results: {
         id: string;
-        size: number;
-        price: number;
         exchange: number;
         participant_timestamp: number;
+        price: number;
         sequence_number: number;
         sip_timestamp: number;
+        size: number;
         conditions?: number[] | undefined;
         correction?: number | undefined;
         tape?: number | undefined;
@@ -466,79 +475,88 @@ export declare const MassiveLastTradeResponseSchema: z.ZodObject<{
     request_id: string;
 }>;
 /** Schema for Massive aggregates (bars) response */
+/**
+ * Single-ticker aggregates envelope.
+ *
+ * Only `status` and the bars are load-bearing: the aggregates path reads
+ * neither `request_id` nor the counts, and requiring a field no consumer
+ * depends on would report drift that cannot affect anything — noise that
+ * teaches an operator to ignore the signal. The grouped-daily schema does
+ * require `request_id`, because that path copies it into its own result.
+ */
 export declare const MassiveAggregatesResponseSchema: z.ZodObject<{
     adjusted: z.ZodOptional<z.ZodBoolean>;
     next_url: z.ZodOptional<z.ZodString>;
     queryCount: z.ZodOptional<z.ZodNumber>;
-    request_id: z.ZodString;
+    request_id: z.ZodOptional<z.ZodString>;
     results: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        T: z.ZodString;
+        T: z.ZodOptional<z.ZodString>;
         c: z.ZodNumber;
         h: z.ZodNumber;
         l: z.ZodNumber;
-        n: z.ZodNumber;
+        n: z.ZodOptional<z.ZodNumber>;
         o: z.ZodNumber;
         t: z.ZodNumber;
         v: z.ZodNumber;
-        vw: z.ZodNumber;
+        vw: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         t: number;
-        T: string;
         o: number;
         h: number;
         l: number;
         c: number;
         v: number;
-        vw: number;
-        n: number;
+        T?: string | undefined;
+        vw?: number | undefined;
+        n?: number | undefined;
     }, {
         t: number;
-        T: string;
         o: number;
         h: number;
         l: number;
         c: number;
         v: number;
-        vw: number;
-        n: number;
+        T?: string | undefined;
+        vw?: number | undefined;
+        n?: number | undefined;
     }>, "many">>;
     resultsCount: z.ZodOptional<z.ZodNumber>;
     status: z.ZodString;
     ticker: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     status: string;
-    request_id: string;
     ticker?: string | undefined;
     results?: {
         t: number;
-        T: string;
         o: number;
         h: number;
         l: number;
         c: number;
         v: number;
-        vw: number;
-        n: number;
+        T?: string | undefined;
+        vw?: number | undefined;
+        n?: number | undefined;
     }[] | undefined;
+    request_id?: string | undefined;
     adjusted?: boolean | undefined;
     queryCount?: number | undefined;
     resultsCount?: number | undefined;
     next_url?: string | undefined;
 }, {
     status: string;
-    request_id: string;
     ticker?: string | undefined;
     results?: {
         t: number;
-        T: string;
         o: number;
         h: number;
         l: number;
         c: number;
         v: number;
-        vw: number;
-        n: number;
+        T?: string | undefined;
+        vw?: number | undefined;
+        n?: number | undefined;
     }[] | undefined;
+    request_id?: string | undefined;
     adjusted?: boolean | undefined;
     queryCount?: number | undefined;
     resultsCount?: number | undefined;

package/dist/types/schemas/massive-schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"massive-schemas.d.ts","sourceRoot":"","sources":["../../../src/schemas/massive-schemas.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAUpC,CAAC;AAIH,8CAA8C;AAC9C,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAalC,CAAC;AAEH,gEAAgE;AAChE,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAI7C,CAAC;AAIH,gDAAgD;AAChD,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAO5C,CAAC;AAIH,mDAAmD;AACnD,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWtC,CAAC;AAIH,wCAAwC;AACxC,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAa7B,CAAC;AAEH,yCAAyC;AACzC,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKtC,CAAC;AAIH,mFAAmF;AACnF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqBzC,CAAC;AAIH,oDAAoD;AACpD,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS1C,CAAC;AAIH,wCAAwC;AACxC,eAAO,MAAM,0BAA0B;;;;;;;;;;;;EAIrC,CAAC"}
+{"version":3,"file":"massive-schemas.d.ts","sourceRoot":"","sources":["../../../src/schemas/massive-schemas.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAUpC,CAAC;AAIH,8CAA8C;AAC9C,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAelC,CAAC;AAEH,gEAAgE;AAChE,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAI7C,CAAC;AAIH,gDAAgD;AAChD,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAO5C,CAAC;AAIH,mDAAmD;AACnD,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWtC,CAAC;AAIH,wCAAwC;AACxC,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAa7B,CAAC;AAEH,yCAAyC;AACzC,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKtC,CAAC;AAIH,mFAAmF;AACnF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqBzC,CAAC;AAIH,oDAAoD;AACpD;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS1C,CAAC;AAIH,wCAAwC;AACxC,eAAO,MAAM,0BAA0B;;;;;;;;;;;;EAIrC,CAAC"}

package/dist/types/strategy-metrics.d.ts

@@ -4,62 +4,84 @@
  * 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.
  */
+import { type SampleStatistic } from "./sample-statistic";
 /**
  * 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.
  */
-export declare function calculateRollingExpectancy(tradePnls: number[], windowSize: number): number | null;
+export declare function calculateRollingExpectancy(tradePnls: number[], windowSize: number): SampleStatistic<number>;
 /**
  * Rolling hit-rate: fraction of strictly-positive P&L trades in the most-recent
  * `windowSize` trades. Zero P&L counts as non-win.
  *
  * @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.
  */
-export declare function calculateRollingHitRate(tradePnls: number[], windowSize: number): number | null;
+export declare function calculateRollingHitRate(tradePnls: number[], windowSize: number): SampleStatistic<number>;
 /**
  * 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.
  */
-export declare function calculateRollingProfitFactor(tradePnls: number[], windowSize: number): number | null;
+export declare function calculateRollingProfitFactor(tradePnls: number[], windowSize: number): SampleStatistic<number>;
 /**
  * Rolling Sortino: delegate to `calculateSortino` over the most-recent `windowSize` returns.
  *
  * @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.
  */
-export declare function calculateRollingSortino(tradeReturns: number[], windowSize: number, riskFreeRate?: number): number | null;
+export declare function calculateRollingSortino(tradeReturns: number[], windowSize: number, riskFreeRate?: number): SampleStatistic<number>;
 /**
  * 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.
  */
-export declare function calculateBacktestDivergenceZ(liveExpectancy: number, backtestExpectancy: number, backtestStddev: number): number;
+export declare function calculateBacktestDivergenceZ(liveExpectancy: SampleStatistic<number>, backtestExpectancy: number, backtestStddev: number): SampleStatistic<number>;
 //# sourceMappingURL=strategy-metrics.d.ts.map

package/dist/types/strategy-metrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strategy-metrics.d.ts","sourceRoot":"","sources":["../../src/strategy-metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAkBH;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EAAE,EACnB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAMf;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EAAE,EACnB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAOf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,MAAM,EAAE,EACnB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CASf;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EAAE,EACtB,UAAU,EAAE,MAAM,EAClB,YAAY,SAAI,GACf,MAAM,GAAG,IAAI,CAKf;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,cAAc,EAAE,MAAM,EACtB,kBAAkB,EAAE,MAAM,EAC1B,cAAc,EAAE,MAAM,GACrB,MAAM,CAQR"}
+{"version":3,"file":"strategy-metrics.d.ts","sourceRoot":"","sources":["../../src/strategy-metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAwC5B;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EAAE,EACnB,UAAU,EAAE,MAAM,GACjB,eAAe,CAAC,MAAM,CAAC,CAezB;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EAAE,EACnB,UAAU,EAAE,MAAM,GACjB,eAAe,CAAC,MAAM,CAAC,CAgBzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,MAAM,EAAE,EACnB,UAAU,EAAE,MAAM,GACjB,eAAe,CAAC,MAAM,CAAC,CAyBzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EAAE,EACtB,UAAU,EAAE,MAAM,EAClB,YAAY,SAAI,GACf,eAAe,CAAC,MAAM,CAAC,CAuBzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,4BAA4B,CAC1C,cAAc,EAAE,eAAe,CAAC,MAAM,CAAC,EACvC,kBAAkB,EAAE,MAAM,EAC1B,cAAc,EAAE,MAAM,GACrB,eAAe,CAAC,MAAM,CAAC,CAqBzB"}

package/dist/types/types/alpaca-types.d.ts

@@ -1,6 +1,7 @@
 import { ApolloClientType, NormalizedCacheObject } from "@adaptic/backend";
 import { types } from "@adaptic/backend";
 import type Alpaca from "@alpacahq/alpaca-trade-api";
+import type { SampleStatistic } from "../sample-statistic";
 /** Config parameter type for Alpaca SDK market data methods (getLatestQuote, etc.) */
 export type AlpacaSDKConfig = NonNullable<Parameters<Alpaca["getLatestQuote"]>[1]>;
 /** Parameter type for Alpaca SDK getOrders method */
@@ -101,15 +102,38 @@ export interface BenchmarkBar {
     c: number;
 }
 /**
- * Result of the beta calculation.
+ * The components of a beta measurement, all derived from the same paired
+ * observations.
+ *
+ * They travel together because they are one measurement, not five: a
+ * `covariance` reported next to a `variance` taken over a different set of
+ * rows is not a beta, it is two numbers that look like one.
  */
-export interface CalculateBetaResult {
+export interface BetaComponents {
+    /** Slope of portfolio returns on benchmark returns: `covariance / variance`. */
     beta: number;
+    /** Sample covariance of the paired returns (Bessel-corrected). */
     covariance: number;
+    /** Sample variance of the benchmark returns (Bessel-corrected). */
     variance: number;
+    /** Mean portfolio return over the surviving pairs. */
     averagePortfolioReturn: number;
+    /** Mean benchmark return over the surviving pairs. */
     averageBenchmarkReturn: number;
 }
+/**
+ * Result of the beta calculation, inseparable from the cohort it was measured
+ * on.
+ *
+ * Beta is a ratio of two second moments, so it is meaningless without the
+ * number of paired observations behind it and the fraction of the offered rows
+ * that survived pairing and finiteness filtering. Returning the components
+ * alone lets a caller read a beta computed from two usable rows out of nine
+ * hundred as though it were the whole series, and lets an uncomputable beta
+ * arrive as a `0` that reads as "no market exposure" — which is a measurement,
+ * and a consequential one, rather than the absence it actually is.
+ */
+export type CalculateBetaResult = SampleStatistic<BetaComponents>;
 /**
  * Represents a position in the portfolio.
  */
@@ -820,8 +844,19 @@ export interface OptionAccountActivity {
     price?: string;
     status: "executed";
 }
+/**
+ * Every order-lifecycle event the Alpaca trade-updates stream emits.
+ *
+ * Declared once here because two partial copies drift: the stream emits all of
+ * these names, and a union that omits some of them forces a cast at the point
+ * of receipt, which silently accepts any string and defeats the union's purpose.
+ * Terminal-rejection events (`rejected`, `order_cancel_rejected`,
+ * `order_replace_rejected`) matter most — a consumer that cannot name them
+ * cannot distinguish a refused order from one still working.
+ */
+export type AlpacaTradeUpdateEvent = "new" | "fill" | "partial_fill" | "canceled" | "expired" | "done_for_day" | "replaced" | "rejected" | "pending_new" | "pending_cancel" | "pending_replace" | "calculated" | "suspended" | "order_cancel_rejected" | "order_replace_rejected" | "stopped" | "accepted" | "accepted_for_bidding";
 export interface TradeUpdate {
-    event: "new" | "fill" | "partial_fill" | "canceled" | "expired" | "pending_new" | "pending_cancel" | "pending_replace" | "replaced" | "done_for_day";
+    event: AlpacaTradeUpdateEvent;
     price?: string;
     timestamp: string;
     qty?: string;