@adaptic/utils 0.0.1031 → 0.0.1033

package/dist/types/llm/rate-guard.d.ts

@@ -8,7 +8,10 @@
  * 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
@@ -17,16 +20,51 @@
  * 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
  */
+/** Where a limit came from: a provider's documented ceiling, or a deliberate under-estimate of an unknown one. */
+export type ProviderLimitBasis = "published" | "conservative-default";
+/**
+ * The unit a provider enforces its limits in.
+ *
+ * `model` means each of the provider's models has its own ceilings, so the
+ * client keeps one guard per model; `provider` means one guard covers every
+ * model the provider serves.
+ */
+export type ProviderLimitScope = "provider" | "model";
 /** Limits for one provider. */
 export interface ProviderLimits {
     /** Whether these numbers were transcribed from a provider doc or chosen conservatively. */
-    readonly basis: "published" | "conservative-default";
+    readonly basis: ProviderLimitBasis;
+    /** The unit the provider enforces its limits in. Absent means `provider`. */
+    readonly scope?: ProviderLimitScope;
+    /**
+     * Where a per-model scope was read from, when the entry's numbers are not
+     * themselves published. The unit is a claim about the provider and carries
+     * the same burden of proof as a number.
+     */
+    readonly scope_source?: string | null;
     readonly requests_per_minute: number;
+    /**
+     * Provenance of `requests_per_minute` when it differs from `basis`. A provider
+     * can publish a concurrency ceiling and no per-minute ceiling at all; the
+     * per-minute number is then the client's own choice and must not borrow the
+     * published label of the bound that was transcribed.
+     */
+    readonly requests_per_minute_basis?: ProviderLimitBasis;
     readonly max_concurrent: number;
     readonly acquire_timeout_ms: number;
     /** Where a published limit was read from. Null while the basis is a conservative default. */
@@ -50,6 +88,28 @@ export declare function limitsInventory(): {
     provider: string;
     limits: ProviderLimits;
 }[];
+/** Which guard a call is held by, and how its caller can stop waiting. */
+export interface GuardCallScope {
+    /**
+     * The model the call is addressed to. Selects the guard for a provider whose
+     * limits apply per model; ignored for a provider whose limits apply per
+     * provider.
+     */
+    readonly modelId?: string;
+    /**
+     * The caller's cancellation. A caller that stops waiting leaves the queue at
+     * once rather than holding its place until its wait budget runs out, and a
+     * permit freed after it has gone goes to a caller that is still waiting.
+     */
+    readonly signal?: AbortSignal;
+}
+/** What a refusal says about the call it refused. */
+interface RefusalDetail {
+    /** The model whose guard refused the call, for a provider whose limits apply per model. */
+    readonly modelId?: string;
+    /** Whether the caller stopped waiting before the guard's own budget ran out. */
+    readonly abandoned?: boolean;
+}
 /**
  * Thrown when a caller could not acquire a slot within its budget.
  *
@@ -61,12 +121,17 @@ export declare class RateGuardTimeoutError extends Error {
     readonly provider: string;
     /** Which of the two bounds the caller waited on. */
     readonly bound: "rate" | "concurrency";
+    /** The model whose guard refused the call, when the provider's limits apply per model. */
+    readonly modelId: string | undefined;
+    /** Whether the caller stopped waiting before the guard's own wait budget ran out. */
+    readonly abandoned: boolean;
     /**
      * @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: string, bound: "rate" | "concurrency", waitedMs: number);
+    constructor(provider: string, bound: "rate" | "concurrency", waitedMs: number, detail?: RefusalDetail);
 }
 /**
  * Run a call under a provider's rate and concurrency guards.
@@ -86,13 +151,20 @@ export declare class RateGuardTimeoutError extends Error {
  * @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.
  */
-export declare function withProviderGuards<T>(provider: string, call: () => Promise<T>, maxWaitMs?: number): Promise<T>;
+export declare function withProviderGuards<T>(provider: string, call: () => Promise<T>, maxWaitMs?: number, scope?: GuardCallScope): Promise<T>;
 /** Observable guard state, for dashboards and tests. */
 export interface GuardSnapshot {
+    /** The guard's identity: the provider, or `provider/model` for a per-model guard. */
+    readonly key: string;
     readonly provider: string;
+    /** The model this guard covers, for a provider whose limits apply per model. */
+    readonly modelId: string | undefined;
+    readonly scope: ProviderLimitScope;
     readonly basis: ProviderLimits["basis"];
     readonly requestsPerMinute: number;
     readonly maxConcurrent: number;
@@ -104,7 +176,7 @@ export interface GuardSnapshot {
 /**
  * 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.
  */
 export declare function guardSnapshots(): GuardSnapshot[];
 /**
@@ -116,4 +188,5 @@ export declare function guardSnapshots(): GuardSnapshot[];
  * @returns void
  */
 export declare function resetProviderGuards(): void;
+export {};
 //# sourceMappingURL=rate-guard.d.ts.map

package/dist/types/llm/rate-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate-guard.d.ts","sourceRoot":"","sources":["../../../src/llm/rate-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAYH,+BAA+B;AAC/B,MAAM,WAAW,cAAc;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,sBAAsB,CAAC;IACrD,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAE1D;AAED,uFAAuF;AACvF,wBAAgB,eAAe,IAAI;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,EAAE,CAIhF;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,yDAAyD;IACzD,SAAgB,QAAQ,EAAE,MAAM,CAAC;IAEjC,oDAAoD;IACpD,SAAgB,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC;IAE9C;;;;OAIG;gBACgB,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE,QAAQ,EAAE,MAAM;CASrF;AAgID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAED,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,aAAa,EAAE,CAiBhD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAM1C"}
+{"version":3,"file":"rate-guard.d.ts","sourceRoot":"","sources":["../../../src/llm/rate-guard.ts"],"names":[],"mappings":"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"}

package/dist/types/llm/structured-content.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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
+ */
+import type { LlmResponseFormat, LlmUsageRecord } from "./types";
+/** A response format that promises structured content. */
+export type StructuredResponseFormat = Exclude<LlmResponseFormat, "text">;
+/**
+ * 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.
+ */
+export declare class LlmResponseFormatError extends Error {
+    /** The format the caller asked for. */
+    readonly responseFormat: "json" | "json_schema";
+    /** What the provider billed for the answer that did not parse. */
+    readonly usage: LlmUsageRecord;
+    /** Whether the answer sat inside one enclosing fence that was removed before parsing. */
+    readonly fenced: boolean;
+    /**
+     * @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: "json" | "json_schema", usage: LlmUsageRecord, fenced: boolean, cause: unknown);
+}
+/**
+ * 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.
+ */
+export declare function unwrapSingleJsonFence(text: string): string | null;
+/**
+ * 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.
+ */
+export declare function parseStructuredContent<T>(content: unknown, responseFormat: StructuredResponseFormat, usage: LlmUsageRecord): T;
+//# sourceMappingURL=structured-content.d.ts.map

package/dist/types/llm/structured-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-content.d.ts","sourceRoot":"","sources":["../../../src/llm/structured-content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEjE,0DAA0D;AAC1D,MAAM,MAAM,wBAAwB,GAAG,OAAO,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;AAW1E;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,uCAAuC;IACvC,SAAgB,cAAc,EAAE,MAAM,GAAG,aAAa,CAAC;IAEvD,kEAAkE;IAClE,SAAgB,KAAK,EAAE,cAAc,CAAC;IAEtC,yFAAyF;IACzF,SAAgB,MAAM,EAAE,OAAO,CAAC;IAEhC;;;;;OAKG;gBAED,cAAc,EAAE,MAAM,GAAG,aAAa,EACtC,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,OAAO;CAYjB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,wBAAwB,EACxC,KAAK,EAAE,cAAc,GACpB,CAAC,CAaH"}

package/dist/types/llm/transports/gateway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../../../src/llm/transports/gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EAGpB,MAAM,UAAU,CAAC;AAQlB,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,MAAM,CAAC;CACjE;AAED;;;;;;;;GAQG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD;;;OAGG;gBACgB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAMnD;AAED,4DAA4D;AAC5D,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,uBAAuB;IACvB,SAAgB,MAAM,EAAE,MAAM,CAAC;IAE/B,8DAA8D;IAC9D,SAAgB,SAAS,EAAE,OAAO,CAAC;IAEnC;;;OAGG;gBACgB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAMhD;AAwDD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,sBAAsB,GAC7B,YAAY,CA0Dd"}
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../../../src/llm/transports/gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EAGpB,MAAM,UAAU,CAAC;AAQlB,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,MAAM,CAAC;CACjE;AAED;;;;;;;;GAQG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD;;;OAGG;gBACgB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAMnD;AAED,4DAA4D;AAC5D,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,uBAAuB;IACvB,SAAgB,MAAM,EAAE,MAAM,CAAC;IAE/B,8DAA8D;IAC9D,SAAgB,SAAS,EAAE,OAAO,CAAC;IAEnC;;;OAGG;gBACgB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAMhD;AAwDD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,sBAAsB,GAC7B,YAAY,CA8Dd"}

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

@@ -1,6 +1,31 @@
 import { Bar, BenchmarkBar } from "./types/alpaca-types";
 import { types } from "@adaptic/backend";
 import { CalculateBetaResult, TradeMetrics } from "./types";
+/**
+ * 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 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
+ * }
+ */
 export declare function calculateBetaFromReturns(portfolioReturns: number[], benchmarkReturns: number[]): CalculateBetaResult;
 /**
  * Calculate max drawdown taking position type into account

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

@@ -1 +1 @@
-{"version":3,"file":"metrics-calcs.d.ts","sourceRoot":"","sources":["../../src/metrics-calcs.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAsJ5D,wBAAgB,wBAAwB,CACtC,gBAAgB,EAAE,MAAM,EAAE,EAC1B,gBAAgB,EAAE,MAAM,EAAE,GACzB,mBAAmB,CA4FrB;AAgQD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,GAAG,EAAE,EAChB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,MAAM,CAAC,CAmCjB;AA8CD,wBAA8B,iBAAiB,CAC7C,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,SAAS,EAAE,GAAG,EAAE,EAChB,aAAa,EAAE,YAAY,EAAE,GAC5B,OAAO,CAAC,YAAY,CAAC,CA0DvB"}
+{"version":3,"file":"metrics-calcs.d.ts","sourceRoot":"","sources":["../../src/metrics-calcs.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AA0I5D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,wBAAwB,CACtC,gBAAgB,EAAE,MAAM,EAAE,EAC1B,gBAAgB,EAAE,MAAM,EAAE,GACzB,mBAAmB,CA6FrB;AA6QD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,GAAG,EAAE,EAChB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,MAAM,CAAC,CAmCjB;AA8CD,wBAA8B,iBAAiB,CAC7C,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,SAAS,EAAE,GAAG,EAAE,EAChB,aAAa,EAAE,YAAY,EAAE,GAC5B,OAAO,CAAC,YAAY,CAAC,CA0DvB"}

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

@@ -78,10 +78,22 @@ export declare function alignReturnsByDate(portfolioHistory: PortfolioHistory, b
     alignedBenchmarkReturns: number[];
 };
 /**
- * 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.
  */
 export declare function calculateBetaFromReturns(portfolioReturns: number[], benchmarkReturns: number[]): CalculateBetaResult;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"performance-metrics.d.ts","sourceRoot":"","sources":["../../src/performance-metrics.ts"],"names":[],"mappings":"AASA,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,wBAAwB,EACxB,YAAY,EACZ,mBAAmB,EAEnB,uBAAuB,EACvB,UAAU,EAEX,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EACL,kBAAkB,EAClB,4BAA4B,EAC7B,MAAM,uBAAuB,CAAC;AAgD/B;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,SAAS,EACT,MAAM,EACN,aAAa,GACd,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiF3C;AAwBD;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,MAAM,CAAC,CA2CjB;AAqMD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,gBAAgB,EAAE,wBAAwB,EAC1C,aAAa,EAAE,YAAY,EAAE,GAC5B,OAAO,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CAiOD;AAkCD,UAAU,cAAc;IACtB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yBAAyB,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;CACrB,GACL,cAAc,CAuHhB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,GAAE,MAAU,GACnB,MAAM,CAGR;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAchE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,gBAAgB,EAAE,gBAAgB,EAClC,aAAa,EAAE,YAAY,EAAE,GAC5B;IAAE,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAAC,uBAAuB,EAAE,MAAM,EAAE,CAAA;CAAE,CAiF1E;AAkFD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,gBAAgB,EAAE,MAAM,EAAE,EAC1B,gBAAgB,EAAE,MAAM,EAAE,GACzB,mBAAmB,CAoErB;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,gBAAgB,EAAE,wBAAwB,EAC1C,aAAa,EAAE,YAAY,EAAE,GAC5B,OAAO,CAAC,MAAM,CAAC,CAmHjB;AA+BD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,sBAAsB,CAAC,WAAW,CAAC,CAAC;CAChD,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAsB1B;AAED;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAAC,EAC5C,MAAM,EACN,MAAM,EACN,SAAS,EACT,aAAa,GACd,EAAE,4BAA4B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA0J5D"}
+{"version":3,"file":"performance-metrics.d.ts","sourceRoot":"","sources":["../../src/performance-metrics.ts"],"names":[],"mappings":"AASA,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,wBAAwB,EACxB,YAAY,EACZ,mBAAmB,EAEnB,uBAAuB,EACvB,UAAU,EAEX,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EACL,kBAAkB,EAClB,4BAA4B,EAC7B,MAAM,uBAAuB,CAAC;AAqD/B;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,SAAS,EACT,MAAM,EACN,aAAa,GACd,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiF3C;AAwBD;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,MAAM,CAAC,CA2CjB;AAqMD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,gBAAgB,EAAE,wBAAwB,EAC1C,aAAa,EAAE,YAAY,EAAE,GAC5B,OAAO,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CA+OD;AAkCD,UAAU,cAAc;IACtB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yBAAyB,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;CACrB,GACL,cAAc,CAuHhB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,GAAE,MAAU,GACnB,MAAM,CAGR;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAchE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,gBAAgB,EAAE,gBAAgB,EAClC,aAAa,EAAE,YAAY,EAAE,GAC5B;IAAE,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAAC,uBAAuB,EAAE,MAAM,EAAE,CAAA;CAAE,CAiF1E;AAkFD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,gBAAgB,EAAE,MAAM,EAAE,EAC1B,gBAAgB,EAAE,MAAM,EAAE,GACzB,mBAAmB,CA2ErB;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,gBAAgB,EAAE,wBAAwB,EAC1C,aAAa,EAAE,YAAY,EAAE,GAC5B,OAAO,CAAC,MAAM,CAAC,CAmHjB;AA+BD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,sBAAsB,CAAC,WAAW,CAAC,CAAC;CAChD,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAsB1B;AAED;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAAC,EAC5C,MAAM,EACN,MAAM,EACN,SAAS,EACT,aAAa,GACd,EAAE,4BAA4B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA0J5D"}

package/dist/types/sample-statistic.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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
+ */
+/**
+ * Why a statistic could not be computed from the observations offered.
+ *
+ * The distinctions are the point: a caller that cannot tell "too few rows" from
+ * "the rows were unusable" from "the population is degenerate" cannot tell a
+ * warm-up from a data outage from a genuinely constant series, and will treat
+ * all three the same way.
+ */
+export type StatisticUnavailableReason = 
+/** Fewer usable observations than the computation requires. */
+"insufficient_samples"
+/** Observations were offered but none survived validation (non-finite, unpaired). */
+ | "no_usable_samples"
+/** Enough usable observations, but the population cannot support the statistic
+ *  (a zero-variance denominator, an undefined ratio). */
+ | "degenerate_population"
+/** The request itself is malformed — mismatched series lengths, a non-positive window. */
+ | "invalid_input";
+/**
+ * How many observations a statistic was actually computed from, against how
+ * many the caller offered.
+ *
+ * `coverage` is the ratio that makes silent row-dropping visible: a function
+ * that filters non-finite rows and reports only the surviving statistic hides
+ * the size of what it discarded, and a statistic computed on 12% of the
+ * requested window is a different claim from the same number computed on all
+ * of it.
+ */
+export interface SampleCohort {
+    /** Observations that entered the computation. Never negative. */
+    readonly sampleCount: number;
+    /** Observations the caller offered, or the window width the caller asked for. */
+    readonly requestedCount: number;
+    /** `sampleCount / requestedCount`, clamped to [0, 1]; `0` when nothing was requested. */
+    readonly coverage: number;
+}
+/** A statistic that was computed, carrying the cohort it was computed on. */
+export interface AvailableStatistic<T> extends SampleCohort {
+    readonly available: true;
+    /** The measured value. */
+    readonly value: T;
+}
+/** A statistic that could not be computed, still carrying what data was seen. */
+export interface UnavailableStatistic extends SampleCohort {
+    readonly available: false;
+    /** Which class of failure prevented the computation. */
+    readonly reason: StatisticUnavailableReason;
+    /** Human-readable specifics, for logs and error messages. Never parsed. */
+    readonly detail: string;
+}
+/**
+ * A statistic that either exists with its cohort, or does not exist and says
+ * why — never a number standing in for an unknown.
+ */
+export type SampleStatistic<T> = AvailableStatistic<T> | UnavailableStatistic;
+/**
+ * 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.
+ */
+export declare function sampleCohort(requestedCount: number, sampleCount: number): SampleCohort;
+/**
+ * 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}.
+ */
+export declare function availableStatistic<T>(value: T, cohort: SampleCohort): AvailableStatistic<T>;
+/**
+ * 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}.
+ */
+export declare function unavailableStatistic(reason: StatisticUnavailableReason, detail: string, cohort: SampleCohort): UnavailableStatistic;
+/**
+ * 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.
+ */
+export declare function isAvailable<T>(statistic: SampleStatistic<T>): statistic is AvailableStatistic<T>;
+//# sourceMappingURL=sample-statistic.d.ts.map

package/dist/types/sample-statistic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sample-statistic.d.ts","sourceRoot":"","sources":["../../src/sample-statistic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,0BAA0B;AACpC,+DAA+D;AAC7D,sBAAsB;AACxB,qFAAqF;GACnF,mBAAmB;AACrB;yDACyD;GACvD,uBAAuB;AACzB,0FAA0F;GACxF,eAAe,CAAC;AAEpB;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,YAAY;IACzD,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,iFAAiF;AACjF,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC;AAE9E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,GAClB,YAAY,CAkBd;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,YAAY,GACnB,kBAAkB,CAAC,CAAC,CAAC,CAEvB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,0BAA0B,EAClC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,GACnB,oBAAoB,CAEtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,SAAS,EAAE,eAAe,CAAC,CAAC,CAAC,GAC5B,SAAS,IAAI,kBAAkB,CAAC,CAAC,CAAC,CAEpC"}

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

@@ -1 +1 @@
-{"version":3,"file":"alpaca-schemas.d.ts","sourceRoot":"","sources":["../../../src/schemas/alpaca-schemas.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAexB,iDAAiD;AACjD,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+CrC,CAAC;AAIH,0CAA0C;AAC1C,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmB/B,CAAC;AAEH,8CAA8C;AAC9C,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAAgC,CAAC;AAqDxE,uCAAuC;AACvC,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,OAiChC,CAAC;AAEH,2CAA2C;AAC3C,eAAO,MAAM,uBAAuB,uDAA6B,CAAC;AAIlE,4CAA4C;AAC5C,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS1B,CAAC;AAEH,0CAA0C;AAC1C,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAI7C,CAAC;AAEH,sCAAsC;AACtC,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGzC,CAAC;AAIH,gCAAgC;AAChC,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAU5B,CAAC;AAEH,wCAAwC;AACxC,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG3C,CAAC;AAIH,gCAAgC;AAChC,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;EAQ5B,CAAC;AAEH,wCAAwC;AACxC,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG3C,CAAC;AAUH,gCAAgC;AAChC,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYlC,CAAC;AAEH,+BAA+B;AAC/B,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGnC,CAAC;AAIH,4CAA4C;AAC5C,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;EAO/C,CAAC;AAIH,sCAAsC;AACtC,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBzC,CAAC"}
+{"version":3,"file":"alpaca-schemas.d.ts","sourceRoot":"","sources":["../../../src/schemas/alpaca-schemas.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAexB,iDAAiD;AACjD,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+CrC,CAAC;AAIH,0CAA0C;AAC1C,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmB/B,CAAC;AAEH,8CAA8C;AAC9C,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAAgC,CAAC;AAsDxE,uCAAuC;AACvC,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,OAiChC,CAAC;AAEH,2CAA2C;AAC3C,eAAO,MAAM,uBAAuB,uDAA6B,CAAC;AAIlE,4CAA4C;AAC5C,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS1B,CAAC;AAEH,0CAA0C;AAC1C,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAI7C,CAAC;AAEH,sCAAsC;AACtC,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGzC,CAAC;AAIH,gCAAgC;AAChC,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAU5B,CAAC;AAEH,wCAAwC;AACxC,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG3C,CAAC;AAIH,gCAAgC;AAChC,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;EAQ5B,CAAC;AAEH,wCAAwC;AACxC,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG3C,CAAC;AAUH,gCAAgC;AAChC,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYlC,CAAC;AAEH,+BAA+B;AAC/B,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGnC,CAAC;AAIH,4CAA4C;AAC5C,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;EAO/C,CAAC;AAIH,sCAAsC;AACtC,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBzC,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"}