@insiderfinance/totalfinance 0.1.0

package/modules/options/src/schema.ts

@@ -0,0 +1,73 @@
+/**
+ * `@insiderfinance/totalfinance/options/schema` — runtime schemas for option payloads (spec §6).
+ *
+ * Isolation guarantee: the hot path is the deep `@insiderfinance/totalfinance/options/black-scholes` entrypoint, which
+ * does NOT import this module — the bundle-size test enforces that it carries no schema/validator
+ * code. The aggregate `@insiderfinance/totalfinance/options` index re-exports these schemas for convenience; bundlers
+ * tree-shake them when unused, but a native-ESM `import { blackScholes } from '@insiderfinance/totalfinance/options'` will still
+ * evaluate this module. That cost is trivial (plain descriptor objects, no work at load); anyone who
+ * needs the guaranteed-lean footprint imports the deep entrypoint. MCP tools, adapters, and validated
+ * wrappers use these; the compute path does not.
+ */
+
+import { type Infer, OptionContractSchema, schema } from '@totalfinance/core/schema';
+
+/**
+ * The Black–Scholes–Merton input field descriptors — the ONE source of truth for every option
+ * payload schema (facade, typed, implied-vol) and for consumers (MCP tools) that compose date-aware
+ * variants. Reusing these fields is why every option schema carries the same field descriptions
+ * instead of drifting apart.
+ */
+export const blackScholesShape = {
+  spot: schema.number().positive().describe('Spot price of the underlying'),
+  strike: schema.number().positive().describe('Strike price'),
+  timeToExpiryYears: schema.number().positive().describe('Time to expiry in years'),
+  riskFreeRate: schema.number().describe('Continuously-compounded risk-free rate (decimal)'),
+  volatility: schema.number().positive().describe('Volatility (decimal)'),
+  dividendYield: schema
+    .number()
+    .optional()
+    .describe('Continuous dividend yield (decimal, default 0)'),
+} as const;
+
+/** The `call | put` option-type enum, shared by every typed option schema. */
+export const optionType = schema.enum(['call', 'put'] as const).describe('Option type');
+
+/** Schema for a `BlackScholesInput` facade payload. */
+export const BlackScholesInputSchema = schema.object(blackScholesShape);
+
+/** Schema for a typed BSM payload (`blackScholes.price` / `blackScholes.greeks`). */
+export const BlackScholesTypedInputSchema = schema.object({
+  ...blackScholesShape,
+  type: optionType,
+});
+
+/**
+ * Schema for an implied-volatility request. Built from {@link blackScholesShape} (minus `volatility`, which is the
+ * unknown being solved) so its fields carry the same descriptions as every other option schema
+ * rather than the bare, description-less duplicate this used to be.
+ */
+export const BlackScholesImpliedVolatilityInputSchema = schema.object({
+  price: schema.number().positive().describe('Observed option price to invert'),
+  spot: blackScholesShape.spot,
+  strike: blackScholesShape.strike,
+  timeToExpiryYears: blackScholesShape.timeToExpiryYears,
+  riskFreeRate: blackScholesShape.riskFreeRate,
+  type: optionType,
+  dividendYield: blackScholesShape.dividendYield,
+});
+
+/** Canonical `OptionContract` schema (defined in `@insiderfinance/totalfinance/core/schema`, re-exported for convenience). */
+export { OptionContractSchema };
+
+/** Convenience namespace mirroring the spec's `schemas.OptionContract.parse(...)` usage. */
+export const schemas = {
+  BlackScholesInput: BlackScholesInputSchema,
+  BlackScholesTypedInput: BlackScholesTypedInputSchema,
+  BlackScholesImpliedVolatilityInput: BlackScholesImpliedVolatilityInputSchema,
+  OptionContract: OptionContractSchema,
+} as const;
+
+export type BlackScholesInputShape = Infer<typeof BlackScholesInputSchema>;
+export type BlackScholesTypedInputShape = Infer<typeof BlackScholesTypedInputSchema>;
+export type OptionContractShape = Infer<typeof OptionContractSchema>;

package/modules/options/src/time.ts

@@ -0,0 +1,104 @@
+/** Time-to-expiry helpers for the pro API. */
+
+import {
+  type EpochMs,
+  ErrorCode,
+  InputError,
+  type OptionContract,
+  optionExpiryToMs,
+  usEquitySessionInstant,
+  yearFraction,
+  validateResolvedExpiry,
+} from '@totalfinance/core';
+
+/**
+ * Parse an ISO date (`YYYY-MM-DD`) or ISO date-time expiry to epoch milliseconds, using the shared
+ * {@link optionExpiryToMs} convention: a bare date resolves to the **US options close** (16:00 ET,
+ * 13:00 ET on early-close days) so an intraday `asOf` on the expiry day still sees positive
+ * time-to-expiry, while a full datetime is
+ * parsed as-is. This is the single option-expiry convention across `core`, `options`, `strategy`, and
+ * `structure`. The resulting `timeToExpiryYears` is always echoed in `assumptions` so it is never hidden.
+ */
+export function parseExpiryToEpoch(expiry: string, functionName: string): EpochMs {
+  try {
+    return optionExpiryToMs(expiry);
+  } catch {
+    throw new InputError(
+      `${functionName}: could not parse expiry "${expiry}" (expected an ISO date or datetime).`,
+      {
+        code: ErrorCode.InputWrongType,
+        context: { field: 'expiry', value: expiry, function: functionName },
+      },
+    );
+  }
+}
+
+/** Year fraction from `asOf` to the contract expiry under ACT/365F. */
+export function timeToExpiryYears(asOf: EpochMs, expiry: string, functionName: string): number {
+  return yearFraction(asOf, parseExpiryToEpoch(expiry, functionName), 'ACT/365F');
+}
+
+/**
+ * Resolve a dividend EX-DATE label to epoch milliseconds.
+ *
+ * A date-only `YYYY-MM-DD` ex-date resolves to the **US equity market OPEN, 09:30 America/New_York**
+ * — deliberately NOT the 16:00 ET option-expiry convention that {@link parseExpiryToEpoch} applies.
+ * A share bought on the ex-date does not carry the dividend: the drop happens at the open, so from
+ * 09:30 onward that dividend is already in the price and must not be discounted into the spot again.
+ * Under the expiry convention an `asOf` of 10:00 ET on the ex-date still saw the dividend as "in the
+ * future" and escrowed it a second time — a full dividend of error in the option price (defect-fix
+ * wave, finding 3).
+ *
+ * A ZONED ISO datetime ex-date is the caller's explicit instant and is parsed as-is, unchanged.
+ *
+ * DST-safe: the instant comes from core's `usEquitySessionInstant` (Intl, per date). The open is 09:30 ET
+ * on every session, including early-close days — it is NOT derived from the close.
+ */
+export function parseExDateToEpoch(exDate: string, functionName: string): EpochMs {
+  if (DATE_ONLY_EX_DATE.test(exDate)) {
+    try {
+      return usEquitySessionInstant(exDate, 'open');
+    } catch {
+      throw new InputError(
+        `${functionName}: could not parse dividend exDate "${exDate}" (expected an ISO date or datetime).`,
+        {
+          code: ErrorCode.InputWrongType,
+          context: { field: 'exDate', value: exDate, function: functionName },
+        },
+      );
+    }
+  }
+  // Datetime labels share the option-expiry parser (strict, zone-required, nothing normalized).
+  return parseExpiryToEpoch(exDate, functionName);
+}
+
+const DATE_ONLY_EX_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Year fraction from `asOf` to a dividend ex-date under ACT/365F, using the MARKET-OPEN convention
+ * for date-only labels (see {@link parseExDateToEpoch}). Every discrete-dividend consumer in the
+ * package resolves ex-dates through here so the schedule means one thing everywhere.
+ */
+export function timeToExDateYears(asOf: EpochMs, exDate: string, functionName: string): number {
+  return yearFraction(asOf, parseExDateToEpoch(exDate, functionName), 'ACT/365F');
+}
+
+/**
+ * Contract-aware time to expiry (E2, one expiry law): a contract PRICES from its resolved
+ * `expiresAt`, cross-validated against the label and convention — there is NO label-parsing
+ * fallback. An unresolved literal is rejected with the builder pointer; a post-construction edit
+ * of any of the three fields fails loudly.
+ */
+export function contractTimeToExpiryYears(
+  asOf: EpochMs,
+  contract: Pick<OptionContract, 'expiry' | 'expiresAt' | 'expiryConvention'>,
+  functionName: string,
+): number {
+  validateResolvedExpiry(
+    functionName,
+    contract.expiry,
+    contract.expiresAt,
+    contract.expiryConvention,
+  );
+  return yearFraction(asOf, contract.expiresAt, 'ACT/365F');
+}

package/modules/options/src/types.ts

@@ -0,0 +1,124 @@
+/** Public option-pricing types (spec §9). Pure types — no runtime, no bundle cost. */
+
+import type { Computed, MarketInputs, OptionType } from '@totalfinance/core';
+
+/**
+ * First-order Greeks in TotalFinance default units:
+ *   - `theta` per calendar day (ACT/365F),
+ *   - `vega` per 1 volatility point (1% = 0.01),
+ *   - `rho` per 1% change in the rate.
+ * The applied units are always echoed in `assumptions.units`.
+ */
+export interface Greeks {
+  delta: number;
+  gamma: number;
+  theta: number;
+  vega: number;
+  rho: number;
+}
+
+/** Flat facade input for a single Black–Scholes–Merton computation. */
+export interface BlackScholesInput {
+  /** Spot price of the underlying. */
+  spot: number;
+  /** Strike price. */
+  strike: number;
+  /** Time to expiry in years. */
+  timeToExpiryYears: number;
+  /** Continuously-compounded risk-free rate (decimal, e.g. `0.045`). */
+  riskFreeRate: number;
+  /** Volatility (decimal, e.g. `0.22`). */
+  volatility: number;
+  /** Continuous dividend yield (decimal, default `0`). */
+  dividendYield?: number;
+}
+
+/** Facade input where the option type is explicit (`blackScholes.price`, `blackScholes.greeks`). */
+export interface BlackScholesTypedInput extends BlackScholesInput {
+  type: OptionType;
+}
+
+/** Facade input for implied-volatility solving. */
+export interface BlackScholesImpliedVolatilityInput {
+  /** Observed option price to invert. */
+  price: number;
+  spot: number;
+  strike: number;
+  timeToExpiryYears: number;
+  riskFreeRate: number;
+  type: OptionType;
+  dividendYield?: number;
+}
+
+/** A discrete cash dividend with an ex-date (ISO) and per-share amount. */
+export interface DiscreteDividend {
+  /**
+   * Ex-date, `YYYY-MM-DD` or a zoned ISO datetime.
+   *
+   * A DATE-ONLY label resolves to the US equity market OPEN, **09:30 America/New_York** — the
+   * instant the share starts trading without the dividend. This is deliberately NOT the 16:00 ET
+   * convention a date-only option EXPIRY uses: they are different events. The practical consequence
+   * is that an `asOf` from 09:30 ET on the ex-date onward treats the dividend as PAID (it is already
+   * out of the spot) and stops discounting it into the escrowed spot, while `asOf` earlier that
+   * morning, or any time the day before, still accrues it.
+   *
+   * Pass a zoned datetime (e.g. `'2026-06-01T09:30:00-04:00'`) to name the instant yourself.
+   */
+  exDate: string;
+  /** Cash amount per share (must be finite and non-negative). */
+  amount: number;
+}
+
+/**
+ * Market inputs for the pro pricing API (spec §9.1). Extends the workspace-canonical
+ * {@link MarketInputs} (spot/rate/dividendYield/asOf) and adds the option-specific fields. `spot` is
+ * required (every pro engine resolves off it — forward-only pricing uses the flat `black76`/
+ * `bachelier` facades). `rate`/`volatility` are scalars in this milestone; a `VolatilityLookup` variant for
+ * `volatility` arrives with the surface integration.
+ */
+export interface OptionMarket extends MarketInputs {
+  forward?: number;
+  /** Discrete cash dividends (American engines use the escrowed-dividend approximation). */
+  dividends?: DiscreteDividend[];
+  volatility?: number;
+  /** The observed premium an inversion reproduces (`option.impliedVolatility`). */
+  price?: number;
+}
+
+/** Extended (higher-order) Greeks (spec §9.4). */
+export interface ExtendedGreeks extends Greeks {
+  vanna: number;
+  charm: number;
+  vomma: number;
+  speed: number;
+  color: number;
+  /** Dividend rho (epsilon) `ε = ∂V/∂q`, per 1% dividend yield (scaled like `rho`). */
+  phi: number;
+  /** `∂Γ/∂σ = ∂³V/∂S²∂σ` (raw, per 1.00 σ). */
+  zomma: number;
+  /** `∂vega/∂T` (raw, per year of time-to-expiry; vega here is per 1.00 σ) — the ∂/∂T sibling of vega. */
+  veta: number;
+  /** `∂rho/∂σ = ∂²V/∂r∂σ` (raw, per 1.00 σ; rho here is per 1.00 rate). */
+  vera: number;
+  /** `∂vomma/∂σ = ∂³V/∂σ³` (raw). */
+  ultima: number;
+  /**
+   * Elasticity / effective leverage `Λ = Δ·S / V` (dimensionless). `null` when the price
+   * underflows to zero (deep-OTM): elasticity is undefined at V = 0 and is disclosed as null with
+   * a `greeks.lambda_undefined` warning on explained paths — never NaN/Infinity (Law 7).
+   */
+  lambda: number | null;
+}
+
+/**
+ * Result of a pro `option.price(...)` call: a value envelope plus Greeks. `greeks` is OPTIONAL — absent
+ * means "not computed" (e.g. a Monte-Carlo engine priced without the extra Greek budget). Absent is never
+ * the same as a genuine zero: engines never fabricate `{delta:0, …}`. It is the **first-order** `Greeks`
+ * by default, or the full {@link ExtendedGreeks} when the call passes `{ extendedGreeks: true }`.
+ */
+export interface PriceResult extends Computed<number> {
+  greeks?: Greeks | ExtendedGreeks;
+}
+
+/** Result of a pro `option.impliedVolatility(...)` call. */
+export type ImpliedVolatilityResult = Computed<number>;

package/modules/performance/dist/activity.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@insiderfinance/totalfinance/performance/activity` — portfolio-activity metrics (spec §15.1): turnover and exposure.
+ *
+ * Both read a time series of portfolio weight vectors — `weights[t][i]` is the weight of asset `i` at
+ * rebalance `t` (negative = short, the row need not sum to 1 if the book runs net cash). These are the
+ * two metrics that need position data rather than just a return/equity series.
+ */
+export interface ExposureResult {
+    /** Fraction of periods with any non-zero net position (`Σ_i w ≠ 0`). */
+    timeInMarket: number | null;
+    /** Average gross exposure `mean_t( Σ_i |w_{t,i}| )`. */
+    averageGross: number | null;
+    /** Average net exposure `mean_t( Σ_i w_{t,i} )`. */
+    averageNet: number | null;
+    /** Average long exposure `mean_t( Σ_i max(w_{t,i}, 0) )`. */
+    averageLong: number | null;
+    /** Average short exposure as a positive number `mean_t( Σ_i max(−w_{t,i}, 0) )`. */
+    averageShort: number | null;
+}
+/** Turnover facade (dx §2.3): plain call → the ratio; `.explain()` → the Computed envelope. */
+export declare const turnover: import("../../core/dist/index.js").SeriesFacade<[weights: readonly ArrayLike<number>[]], number | null, Record<never, never>>;
+/** Exposure facade (dx §2.3): plain call → the profile; `.explain()` → the Computed envelope. */
+export declare const exposure: import("../../core/dist/index.js").SeriesFacade<[weights: readonly ArrayLike<number>[]], ExposureResult, Record<never, never>>;
+//# sourceMappingURL=activity.d.ts.map

package/modules/performance/dist/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA8DH,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,wDAAwD;IACxD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,oDAAoD;IACpD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,oFAAoF;IACpF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAqED,+FAA+F;AAC/F,eAAO,MAAM,QAAQ,+HAYpB,CAAC;AAEF,iGAAiG;AACjG,eAAO,MAAM,QAAQ,gIAiBpB,CAAC"}

package/modules/performance/dist/activity.js

@@ -0,0 +1,137 @@
+/**
+ * `@insiderfinance/totalfinance/performance/activity` — portfolio-activity metrics (spec §15.1): turnover and exposure.
+ *
+ * Both read a time series of portfolio weight vectors — `weights[t][i]` is the weight of asset `i` at
+ * rebalance `t` (negative = short, the row need not sum to 1 if the book runs net cash). These are the
+ * two metrics that need position data rather than just a return/equity series.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, seriesFacade, finiteOrNull, } from '../../core/dist/index.js';
+import { degenerateAwareDiagnostics } from './sharpe.js';
+function requireRectangular(weights, functionName) {
+    if (!Array.isArray(weights)) {
+        throw new InputError(`${functionName}: weights must be an array of per-period weight rows (weights[t][i]).`, {
+            code: ErrorCode.InputWrongType,
+            context: { function: functionName },
+        });
+    }
+    if (weights.length === 0)
+        return 0;
+    const width = weights[0].length;
+    for (let t = 0; t < weights.length; t++) {
+        if (weights[t].length !== width) {
+            throw new InputError(`${functionName}: every weight row must have the same length (${width}).`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { row: t, expected: width, got: weights[t].length },
+            });
+        }
+    }
+    return width;
+}
+/**
+ * Average one-way turnover per rebalance: `mean_t( ½·Σ_i |w_{t,i} − w_{t-1,i}| )`. The leading row
+ * counts as turnover from an all-cash start, so a single buy-and-hold allocation reports its entry
+ * turnover once and ~0 thereafter.
+ *
+ * NOTE: this is a **per-rebalance weight-change ratio** (unitless, in [0, 1] one-way), distinct from
+ * `BacktestResult.turnover` in `@insiderfinance/totalfinance/backtest`, which is a **traded-notional ÷ equity** ratio
+ * accumulated over the run. Different definitions and units — do not compare the two directly.
+ */
+function turnoverValue(weights) {
+    const width = requireRectangular(weights, 'turnover');
+    if (weights.length === 0)
+        return NaN;
+    let total = 0;
+    for (let t = 0; t < weights.length; t++) {
+        let row = 0;
+        for (let i = 0; i < width; i++) {
+            const prev = t === 0 ? 0 : weights[t - 1][i];
+            row += Math.abs(weights[t][i] - prev);
+        }
+        total += row / 2;
+    }
+    return total / weights.length;
+}
+/** Exposure profile from a weight time series: time-in-market plus average gross/net/long/short. */
+function exposureValue(weights) {
+    const width = requireRectangular(weights, 'exposure');
+    const n = weights.length;
+    if (n === 0) {
+        return {
+            timeInMarket: NaN,
+            averageGross: NaN,
+            averageNet: NaN,
+            averageLong: NaN,
+            averageShort: NaN,
+        };
+    }
+    let inMarket = 0;
+    let gross = 0;
+    let net = 0;
+    let long = 0;
+    let short = 0;
+    for (let t = 0; t < n; t++) {
+        let rowNet = 0;
+        let rowGross = 0;
+        for (let i = 0; i < width; i++) {
+            const w = weights[t][i];
+            rowNet += w;
+            rowGross += Math.abs(w);
+            if (w > 0)
+                long += w;
+            else if (w < 0)
+                short -= w;
+        }
+        if (rowGross > 0)
+            inMarket++;
+        gross += rowGross;
+        net += rowNet;
+    }
+    return {
+        timeInMarket: inMarket / n,
+        averageGross: gross / n,
+        averageNet: net / n,
+        averageLong: long / n,
+        averageShort: short / n,
+    };
+}
+/** Law 7 (D3): an empty weight series makes every profile field undefined — null, never NaN. */
+function nullSafeExposure(v) {
+    return {
+        timeInMarket: v['timeInMarket'] === null || v['timeInMarket'] === undefined
+            ? null
+            : finiteOrNull(v['timeInMarket']),
+        averageGross: v['averageGross'] === null || v['averageGross'] === undefined
+            ? null
+            : finiteOrNull(v['averageGross']),
+        averageNet: v['averageNet'] === null || v['averageNet'] === undefined
+            ? null
+            : finiteOrNull(v['averageNet']),
+        averageLong: v['averageLong'] === null || v['averageLong'] === undefined
+            ? null
+            : finiteOrNull(v['averageLong']),
+        averageShort: v['averageShort'] === null || v['averageShort'] === undefined
+            ? null
+            : finiteOrNull(v['averageShort']),
+    };
+}
+/** Turnover facade (dx §2.3): plain call → the ratio; `.explain()` → the Computed envelope. */
+export const turnover = seriesFacade('turnover', (weights) => finiteOrNull(turnoverValue(weights)), (weights) => {
+    const value = turnoverValue(weights);
+    return {
+        value: finiteOrNull(value),
+        assumptions: { conventionsVersion: CONVENTIONS_VERSION },
+        // No series args: weights are not returns, so the prices-as-returns scan must not apply.
+        diagnostics: degenerateAwareDiagnostics(value, 'turnover', 'the weight series is empty'),
+    };
+});
+/** Exposure facade (dx §2.3): plain call → the profile; `.explain()` → the Computed envelope. */
+export const exposure = seriesFacade('exposure', (weights) => nullSafeExposure(exposureValue(weights)), (weights) => {
+    const value = exposureValue(weights);
+    return {
+        value: nullSafeExposure(value),
+        assumptions: { conventionsVersion: CONVENTIONS_VERSION },
+        // Probe one field: every field of the profile is NaN together (empty weight series).
+        diagnostics: degenerateAwareDiagnostics(value.timeInMarket ?? NaN, 'exposure', 'the weight series is empty'),
+    };
+});
+//# sourceMappingURL=activity.js.map

package/modules/performance/dist/activity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.js","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"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"}

package/modules/performance/dist/analyze.d.ts

@@ -0,0 +1,85 @@
+/** A one-call performance summary (spec §15.1). */
+import { type QuantWarning } from '../../core/dist/index.js';
+import { type DrawdownResult } from './drawdown.js';
+/**
+ * Input for {@link analyze}: an explicit `equity` curve (growth of capital) **or** a per-period
+ * `returns` series — a tagged union so the caller can never silently confuse the two (WS3.3b).
+ */
+export type AnalyzeInput = {
+    equity: ArrayLike<number>;
+} | {
+    returns: ArrayLike<number>;
+};
+export interface AnalyzeOptions {
+    /** Annualization factor. Defaults to 252 (daily); echoed in the summary's `assumptions`. */
+    periodsPerYear?: number;
+    riskFreeRate?: number;
+    /**
+     * Per-period benchmark **return** series aligned to the equity curve's returns (length =
+     * `equity.length − 1`). When supplied, the summary adds beta, alpha, tracking error, information
+     * ratio, and the Treynor ratio.
+     */
+    benchmark?: ArrayLike<number>;
+}
+export interface PerformanceSummary {
+    periods: number;
+    /** `null` when compounding overflowed (disclosed via `performance.non_finite_metric`). */
+    totalReturn: number | null;
+    /** `null` when compounding overflowed (disclosed via `performance.non_finite_metric`). */
+    annualizedReturn: number | null;
+    annualizedVolatility: number | null;
+    /** `null` when the metric is undefined for this input (disclosed via warnings). */
+    sharpe: number | null;
+    /** `null` when the metric is undefined for this input (disclosed via warnings). */
+    sortino: number | null;
+    /** `null` when the metric is undefined for this input (disclosed via warnings). */
+    calmar: number | null;
+    maxDrawdown: number;
+    drawdown: DrawdownResult;
+    /** Omega ratio at a 0 per-period threshold. */
+    /** `null` when the metric is undefined for this input (disclosed via warnings). */
+    omega: number | null;
+    /** Fraction of non-zero return periods that were positive. */
+    /** `null` when the metric is undefined for this input (disclosed via warnings). */
+    hitRate: number | null;
+    /** Gross gains ÷ gross losses across the return series. */
+    /** `null` when the metric is undefined for this input (disclosed via warnings). */
+    profitFactor: number | null;
+    /** Mean per-period return (expectancy); `null` on an empty series or overflow (disclosed). */
+    expectancy: number | null;
+    /** Diagnostics — e.g. `performance.suspicious_equity_input` when an equity curve looks like returns. */
+    warnings: QuantWarning[];
+    /** Beta to the benchmark (only when `options.benchmark` is supplied). */
+    beta?: number | null;
+    /** Annualized Jensen's alpha (only when `options.benchmark` is supplied). */
+    alpha?: number | null;
+    /** Annualized tracking error (only when `options.benchmark` is supplied). */
+    trackingError?: number | null;
+    /** Information ratio (only when `options.benchmark` is supplied). */
+    informationRatio?: number | null;
+    /** Treynor ratio (only when `options.benchmark` is supplied). */
+    treynor?: number | null;
+    /** The conventions actually applied — a serialized summary is self-interpreting (spec §7.4). */
+    assumptions: {
+        /** Annualization factor used for all annualized metrics. */
+        periodsPerYear: number;
+        /** Per-period risk-free rate used for Sharpe/Sortino/alpha/Treynor (0 when unspecified). */
+        riskFreeRate: number;
+        /** Length of the benchmark return series, present only when a benchmark was supplied. */
+        benchmarkLength?: number;
+    };
+}
+/**
+ * The performance summary facade (dx §2.3): plain call → the summary; `.explain()` → the core
+ * Computed envelope around it (the summary's own warnings ride `diagnostics.warnings`, its echoed
+ * conventions ride `assumptions`).
+ */
+export declare const analyze: import("../../core/dist/index.js").SeriesFacade<[input: AnalyzeInput, options?: AnalyzeOptions | undefined], PerformanceSummary, {
+    /** Annualization factor used for all annualized metrics. */
+    periodsPerYear: number;
+    /** Per-period risk-free rate used for Sharpe/Sortino/alpha/Treynor (0 when unspecified). */
+    riskFreeRate: number;
+    /** Length of the benchmark return series, present only when a benchmark was supplied. */
+    benchmarkLength?: number;
+}>;
+//# sourceMappingURL=analyze.d.ts.map

package/modules/performance/dist/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA,mDAAmD;AAEnD,OAAO,EAIL,KAAK,YAAY,EAMlB,MAAM,0BAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,cAAc,EAAe,MAAM,eAAe,CAAC;AASjE;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IAAE,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC;AAK1F,MAAM,WAAW,cAAc;IAC7B,4FAA4F;IAC5F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;CAC/B;AAKD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,0FAA0F;IAC1F,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,mFAAmF;IACnF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mFAAmF;IACnF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,mFAAmF;IACnF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,cAAc,CAAC;IACzB,+CAA+C;IAC/C,mFAAmF;IACnF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,8DAA8D;IAC9D,mFAAmF;IACnF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,2DAA2D;IAC3D,mFAAmF;IACnF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,8FAA8F;IAC9F,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wGAAwG;IACxG,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,gGAAgG;IAChG,WAAW,EAAE;QACX,4DAA4D;QAC5D,cAAc,EAAE,MAAM,CAAC;QACvB,4FAA4F;QAC5F,YAAY,EAAE,MAAM,CAAC;QACrB,yFAAyF;QACzF,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAgMD;;;;GAIG;AACH,eAAO,MAAM,OAAO;IA5MhB,4DAA4D;oBAC5C,MAAM;IACtB,4FAA4F;kBAC9E,MAAM;IACpB,yFAAyF;sBACvE,MAAM;EAqN3B,CAAC"}