@adaptic/utils 0.0.989 → 0.0.991

package/dist/index.cjs

@@ -6044,6 +6044,202 @@ async function createLimitOrder(auth, params = {
 }
 
 // Utility function for debug logging
+/** Sliding-window size (number of recent outcomes tracked per host). */
+const CIRCUIT_WINDOW_SIZE = 20;
+/** Maximum age (ms) of an outcome before it is dropped from the window. */
+const CIRCUIT_WINDOW_TTL_MS = 30_000;
+/**
+ * Failure ratio (0..1) at which the breaker trips when the window
+ * is full (i.e. CIRCUIT_WINDOW_SIZE outcomes recorded).
+ *
+ * Tuned to be permissive enough that a few transient failures during
+ * normal operation do not trip the breaker, but tight enough that a
+ * persistent upstream outage (where >= half of recent calls are
+ * failing) is detected quickly. With WINDOW=20 and threshold=0.6 we
+ * need 12 failures within the most recent 20 attempts to trip.
+ */
+const CIRCUIT_TRIP_FAILURE_RATIO = 0.6;
+/**
+ * Minimum number of recent outcomes required before the failure-ratio
+ * gate is even evaluated. Without this guard, a single failure on a
+ * cold host would give a 100 % ratio and trip the breaker on the
+ * second attempt — which would be useless protection while also being
+ * highly destructive.
+ */
+const CIRCUIT_MIN_SAMPLES = 8;
+/**
+ * How long the breaker stays open before transitioning to half-open
+ * (i.e. allowing the next request through as a probe). The next
+ * outcome — success or failure — fully recloses or re-opens the
+ * breaker. 5 s aligns with typical upstream recovery times and is
+ * short enough that the next caller drives the probe.
+ */
+const CIRCUIT_OPEN_COOLDOWN_MS = 5_000;
+/**
+ * Fail-fast latency. We sleep a short, deterministic amount before
+ * rejecting so the upstream caller's outer timeout (commonly 10–25 s)
+ * sees a clean rejection rather than a synchronous reject-storm that
+ * could starve other event-loop work. 100 ms aligns with the user's
+ * G1 analysis target: "cap per-symbol fallback latency at 100 ms
+ * during outages — eliminating the 25 s × N-concurrent-symbols
+ * event-loop hog."
+ */
+const CIRCUIT_FAIL_FAST_LATENCY_MS = 100;
+const circuitStates = new Map();
+function getCircuitState(host) {
+    let state = circuitStates.get(host);
+    if (!state) {
+        state = {
+            host,
+            recent: [],
+            openedAt: 0,
+            lastTripFailureRatio: 0,
+        };
+        circuitStates.set(host, state);
+    }
+    return state;
+}
+function pruneStaleSamples(state, now) {
+    const cutoff = now - CIRCUIT_WINDOW_TTL_MS;
+    // Remove entries older than the TTL. Window is small so a simple
+    // filter is fine — no need for a deque structure.
+    if (state.recent.length === 0)
+        return;
+    let firstFreshIndex = 0;
+    while (firstFreshIndex < state.recent.length &&
+        state.recent[firstFreshIndex].atMs < cutoff) {
+        firstFreshIndex += 1;
+    }
+    if (firstFreshIndex > 0) {
+        state.recent.splice(0, firstFreshIndex);
+    }
+}
+function recordOutcome(host, ok) {
+    const now = Date.now();
+    const state = getCircuitState(host);
+    pruneStaleSamples(state, now);
+    state.recent.push({ atMs: now, ok });
+    if (state.recent.length > CIRCUIT_WINDOW_SIZE) {
+        state.recent.shift();
+    }
+    // If we are in the open or half-open window and just received an
+    // outcome, decide whether to close or re-open.
+    if (state.openedAt > 0) {
+        if (now - state.openedAt >= CIRCUIT_OPEN_COOLDOWN_MS) {
+            // Half-open probe outcome arrived.
+            if (ok) {
+                // Recovered. Close the breaker.
+                state.openedAt = 0;
+                state.lastTripFailureRatio = 0;
+                getLogger().info(`Circuit breaker for ${host} closed — upstream recovered`, { host });
+            }
+            else {
+                // Probe failed. Re-open the breaker for another cooldown.
+                state.openedAt = now;
+            }
+            return;
+        }
+        // Still inside the cooldown window — outcomes are recorded for
+        // statistics but the breaker stays open regardless.
+        return;
+    }
+    // Closed breaker — evaluate whether the failure ratio has tripped.
+    if (state.recent.length < CIRCUIT_MIN_SAMPLES)
+        return;
+    const failures = state.recent.reduce((acc, entry) => acc + (entry.ok ? 0 : 1), 0);
+    const ratio = failures / state.recent.length;
+    if (ratio >= CIRCUIT_TRIP_FAILURE_RATIO) {
+        state.openedAt = now;
+        state.lastTripFailureRatio = ratio;
+        getLogger().warn(`Circuit breaker for ${host} opened — ${failures}/${state.recent.length} recent attempts failed (${(ratio * 100).toFixed(0)}%); fail-fast for ${CIRCUIT_OPEN_COOLDOWN_MS}ms`, {
+            host,
+            recentFailures: failures,
+            recentSamples: state.recent.length,
+            failureRatio: ratio,
+            cooldownMs: CIRCUIT_OPEN_COOLDOWN_MS,
+        });
+    }
+}
+function isCircuitOpen(host, now) {
+    const state = circuitStates.get(host);
+    if (!state || state.openedAt === 0)
+        return false;
+    pruneStaleSamples(state, now);
+    return now - state.openedAt < CIRCUIT_OPEN_COOLDOWN_MS;
+}
+/**
+ * Error thrown by {@link fetchWithRetry} when the per-host circuit
+ * breaker is open and fail-fast suppression is in effect.
+ *
+ * Carries the host, the failure ratio that tripped the breaker, and
+ * the remaining cooldown so callers can render an actionable log.
+ */
+class CircuitOpenError extends Error {
+    code = "MASSIVE_CIRCUIT_OPEN";
+    host;
+    tripFailureRatio;
+    cooldownRemainingMs;
+    constructor(host, tripFailureRatio, cooldownRemainingMs) {
+        super(`Circuit open for ${host} — fail-fast (recent failure ratio ${(tripFailureRatio * 100).toFixed(0)}%, retry in ${cooldownRemainingMs}ms)`);
+        this.name = "CircuitOpenError";
+        this.host = host;
+        this.tripFailureRatio = tripFailureRatio;
+        this.cooldownRemainingMs = cooldownRemainingMs;
+    }
+}
+/**
+ * Force-close the breaker for a given host. Exposed for tests and
+ * operator-runbook scripts so a stuck-open breaker can be reset
+ * without bouncing the process. Not intended for hot-path use.
+ *
+ * @param host The hostname whose breaker should be reset.
+ */
+function resetCircuitBreaker(host) {
+    const state = circuitStates.get(host);
+    if (!state)
+        return;
+    state.openedAt = 0;
+    state.lastTripFailureRatio = 0;
+    state.recent = [];
+}
+/**
+ * Snapshot of all known per-host circuit-breaker states. Intended for
+ * an operational-truth / status endpoint to surface upstream health.
+ *
+ * @returns Map of host → {open, openedAt, recentSamples, failureRatio,
+ *          lastTripFailureRatio}.
+ */
+function getCircuitBreakerSnapshot() {
+    const now = Date.now();
+    const snapshot = {};
+    for (const [host, state] of circuitStates) {
+        pruneStaleSamples(state, now);
+        const failures = state.recent.reduce((acc, entry) => acc + (entry.ok ? 0 : 1), 0);
+        const ratio = state.recent.length > 0 ? failures / state.recent.length : 0;
+        snapshot[host] = {
+            open: state.openedAt > 0 && now - state.openedAt < CIRCUIT_OPEN_COOLDOWN_MS,
+            openedAt: state.openedAt,
+            cooldownRemainingMs: state.openedAt > 0
+                ? Math.max(0, CIRCUIT_OPEN_COOLDOWN_MS - (now - state.openedAt))
+                : 0,
+            recentSamples: state.recent.length,
+            failureRatio: ratio,
+            lastTripFailureRatio: state.lastTripFailureRatio,
+        };
+    }
+    return snapshot;
+}
+function hostnameFromUrl(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return null;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 /**
  * Debug logging utility that respects environment debug flags.
  * Logs messages through the configured structured logger when LUMIC_DEBUG
@@ -6155,9 +6351,46 @@ function hideApiKeyFromurl(url) {
  * @throws Will throw an error if the fetch fails after the specified number of retries.
  */
 async function fetchWithRetry(url, options = {}, retries = 3, initialBackoff = 1000) {
+    // Per-host circuit-breaker check. When upstream is failing
+    // pervasively (e.g. Massive REST in an outage), short-circuit to a
+    // 100 ms fail-fast rejection so the caller's outer timeout (25 s,
+    // 10 s, etc.) does not pile concurrent symbol fetches against a
+    // dead host. Without this, an upstream outage during a screener tick
+    // can lock up the event loop for up to (timeout × N-concurrent-symbols).
+    const host = hostnameFromUrl(url);
+    if (host) {
+        const now = Date.now();
+        if (isCircuitOpen(host, now)) {
+            const state = getCircuitState(host);
+            const cooldownRemainingMs = Math.max(0, CIRCUIT_OPEN_COOLDOWN_MS - (now - state.openedAt));
+            await sleep(CIRCUIT_FAIL_FAST_LATENCY_MS);
+            throw new CircuitOpenError(host, state.lastTripFailureRatio, cooldownRemainingMs);
+        }
+    }
     return withRetry(async () => {
-        const response = await fetch(url, options);
+        let response;
+        try {
+            response = await fetch(url, options);
+        }
+        catch (networkError) {
+            // Network failure (e.g. DNS, connection refused, TLS abort).
+            // Record against the breaker so a sustained outage trips it
+            // for subsequent calls; then re-throw so withRetry handles
+            // its own retry policy.
+            if (host)
+                recordOutcome(host, false);
+            throw networkError;
+        }
         if (!response.ok) {
+            // Classify the outcome for the circuit breaker. 5xx and 429
+            // are upstream-health signals (record as failure). 4xx client
+            // errors are caller-side and should NOT affect the breaker —
+            // a request with a bad API key shouldn't trip the host's
+            // breaker for everyone else.
+            const upstreamUnhealthy = response.status === 429 ||
+                (response.status >= 500 && response.status < 600);
+            if (host)
+                recordOutcome(host, !upstreamUnhealthy);
             // Enhanced HTTP error handling with specific error types
             if (response.status === 429) {
                 // Check for Retry-After header
@@ -6189,6 +6422,10 @@ async function fetchWithRetry(url, options = {}, retries = 3, initialBackoff = 1
             error.response = response;
             throw error;
         }
+        // Success — record against the breaker so a healthy upstream
+        // closes any half-open state cleanly.
+        if (host)
+            recordOutcome(host, true);
         return response;
     }, {
         maxRetries: retries,
@@ -7804,6 +8041,81 @@ const fetchTickerNews = async (ticker, options = {
     });
 };
 
+/**
+ * Wilder ATR + EWMA-smoothed + multi-timespan variants.
+ *
+ * All functions are pure: same inputs → same output, no I/O, no time-dependence.
+ */
+/**
+ * Classic Wilder ATR (single value).
+ * @returns ATR for the most recent `period` bars, or null when insufficient bars.
+ */
+function calculateATR(highs, lows, closes, period) {
+    if (period < 1 || !Number.isInteger(period)) {
+        throw new Error("ATR: period must be a positive integer");
+    }
+    if (highs.length !== lows.length || highs.length !== closes.length) {
+        throw new Error("ATR: highs, lows, closes must have equal length");
+    }
+    if (highs.length < period + 1)
+        return null;
+    const trs = [];
+    for (let i = 1; i < highs.length; i++) {
+        const tr = Math.max(highs[i] - lows[i], Math.abs(highs[i] - closes[i - 1]), Math.abs(lows[i] - closes[i - 1]));
+        trs.push(tr);
+    }
+    // Wilder smoothing: first ATR = simple mean of first `period` TRs
+    let atr = trs.slice(0, period).reduce((a, b) => a + b, 0) / period;
+    for (let i = period; i < trs.length; i++) {
+        atr = (atr * (period - 1) + trs[i]) / period;
+    }
+    return atr;
+}
+/**
+ * Returns the EWMA-smoothed ATR series (one ATR per bar, leading nulls until `period` bars).
+ */
+function calculateATREMA(highs, lows, closes, period) {
+    if (period < 1 || !Number.isInteger(period)) {
+        throw new Error("ATR: period must be a positive integer");
+    }
+    if (highs.length !== lows.length || highs.length !== closes.length) {
+        throw new Error("ATREMA: highs, lows, closes must have equal length");
+    }
+    const out = highs.map(() => null);
+    if (highs.length < period + 1)
+        return out;
+    // Index 0 is a placeholder so trs[i] aligns with bar i (i >= 1); TR is undefined for the first bar (no prior close).
+    const trs = [0];
+    for (let i = 1; i < highs.length; i++) {
+        trs.push(Math.max(highs[i] - lows[i], Math.abs(highs[i] - closes[i - 1]), Math.abs(lows[i] - closes[i - 1])));
+    }
+    let atr = trs.slice(1, period + 1).reduce((a, b) => a + b, 0) / period;
+    out[period] = atr;
+    for (let i = period + 1; i < trs.length; i++) {
+        atr = (atr * (period - 1) + trs[i]) / period;
+        out[i] = atr;
+    }
+    return out;
+}
+/**
+ * Wrapper that accepts AtrBar[] (timespan-tagged); identical math, the timespan tag is
+ * carried through for consumer-side logic only.
+ *
+ * @param bars - All bars must share the same timespan; the tag is metadata only
+ *               and is not validated. Mixed-timespan input produces a meaningless ATR.
+ * @param period - Wilder lookback period (positive integer).
+ */
+function calculateATRMultiTimespan(bars, period) {
+    return calculateATR(bars.map((b) => b.high), bars.map((b) => b.low), bars.map((b) => b.close), period);
+}
+
+var atrNs = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    calculateATR: calculateATR,
+    calculateATREMA: calculateATREMA,
+    calculateATRMultiTimespan: calculateATRMultiTimespan
+});
+
 const ALPACA_API_BASE = MARKET_DATA_API.CRYPTO;
 /**
  * Fetches cryptocurrency bars for the specified parameters.
@@ -10853,6 +11165,335 @@ async function fetchPerformanceMetrics({ params, client, accountId, alpacaAccoun
     }
 }
 
+/**
+ * VaR, Expected Shortfall (CVaR), conditional drawdown, rolling drawdown, Sortino, Calmar.
+ *
+ * Convention: VaR and ES are returned as the actual quantile value (typically negative
+ * for losses). Drawdowns from `calculateConditionalDrawdown` are returned as non-negative
+ * magnitudes (e.g., 0.05 = 5% drawdown). Drawdowns from `calculateRollingDrawdown` are
+ * non-positive (e.g., -0.05 = 5% below rolling peak, 0 = at or above peak).
+ *
+ * All public functions reject non-finite inputs (NaN, Infinity) by throwing. Callers
+ * must pre-validate or filter their inputs.
+ */
+function assertAlpha(alpha) {
+    if (!(alpha > 0 && alpha < 1)) {
+        throw new Error(`alpha must be in (0,1), got ${alpha}`);
+    }
+}
+function assertFiniteArray$1(name, arr) {
+    for (let i = 0; i < arr.length; i++) {
+        if (!Number.isFinite(arr[i])) {
+            throw new Error(`${name}: input contains non-finite value at index ${i}: ${arr[i]}`);
+        }
+    }
+}
+/**
+ * Historical-bootstrap VaR at confidence `alpha`.
+ * E.g., alpha=0.95 returns the 5%-quantile of returns (the loss at the 5th percentile).
+ *
+ * @returns The quantile value (typically negative), or null on empty input.
+ */
+function calculateVaRHistorical(returns, alpha) {
+    assertAlpha(alpha);
+    if (returns.length === 0)
+        return null;
+    assertFiniteArray$1("calculateVaRHistorical", returns);
+    const sorted = [...returns].sort((a, b) => a - b);
+    const idx = Math.max(0, Math.floor((1 - alpha) * sorted.length) - 1);
+    return sorted[idx];
+}
+/**
+ * Gaussian parametric VaR: μ + zα·σ where zα is the (1-alpha) standard-normal quantile.
+ *
+ * @returns The Gaussian quantile, or null when fewer than 2 samples.
+ */
+function calculateVaRParametric(returns, alpha) {
+    assertAlpha(alpha);
+    if (returns.length < 2)
+        return null;
+    assertFiniteArray$1("calculateVaRParametric", returns);
+    const mean = returns.reduce((a, b) => a + b, 0) / returns.length;
+    const variance = returns.reduce((a, b) => a + (b - mean) ** 2, 0) / (returns.length - 1);
+    const sigma = Math.sqrt(variance);
+    const z = inverseStdNormal(1 - alpha);
+    return mean + z * sigma;
+}
+/**
+ * Expected Shortfall (Conditional VaR): average of returns below the (1-alpha) quantile.
+ *
+ * @returns The mean tail return (typically negative), or null on empty input.
+ */
+function calculateExpectedShortfall(returns, alpha) {
+    assertAlpha(alpha);
+    if (returns.length === 0)
+        return null;
+    assertFiniteArray$1("calculateExpectedShortfall", returns);
+    const sorted = [...returns].sort((a, b) => a - b);
+    const cutoff = Math.max(1, Math.floor((1 - alpha) * sorted.length));
+    const tail = sorted.slice(0, cutoff);
+    return tail.reduce((a, b) => a + b, 0) / tail.length;
+}
+/**
+ * Conditional Drawdown at Risk (CDaR): average of drawdowns in the worst (1-alpha) tail.
+ * Drawdowns are computed as (peak - equity) / peak so they are non-negative.
+ *
+ * @returns A non-negative magnitude (0 = no drawdowns), or null for fewer than 2 samples.
+ */
+function calculateConditionalDrawdown(equity, alpha) {
+    assertAlpha(alpha);
+    if (equity.length < 2)
+        return null;
+    assertFiniteArray$1("calculateConditionalDrawdown", equity);
+    let peak = equity[0];
+    const drawdowns = [];
+    for (const e of equity) {
+        if (e > peak)
+            peak = e;
+        drawdowns.push(peak > 0 ? (peak - e) / peak : 0);
+    }
+    if (drawdowns.every((d) => d === 0))
+        return 0;
+    const sorted = [...drawdowns].sort((a, b) => b - a); // descending (worst first)
+    const cutoff = Math.max(1, Math.floor((1 - alpha) * sorted.length));
+    const tail = sorted.slice(0, cutoff);
+    return tail.reduce((a, b) => a + b, 0) / tail.length;
+}
+/**
+ * Rolling-window drawdown series: for each index, drawdown = (current - rollingPeak) / rollingPeak.
+ * Non-positive values; 0 when at or above the rolling peak. Window measured in samples.
+ *
+ * @returns An array the same length as `equity`.
+ */
+function calculateRollingDrawdown(equity, windowSize) {
+    if (windowSize < 1 || !Number.isInteger(windowSize)) {
+        throw new Error("calculateRollingDrawdown: windowSize must be a positive integer");
+    }
+    assertFiniteArray$1("calculateRollingDrawdown", equity);
+    return equity.map((_, i) => {
+        const start = Math.max(0, i - windowSize + 1);
+        const slice = equity.slice(start, i + 1);
+        const peak = Math.max(...slice);
+        return peak > 0 ? (equity[i] - peak) / peak : 0;
+    });
+}
+/**
+ * Sortino ratio: (mean excess return) / downside deviation.
+ * Returns +Infinity when there are no downside returns.
+ * Returns null when fewer than 2 samples.
+ */
+function calculateSortino(returns, riskFreeRate) {
+    if (returns.length < 2)
+        return null;
+    assertFiniteArray$1("calculateSortino", returns);
+    const excess = returns.map((r) => r - riskFreeRate);
+    const meanExcess = excess.reduce((a, b) => a + b, 0) / excess.length;
+    const downside = excess.filter((r) => r < 0);
+    if (downside.length === 0)
+        return Number.POSITIVE_INFINITY;
+    const dd = Math.sqrt(downside.reduce((a, b) => a + b * b, 0) / downside.length);
+    return meanExcess / dd;
+}
+/**
+ * Calmar ratio: CAGR / |max drawdown|.
+ *
+ * @returns null when there is no drawdown (division by zero), fewer than 2 samples,
+ *          or `equity[0] <= 0` (CAGR undefined).
+ */
+function calculateCalmar(equity, periodsPerYear) {
+    if (equity.length < 2)
+        return null;
+    if (equity[0] <= 0)
+        return null;
+    if (periodsPerYear <= 0) {
+        throw new Error("calculateCalmar: periodsPerYear must be > 0");
+    }
+    assertFiniteArray$1("calculateCalmar", equity);
+    const total = equity[equity.length - 1] / equity[0];
+    const years = (equity.length - 1) / periodsPerYear;
+    const cagr = years > 0 ? Math.pow(total, 1 / years) - 1 : 0;
+    let peak = equity[0];
+    let maxDd = 0;
+    for (const e of equity) {
+        if (e > peak)
+            peak = e;
+        const dd = peak > 0 ? (peak - e) / peak : 0;
+        if (dd > maxDd)
+            maxDd = dd;
+    }
+    return maxDd === 0 ? null : cagr / maxDd;
+}
+/**
+ * Beasley-Springer-Moro approximation of the inverse standard normal CDF.
+ * Accurate to ~1e-9 across the full domain; sufficient for VaR work.
+ */
+function inverseStdNormal(p) {
+    if (p <= 0 || p >= 1)
+        throw new Error("p must be in (0,1)");
+    const a = [-39.69683028665376, 2.209460984245205e2, -275.9285104469687,
+        1.38357751867269e2, -30.66479806614716, 2.506628277459239];
+    const b = [-54.47609879822406, 1.615858368580409e2, -155.6989798598866,
+        6.680131188771972e1, -13.28068155288572];
+    const c = [-0.007784894002430293, -0.3223964580411365, -2.400758277161838,
+        -2.549732539343734, 4.374664141464968, 2.938163982698783];
+    const d = [7.784695709041462e-3, 3.224671290700398e-1, 2.445134137142996,
+        3.754408661907416];
+    const pLow = 0.02425;
+    const pHigh = 1 - pLow;
+    let q, r;
+    if (p < pLow) {
+        q = Math.sqrt(-2 * Math.log(p));
+        return (((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) /
+            ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1);
+    }
+    if (p <= pHigh) {
+        q = p - 0.5;
+        r = q * q;
+        return (((((a[0] * r + a[1]) * r + a[2]) * r + a[3]) * r + a[4]) * r + a[5]) * q /
+            (((((b[0] * r + b[1]) * r + b[2]) * r + b[3]) * r + b[4]) * r + 1);
+    }
+    q = Math.sqrt(-2 * Math.log(1 - p));
+    return -(((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) /
+        ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1);
+}
+
+var riskNs = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    calculateCalmar: calculateCalmar,
+    calculateConditionalDrawdown: calculateConditionalDrawdown,
+    calculateExpectedShortfall: calculateExpectedShortfall,
+    calculateRollingDrawdown: calculateRollingDrawdown,
+    calculateSortino: calculateSortino,
+    calculateVaRHistorical: calculateVaRHistorical,
+    calculateVaRParametric: calculateVaRParametric
+});
+
+/**
+ * Per-strategy rolling metrics and backtest-divergence z-score.
+ *
+ * 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.
+ * - All public functions reject non-finite inputs (NaN, Infinity) by throwing.
+ *   Callers must pre-validate or filter their inputs.
+ */
+function assertWindowSize(name, windowSize) {
+    if (windowSize < 1 || !Number.isInteger(windowSize)) {
+        throw new Error(`${name}: windowSize must be a positive integer`);
+    }
+}
+function assertFiniteArray(name, arr) {
+    for (let i = 0; i < arr.length; i++) {
+        if (!Number.isFinite(arr[i])) {
+            throw new Error(`${name}: input contains non-finite value at index ${i}: ${arr[i]}`);
+        }
+    }
+}
+/**
+ * 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.
+ * @throws When `windowSize` is not a positive integer or any input is non-finite.
+ */
+function calculateRollingExpectancy(tradePnls, windowSize) {
+    assertWindowSize("calculateRollingExpectancy", windowSize);
+    if (tradePnls.length < windowSize)
+        return null;
+    assertFiniteArray("calculateRollingExpectancy", tradePnls);
+    const slice = tradePnls.slice(-windowSize);
+    return slice.reduce((a, b) => a + b, 0) / windowSize;
+}
+/**
+ * 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.
+ * @throws When `windowSize` is not a positive integer or any input is non-finite.
+ */
+function calculateRollingHitRate(tradePnls, windowSize) {
+    assertWindowSize("calculateRollingHitRate", windowSize);
+    if (tradePnls.length < windowSize)
+        return null;
+    assertFiniteArray("calculateRollingHitRate", tradePnls);
+    const slice = tradePnls.slice(-windowSize);
+    const wins = slice.filter((p) => p > 0).length;
+    return wins / windowSize;
+}
+/**
+ * Rolling profit factor: sum(wins) / |sum(losses)| over the most-recent `windowSize` trades.
+ *
+ * Edge cases:
+ * - no losses and at least one win → +Infinity
+ * - no wins and no losses (all zeros) → 0
+ * - fewer than windowSize trades → null
+ *
+ * @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.
+ * @throws When `windowSize` is not a positive integer or any input is non-finite.
+ */
+function calculateRollingProfitFactor(tradePnls, windowSize) {
+    assertWindowSize("calculateRollingProfitFactor", windowSize);
+    if (tradePnls.length < windowSize)
+        return null;
+    assertFiniteArray("calculateRollingProfitFactor", tradePnls);
+    const slice = tradePnls.slice(-windowSize);
+    const wins = slice.filter((p) => p > 0).reduce((a, b) => a + b, 0);
+    const losses = slice.filter((p) => p < 0).reduce((a, b) => a + Math.abs(b), 0);
+    if (losses === 0)
+        return wins > 0 ? Number.POSITIVE_INFINITY : 0;
+    return wins / losses;
+}
+/**
+ * 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.
+ * @throws When `windowSize` is not a positive integer or any input is non-finite.
+ */
+function calculateRollingSortino(tradeReturns, windowSize, riskFreeRate = 0) {
+    assertWindowSize("calculateRollingSortino", windowSize);
+    if (tradeReturns.length < windowSize)
+        return null;
+    assertFiniteArray("calculateRollingSortino", tradeReturns);
+    return calculateSortino(tradeReturns.slice(-windowSize), riskFreeRate);
+}
+/**
+ * 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.
+ * @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.
+ */
+function calculateBacktestDivergenceZ(liveExpectancy, backtestExpectancy, backtestStddev) {
+    if (!Number.isFinite(liveExpectancy) || !Number.isFinite(backtestExpectancy) || !Number.isFinite(backtestStddev)) {
+        throw new Error("calculateBacktestDivergenceZ: inputs must be finite numbers");
+    }
+    if (backtestStddev <= 0) {
+        throw new Error("calculateBacktestDivergenceZ: stddev must be > 0");
+    }
+    return (liveExpectancy - backtestExpectancy) / backtestStddev;
+}
+
+var strategyNs = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    calculateBacktestDivergenceZ: calculateBacktestDivergenceZ,
+    calculateRollingExpectancy: calculateRollingExpectancy,
+    calculateRollingHitRate: calculateRollingHitRate,
+    calculateRollingProfitFactor: calculateRollingProfitFactor,
+    calculateRollingSortino: calculateRollingSortino
+});
+
 /**
  * Calculates Bollinger Bands for a given set of price data.
  * Bollinger Bands consist of a middle band (SMA) and two outer bands
@@ -11479,6 +12120,98 @@ var Types = /*#__PURE__*/Object.freeze({
     __proto__: null
 });
 
+/**
+ * Realized and EWMA volatility + regime classifier + annualisation helper.
+ * All functions pure.
+ */
+/**
+ * Sample standard deviation (Bessel-corrected) of returns over the most recent
+ * `window` samples.
+ * @returns null when fewer than `window` samples.
+ */
+function calculateRealizedVolatility(returns, window) {
+    if (window < 2 || !Number.isInteger(window)) {
+        throw new Error("calculateRealizedVolatility: window must be an integer >= 2");
+    }
+    if (returns.length < window)
+        return null;
+    const slice = returns.slice(-window);
+    const mean = slice.reduce((a, b) => a + b, 0) / window;
+    const variance = slice.reduce((a, b) => a + (b - mean) ** 2, 0) / (window - 1);
+    return Math.sqrt(variance);
+}
+/**
+ * EWMA volatility (RiskMetrics-style). λ ∈ (0,1); higher = longer memory.
+ * Default usage: λ = 0.94 for daily returns.
+ *
+ * For a single-element input, the function returns `|returns[0]|` (the seed)
+ * since no smoothing iterations are possible.
+ *
+ * @param returns - Period returns (e.g., log returns or simple returns).
+ * @param lambda - Decay factor in (0,1).
+ * @returns EWMA standard deviation, or null on empty input.
+ * @throws when `lambda` is outside (0,1).
+ */
+function calculateEWMAVolatility(returns, lambda) {
+    if (lambda <= 0 || lambda >= 1) {
+        throw new Error("calculateEWMAVolatility: lambda must be in (0,1)");
+    }
+    if (returns.length === 0)
+        return null;
+    let variance = returns[0] ** 2;
+    for (let i = 1; i < returns.length; i++) {
+        variance = lambda * variance + (1 - lambda) * returns[i] ** 2;
+    }
+    return Math.sqrt(variance);
+}
+/**
+ * Classify a volatility value into one of four regimes.
+ *
+ * Bands are checked in the order: crisis (≥crisisMin) → elevated (≥elevatedMax)
+ * → calm (≤calmMax) → normal (otherwise).
+ *
+ * @throws when bands are not strictly ordered (calmMax < elevatedMax < crisisMin).
+ */
+function detectVolatilityRegime(volatility, bands) {
+    if (!(bands.calmMax < bands.elevatedMax && bands.elevatedMax < bands.crisisMin)) {
+        throw new Error(`detectVolatilityRegime: bands must satisfy calmMax < elevatedMax < crisisMin (got ${JSON.stringify(bands)})`);
+    }
+    if (volatility >= bands.crisisMin)
+        return "crisis";
+    if (volatility >= bands.elevatedMax)
+        return "elevated";
+    if (volatility <= bands.calmMax)
+        return "calm";
+    return "normal";
+}
+/**
+ * Annualise a volatility computed at the given cadence by multiplying by
+ * the square root of the periods per year.
+ *
+ * - daily   → sqrt(252)              (252 trading days per year)
+ * - hourly  → sqrt(252 × 6.5)        (6.5 RTH hours per trading day)
+ * - minute  → sqrt(252 × 6.5 × 60)   (60 minutes per RTH hour)
+ *
+ * @param volatility - Per-period volatility (stddev).
+ * @param cadence - The cadence at which `volatility` was sampled.
+ * @returns The annualised volatility.
+ */
+function annualiseVolatility(volatility, cadence) {
+    switch (cadence) {
+        case "daily": return volatility * Math.sqrt(252);
+        case "hourly": return volatility * Math.sqrt(252 * 6.5);
+        case "minute": return volatility * Math.sqrt(252 * 6.5 * 60);
+    }
+}
+
+var volatilityNs = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    annualiseVolatility: annualiseVolatility,
+    calculateEWMAVolatility: calculateEWMAVolatility,
+    calculateRealizedVolatility: calculateRealizedVolatility,
+    detectVolatilityRegime: detectVolatilityRegime
+});
+
 var commonjsGlobal = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {};
 
 function getDefaultExportFromCjs (x) {
@@ -68697,6 +69430,10 @@ const createAlpacaMarketDataAPI = () => {
 };
 const adaptic = {
     types: Types,
+    atr: atrNs,
+    risk: riskNs,
+    strategy: strategyNs,
+    volatility: volatilityNs,
     backend: {
         fetchAssetOverview: fetchAssetOverview,
         getApolloClient: getSharedApolloClient,
@@ -68879,6 +69616,17 @@ const adaptic = {
         logIfDebug: logIfDebug,
         fetchWithRetry: fetchWithRetry,
         validateMassiveApiKey: validateMassiveApiKey,
+        /**
+         * Force-close a stuck-open per-host circuit breaker. Operator
+         * runbook utility — see {@link misc.resetCircuitBreaker}.
+         */
+        resetCircuitBreaker: resetCircuitBreaker,
+        /**
+         * Read-only snapshot of all per-host circuit-breaker states for
+         * use in operational-truth endpoints. See
+         * {@link misc.getCircuitBreakerSnapshot}.
+         */
+        getCircuitBreakerSnapshot: getCircuitBreakerSnapshot,
     },
     rateLimiter: {
         TokenBucketRateLimiter,
@@ -68917,6 +69665,7 @@ exports.AssetAllocationEngine = AssetAllocationEngine;
 exports.AuthenticationError = AuthenticationError;
 exports.BTC_PAIRS = BTC_PAIRS;
 exports.BarError = BarError;
+exports.CircuitOpenError = CircuitOpenError;
 exports.CryptoDataError = CryptoDataError;
 exports.CryptoOrderError = CryptoOrderError;
 exports.DEFAULT_CACHE_OPTIONS = DEFAULT_CACHE_OPTIONS;
@@ -68965,6 +69714,7 @@ exports.adptc = adptc;
 exports.alpaca = alpaca;
 exports.analyzeBars = analyzeBars;
 exports.approximateImpliedVolatility = approximateImpliedVolatility;
+exports.atr = atrNs;
 exports.bracketOrders = bracketOrders;
 exports.buildOCCSymbol = buildOCCSymbol;
 exports.buildOptionSymbol = buildOptionSymbol;
@@ -69147,6 +69897,7 @@ exports.protectShortPosition = protectShortPosition;
 exports.rateLimiters = rateLimiters;
 exports.resetLogger = resetLogger;
 exports.resetRiskFreeRateCache = resetRiskFreeRateCache;
+exports.risk = riskNs;
 exports.rollOptionPosition = rollOptionPosition;
 exports.roundPriceForAlpaca = roundPriceForAlpaca$3;
 exports.roundPriceForAlpacaNumber = roundPriceForAlpacaNumber;
@@ -69160,6 +69911,7 @@ exports.setLogger = setLogger;
 exports.setRiskFreeRate = setRiskFreeRate;
 exports.shortWithStopLoss = shortWithStopLoss;
 exports.sortOrdersByDate = sortOrdersByDate;
+exports.strategy = strategyNs;
 exports.tradingPolicy = index;
 exports.trailingStops = trailingStops;
 exports.updateAccountConfiguration = updateAccountConfiguration;
@@ -69170,6 +69922,7 @@ exports.validateMassiveApiKey = validateMassiveApiKey$1;
 exports.validateMultiLegOrder = validateMultiLegOrder;
 exports.validateResponse = validateResponse;
 exports.verifyFetchKeepAlive = verifyFetchKeepAlive;
+exports.volatility = volatilityNs;
 exports.waitForOrderFill = waitForOrderFill;
 exports.withRetry = withRetry;
 exports.withTimeout = withTimeout;