@adaptic/utils 0.0.1012 → 0.0.1014

package/dist/index.cjs

@@ -2212,11 +2212,20 @@ class AdapticUtilsError extends Error {
  */
 class AlpacaApiError extends AdapticUtilsError {
     statusCode;
-    constructor(message, code, statusCode, cause) {
+    brokerError;
+    constructor(message, code, statusCode, cause, 
+    /**
+     * Normalized Alpaca broker-rejection detail (numeric code + message + raw
+     * body), when the underlying rejection carried one. Additive and optional:
+     * synthetic errors and non-broker failures omit it, and every existing
+     * consumer of `message`/`code`/`statusCode`/`cause` is unaffected.
+     */
+    brokerError) {
         // Rate limit (429) and server errors (5xx) are retryable
         const isRetryable = statusCode === 429 || (statusCode !== undefined && statusCode >= 500);
         super(message, code, "alpaca", isRetryable, cause);
         this.statusCode = statusCode;
+        this.brokerError = brokerError;
     }
 }
 /**
@@ -2412,11 +2421,261 @@ class DuplicateClientOrderIdError extends AlpacaApiError {
     clientOrderId, 
     /** Whether the colliding id was derived by the wrapper (vs caller-supplied). */
     wasDerived, cause) {
-        super(message, "DUPLICATE_CLIENT_ORDER_ID", 422, cause);
+        // Carry the normalized broker payload forward from the original rejection
+        // (the `cause`) so a consumer can read the numeric code without re-parsing.
+        super(message, "DUPLICATE_CLIENT_ORDER_ID", 422, cause, extractAlpacaBrokerError(cause));
         this.clientOrderId = clientOrderId;
         this.wasDerived = wasDerived;
     }
 }
+/** Max depth walked along the `error.cause` chain when locating a broker payload. */
+const MAX_BROKER_ERROR_CAUSE_DEPTH = 6;
+/**
+ * Narrows an unknown value to an index-signature record so nested properties
+ * can be probed without an unsafe cast.
+ * @param value - The value to test.
+ * @returns true when the value is a non-null object.
+ */
+function isBrokerErrorRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Reads a finite number from an unknown value, accepting Alpaca's numeric
+ * `code` whether it arrives as a JSON number or a numeric string.
+ * @param value - The candidate value.
+ * @returns The number when finite, otherwise null.
+ */
+function asBrokerCode(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+/**
+ * Reads the axios/SDK-shaped broker payload from a SINGLE node's `response`
+ * field: an object `response.data` (`{ code, message }`) or a `response.data`
+ * left as an unparsed JSON string (the raw-`fetch` seams attach the body as a
+ * string). A known HTTP `response.status` is itself a broker-boundary signal —
+ * a `422` whose body carries no numeric code is still a `422` — so a
+ * status-only detail (`brokerCode: null`) is surfaced rather than discarded.
+ * Returns `undefined` only when the node carries no `response` and no status.
+ *
+ * @param node - The candidate error-like record.
+ * @returns The normalized detail, or undefined when the node has no response.
+ */
+function readResponseBrokerDetail(node) {
+    const response = node.response;
+    if (!isBrokerErrorRecord(response)) {
+        return undefined;
+    }
+    const statusCode = asBrokerCode(response.status);
+    // A known status with no structured code/message: preserve the status rather
+    // than discarding it (a code null is never fabricated into a value).
+    const statusOnly = statusCode === null
+        ? undefined
+        : { brokerCode: null, brokerMessage: null, statusCode, raw: response.data };
+    // Keep the raw body in its own const so the string narrowing survives the
+    // JSON.parse (a reassigned `let` would widen back to `unknown` in the catch).
+    const rawData = response.data;
+    let parsed = rawData;
+    if (typeof rawData === "string") {
+        try {
+            parsed = JSON.parse(rawData);
+        }
+        catch {
+            // A non-JSON string body carries a human reason but no structured code.
+            return { brokerCode: null, brokerMessage: rawData, statusCode, raw: rawData };
+        }
+    }
+    if (!isBrokerErrorRecord(parsed)) {
+        return statusOnly;
+    }
+    const brokerCode = asBrokerCode(parsed.code);
+    const brokerMessage = typeof parsed.message === "string" ? parsed.message : null;
+    if (brokerCode === null && brokerMessage === null) {
+        return statusOnly;
+    }
+    return { brokerCode, brokerMessage, statusCode, raw: rawData };
+}
+/**
+ * Reads the normalized broker detail from a SINGLE error-like node, without
+ * walking its `cause` chain. Recognizes two carriers on the node: an
+ * {@link AlpacaBrokerErrorDetail} already attached as `brokerError`, and an
+ * axios/SDK-shaped `response` body (object or unparsed JSON string). A carrier
+ * bearing a numeric code wins over a code-less one, so an enrichment that
+ * resolved no code never shadows a numeric code sitting in the same node's raw
+ * response body. Returns `undefined` when the node carries no broker payload,
+ * so absence is never converted into a fabricated code.
+ *
+ * @param node - The candidate error-like value.
+ * @returns The normalized detail, or undefined.
+ */
+function readBrokerDetailFromNode(node) {
+    if (!isBrokerErrorRecord(node)) {
+        return undefined;
+    }
+    // Carrier 1: a detail already normalized and attached by this module
+    // (e.g. AlpacaApiError.brokerError or a value enriched via enrichAlpacaError).
+    let attachedDetail;
+    const attached = node.brokerError;
+    if (isBrokerErrorRecord(attached) && "brokerCode" in attached) {
+        attachedDetail = {
+            brokerCode: asBrokerCode(attached.brokerCode),
+            brokerMessage: typeof attached.brokerMessage === "string"
+                ? attached.brokerMessage
+                : null,
+            statusCode: asBrokerCode(attached.statusCode),
+            raw: attached.raw,
+        };
+        // A numeric code on the attached detail is authoritative for this node.
+        if (attachedDetail.brokerCode !== null) {
+            return attachedDetail;
+        }
+    }
+    // Carrier 2: an axios/SDK-shaped `response` body on the same node. Prefer a
+    // numeric code found here over a code-less attached detail.
+    const responseDetail = readResponseBrokerDetail(node);
+    if (responseDetail?.brokerCode != null) {
+        return responseDetail;
+    }
+    return attachedDetail ?? responseDetail;
+}
+/**
+ * Extracts the normalized {@link AlpacaBrokerErrorDetail} from a thrown Alpaca
+ * SDK/axios error, reading the vendor payload at `error.response.data` and,
+ * failing that, walking the `error.cause` chain (the raw SDK error is preserved
+ * there once a wrapper has re-thrown). Returns `undefined` when no broker
+ * payload is present anywhere on the chain.
+ *
+ * Pure and outcome-independent: derived solely from Alpaca's documented error
+ * contract, with zero reference to realized P&L, fills, or account state.
+ *
+ * A node bearing a numeric broker code wins immediately; a code-less detail
+ * (status-only or message-only) found higher on the chain is held as a fallback
+ * while the walk continues, so a numeric code sitting deeper in the `cause`
+ * chain is never shadowed by a shallower code-less node — and when no code
+ * exists anywhere, the code-less detail is still returned rather than discarded.
+ *
+ * @param error - The thrown value.
+ * @returns The normalized broker detail, or undefined when none is present.
+ */
+function extractAlpacaBrokerError(error) {
+    let current = error;
+    let fallback;
+    for (let depth = 0; depth < MAX_BROKER_ERROR_CAUSE_DEPTH && current != null; depth++) {
+        const detail = readBrokerDetailFromNode(current);
+        if (detail !== undefined) {
+            if (detail.brokerCode !== null) {
+                return detail;
+            }
+            if (fallback === undefined) {
+                fallback = detail;
+            }
+        }
+        if (!isBrokerErrorRecord(current)) {
+            break;
+        }
+        current = current.cause;
+    }
+    return fallback;
+}
+/**
+ * Returns the normalized {@link AlpacaBrokerErrorDetail} for a thrown error, or
+ * `null` when the error carries no Alpaca broker payload. The typed
+ * vendor-boundary replacement for reaching into `err.response.data` downstream.
+ *
+ * @param error - The thrown value.
+ * @returns The normalized detail, or null.
+ */
+function getAlpacaBrokerErrorDetail(error) {
+    return extractAlpacaBrokerError(error) ?? null;
+}
+/**
+ * Returns Alpaca's machine-readable numeric broker error code from a thrown
+ * error (walking the `cause` chain), or `null` when absent. The typed
+ * replacement for `err.message.includes("42210000")`:
+ *
+ * ```typescript
+ * if (getAlpacaBrokerErrorCode(err) === 42210000) { ... } // stale-order reject
+ * ```
+ *
+ * The code resolves uniformly across every vendor seam: the SDK/axios path
+ * (where `response.data` rides along for free) and the raw-`fetch` paths — the
+ * `AlpacaTradingAPI` class `makeRequest` and the legacy order helpers, which
+ * throw via {@link alpacaHttpError} so the verbatim status + body are carried as
+ * a typed `.response`. A consumer branching on the stale-order `42210000` gets
+ * the same answer regardless of which seam produced the reject, including the
+ * dominant percent-trailing-stop tighten path where a plain `Error` previously
+ * dropped the broker payload.
+ *
+ * @param error - The thrown value.
+ * @returns The numeric broker code, or null.
+ */
+function getAlpacaBrokerErrorCode(error) {
+    return extractAlpacaBrokerError(error)?.brokerCode ?? null;
+}
+/**
+ * Additively enriches a thrown error with the normalized Alpaca broker detail
+ * extracted from `source` (the original SDK/axios rejection), WITHOUT changing
+ * the target's `message`, `name`, or prototype. It:
+ *
+ *  - sets `target.cause = source` when the target has no cause yet, so the raw
+ *    rejection (and its `response.data`) is never lost down the wrapper chain;
+ *  - attaches the normalized {@link AlpacaBrokerErrorDetail} as
+ *    `target.brokerError` when `source` carried a broker payload.
+ *
+ * Purely additive by construction: a caller writes
+ * `throw enrichAlpacaError(new Error(msg), error)` and every consumer that read
+ * `error.message` or `error instanceof Error` before reads the identical value
+ * after, while new consumers can call {@link getAlpacaBrokerErrorCode}. This is
+ * the restoration for the dropped-`response.data` defect (Alpaca `42210000` /
+ * `40310000` reaching consumers only as a lossy "status code NNN" string).
+ *
+ * @param target - The wrapper error about to be thrown.
+ * @param source - The original rejection to normalize and preserve.
+ * @returns The same `target`, typed to expose the optional `brokerError`.
+ */
+function enrichAlpacaError(target, source) {
+    const enriched = target;
+    if (enriched.cause === undefined && source !== undefined) {
+        enriched.cause = source;
+    }
+    const detail = extractAlpacaBrokerError(source);
+    if (detail !== undefined) {
+        enriched.brokerError = detail;
+    }
+    return enriched;
+}
+/**
+ * Builds a thrown-ready `Error` for a raw-`fetch` Alpaca rejection, carrying the
+ * verbatim HTTP status + body as a typed `.response` so that
+ * {@link getAlpacaBrokerErrorCode} / {@link extractAlpacaBrokerError} resolve
+ * the numeric broker code on the `fetch` seams (the `AlpacaTradingAPI` class
+ * `makeRequest` and the legacy functional order helpers) exactly as they
+ * already do on the SDK seam — where the SDK/axios error carries `response.data`
+ * for free but a hand-thrown `new Error(...)` does not.
+ *
+ * Purely additive by construction: the `.message` is caller-supplied and
+ * returned byte-identical (so message string-matching consumers are
+ * unaffected), the returned value `instanceof Error` still holds, and only the
+ * `.response` surface is added. The `data` is the raw string body exactly as
+ * `response.text()` returned it — {@link extractAlpacaBrokerError} parses a
+ * JSON-string body itself, so no vendor payload is lost or reshaped here.
+ *
+ * @param message - The error message, thrown verbatim (never rewritten).
+ * @param status - The HTTP status the rejection arrived on.
+ * @param body - The raw response body (`response.text()`), preserved verbatim.
+ * @returns An `Error` whose `.response` exposes `{ status, data: body }`.
+ */
+function alpacaHttpError(message, status, body) {
+    return Object.assign(new Error(message), {
+        response: { status, data: body },
+    });
+}
 
 const DEFAULT_RETRY_CONFIG = {
     maxRetries: 3,
@@ -5296,7 +5555,13 @@ class AlpacaTradingAPI {
                 this.log(`Alpaca API error (${response.status}): ${errorText}`, {
                     type: "error",
                 });
-                throw new Error(`Alpaca API error (${response.status}): ${errorText}`);
+                // Additive broker-error preservation: the message is byte-identical
+                // (existing "422"/"42210000" string-matching consumers are unaffected),
+                // and the verbatim status + body ride along as a typed `.response` so
+                // getAlpacaBrokerErrorCode resolves the numeric code on this fetch seam —
+                // the dominant percent-trailing-stop tighten path and the 08-20 defect
+                // site, where a plain Error dropped the broker's response.data.
+                throw alpacaHttpError(`Alpaca API error (${response.status}): ${errorText}`, response.status, errorText);
             }
             // Handle responses with no content (e.g., 204 No Content)
             if (response.status === 204 ||
@@ -5681,7 +5946,10 @@ class AlpacaTradingAPI {
                 this.log(`Order ${orderId} is not cancelable`, {
                     type: "error",
                 });
-                throw new Error(`Order ${orderId} is not cancelable`);
+                // Re-message stays byte-identical; the broker payload from makeRequest's
+                // `.response` is carried onto the new error so the numeric code survives
+                // this wrapper instead of being dropped at the re-throw.
+                throw enrichAlpacaError(new Error(`Order ${orderId} is not cancelable`), error);
             }
             // Re-throw other errors
             throw error;
@@ -6731,7 +6999,7 @@ async function makeRequest(auth, params) {
             source: "AlpacaAPI",
             type: "error",
         });
-        throw new Error(`Alpaca API error (${response.status}): ${errorText}`);
+        throw alpacaHttpError(`Alpaca API error (${response.status}): ${errorText}`, response.status, errorText);
     }
     catch (err) {
         const error = err;
@@ -6764,7 +7032,7 @@ async function createOrder$1(auth, params) {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`Failed to create order: ${response.status} ${response.statusText} ${errorText}`);
+            throw alpacaHttpError(`Failed to create order: ${response.status} ${response.statusText} ${errorText}`, response.status, errorText);
         }
         return (await response.json());
     }
@@ -6811,7 +7079,7 @@ async function getOrders$1(auth, params = {}) {
             });
             if (!response.ok) {
                 const errorText = await response.text();
-                throw new Error(`Failed to get orders: ${response.status} ${response.statusText} ${errorText}`);
+                throw alpacaHttpError(`Failed to get orders: ${response.status} ${response.statusText} ${errorText}`, response.status, errorText);
             }
             const orders = (await response.json());
             allOrders.push(...orders);
@@ -6872,7 +7140,7 @@ async function cancelAllOrders$1(auth) {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`Failed to cancel orders: ${response.status} ${response.statusText} ${errorText}`);
+            throw alpacaHttpError(`Failed to cancel orders: ${response.status} ${response.statusText} ${errorText}`, response.status, errorText);
         }
         return (await response.json());
     }
@@ -6905,7 +7173,7 @@ async function getOrder$1(auth, orderId, nested) {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`Failed to get order: ${response.status} ${response.statusText} ${errorText}`);
+            throw alpacaHttpError(`Failed to get order: ${response.status} ${response.statusText} ${errorText}`, response.status, errorText);
         }
         return (await response.json());
     }
@@ -6938,7 +7206,7 @@ async function replaceOrder$1(auth, orderId, params) {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`Failed to replace order: ${response.status} ${response.statusText} ${errorText}`);
+            throw alpacaHttpError(`Failed to replace order: ${response.status} ${response.statusText} ${errorText}`, response.status, errorText);
         }
         return (await response.json());
     }
@@ -6971,7 +7239,7 @@ async function cancelOrder$1(auth, orderId) {
                 return { success: false, message: `Order not found: ${orderId}` };
             }
             else {
-                throw new Error(`Failed to cancel order: ${response.status} ${response.statusText} ${errorText}`);
+                throw alpacaHttpError(`Failed to cancel order: ${response.status} ${response.statusText} ${errorText}`, response.status, errorText);
             }
         }
         return { success: true };
@@ -11415,7 +11683,13 @@ async function calculateMaxDrawdown$1(tradeBars, isShort) {
             peak = positionAwareEquity[i];
         }
         else {
-            const drawdown = peak <= 0 ? 0 : (peak - positionAwareEquity[i]) / Math.abs(peak);
+            // The short branch negates equity, so its peak is legitimately negative.
+            // Scale the decline by the peak's magnitude — a sign test on the peak
+            // would discard every drawdown on one side of the book.
+            const denominator = Math.abs(peak);
+            const drawdown = denominator === 0
+                ? 0
+                : (peak - positionAwareEquity[i]) / denominator;
             if (drawdown > maxDrawdown) {
                 maxDrawdown = drawdown;
             }
@@ -11428,17 +11702,71 @@ async function calculateExpenseRatio$1(trade) {
     const totalFees = await computeTotalFees(trade);
     return totalFees ? `${totalFees.toFixed(2)}%` : "N/A";
 }
+/**
+ * Resolves whether a trade is short from its primary action.
+ *
+ * Only an outright BUY or SELL fixes whether the position's P&L runs with or
+ * against the price series. Option legs, exercises, cancels, adjustments and
+ * hedges do not, and `trade.actions` itself is curated by backend-legacy
+ * selection-set directives, so its absence is routine. Every one of those
+ * cases leaves the direction genuinely unknown, and unknown is returned as
+ * such — inferring a side would silently invert every direction-aware metric
+ * computed from it.
+ *
+ * @param trade - Trade whose direction is being resolved
+ * @returns `true` for a short, `false` for a long, `null` when unresolvable
+ */
+function resolveIsShort(trade) {
+    const primaryAction = trade.actions?.find((action) => action.primary);
+    if (!primaryAction) {
+        getLogger().warn(`Trade ${trade.id} has no primary action; position direction is unresolved.`);
+        return null;
+    }
+    switch (primaryAction.type) {
+        case "SELL":
+            return true;
+        case "BUY":
+            return false;
+        default:
+            getLogger().warn(`Trade ${trade.id} primary action type "${primaryAction.type}" does not determine a long/short direction.`);
+            return null;
+    }
+}
 // Main function to fetch and calculate all trade metrics for one trade object
 async function fetchTradeMetrics(trade, tradeBars, benchmarkBars) {
-    const isShort = trade.actions?.find((a) => a.primary)?.type === "SELL" ? true : false;
+    const isShort = resolveIsShort(trade);
+    // The Sharpe ratio and the expense ratio do not invert on direction, so they
+    // are started immediately and stay concurrent with everything below.
+    const riskAdjustedReturnPromise = calculateRiskAdjustedReturn$1(tradeBars);
+    const expenseRatioPromise = calculateExpenseRatio$1(trade);
+    if (isShort === null) {
+        // Every other metric inverts on direction. With the direction unknown
+        // there is no value to report — only a sign-ambiguous one — so they are
+        // reported as unavailable rather than resolved by assumption.
+        const [riskAdjustedReturn, expenseRatio] = await Promise.all([
+            riskAdjustedReturnPromise,
+            expenseRatioPromise,
+        ]);
+        return {
+            totalReturnYTD: "N/A",
+            alpha: "N/A",
+            beta: "N/A",
+            alphaAnnualized: "N/A",
+            informationRatio: "N/A",
+            riskAdjustedReturn,
+            expenseRatio,
+            maxDrawdown: "N/A",
+            side: "N/A",
+        };
+    }
     // Calculate metrics concurrently
-    const [totalReturnYTD, { alpha, beta, alphaAnnualized }, informationRatio, riskAdjustedReturn, expenseRatio, maxDrawdown,] = await Promise.all([
+    const [totalReturnYTD, { alpha, beta, alphaAnnualized }, informationRatio, maxDrawdown, riskAdjustedReturn, expenseRatio,] = await Promise.all([
         calculateProfitLoss(tradeBars, isShort),
         calculateAlphaAndBeta$1(tradeBars, benchmarkBars, isShort),
         calculateInformationRatio$1(tradeBars, benchmarkBars, isShort),
-        calculateRiskAdjustedReturn$1(tradeBars),
-        calculateExpenseRatio$1(trade),
         calculateMaxDrawdown$1(tradeBars, isShort),
+        riskAdjustedReturnPromise,
+        expenseRatioPromise,
     ]);
     return {
         totalReturnYTD,
@@ -12802,6 +13130,66 @@ var strategyNs = /*#__PURE__*/Object.freeze({
     calculateRollingSortino: calculateRollingSortino
 });
 
+/**
+ * Round a PRICE-scale indicator output to a precision derived from its own
+ * magnitude, rather than a hardcoded 2 decimal places.
+ *
+ * A flat `toFixed(2)` silently destroys every sub-penny price — a $0.0003
+ * microcap's bands collapse to `0.00`, and a MACD histogram of a low-priced
+ * name rounds to nothing (F7.2). Precision must scale with the price: values at
+ * or above $1 keep the conventional 2dp, while sub-dollar values keep ~4
+ * significant figures so the number survives its own scale. Non-finite inputs
+ * pass through untouched — totality of the underlying value is the caller's
+ * responsibility, this helper only quantises.
+ *
+ * The `>= $1` branch delegates to `toFixed(2)` rather than re-deriving it as
+ * `Math.round(value * 100) / 100`. The two disagree wherever the intermediate
+ * `value * 100` rounds onto an exact `.5` that the decimal value sits just
+ * below (`1.045` → `1.05` vs `1.04`), which would make this helper shift
+ * ordinary dollar prices by a cent — a behaviour change well outside repairing
+ * sub-penny collapse. Delegating keeps the common case byte-identical to the
+ * historical output by construction, which matters because the same function
+ * computes indicators for unit tests, backtests, paper and live.
+ *
+ * @param value - A price-scale indicator output (band, EMA, MACD component).
+ * @returns The value rounded to a scale-appropriate precision.
+ */
+function roundToPriceScale(value) {
+    if (!Number.isFinite(value))
+        return value;
+    const abs = Math.abs(value);
+    if (abs === 0)
+        return 0;
+    if (abs >= 1)
+        return parseFloat(value.toFixed(2));
+    // Sub-dollar: decimals = leading zeros after the point + 4 significant figures,
+    // capped so the factor stays within safe-integer range.
+    const decimals = Math.min(12, Math.ceil(-Math.log10(abs)) + 4);
+    const factor = 10 ** decimals;
+    return Math.round(value * factor) / factor;
+}
+/**
+ * Relative Strength Index from average gain / average loss, total on the
+ * degenerate flat window.
+ *
+ * When a window has no losses the Wilder ratio `avgGain / avgLoss` is
+ * `+Infinity` (→ RSI 100); on a perfectly flat window it is `0 / 0 = NaN`,
+ * which the naive formula propagates straight into the output. A flat window
+ * carries no momentum, so its RSI is the neutral 50 — never NaN. This mirrors
+ * the engine's live RSI guards (a constant series scores neutral, an all-gains
+ * series scores 100).
+ *
+ * @param avgGain - Average gain over the period (>= 0).
+ * @param avgLoss - Average loss over the period (>= 0).
+ * @returns RSI in [0, 100]; 50 for a flat window, 100 for an all-gains window.
+ */
+function rsiFromAverages(avgGain, avgLoss) {
+    if (avgLoss === 0)
+        return avgGain === 0 ? 50 : 100;
+    const rs = avgGain / avgLoss;
+    const rsi = 100 - 100 / (1 + rs);
+    return Number.isFinite(rsi) ? rsi : 50;
+}
 /**
  * Calculates Bollinger Bands for a given set of price data.
  * Bollinger Bands consist of a middle band (SMA) and two outer bands
@@ -12834,9 +13222,9 @@ function calculateBollingerBands(priceData, { period = 20, standardDeviations =
         const lowerBand = sma - standardDeviation * standardDeviations;
         result.push({
             date: priceData[i].date,
-            middle: parseFloat(sma.toFixed(2)),
-            upper: parseFloat(upperBand.toFixed(2)),
-            lower: parseFloat(lowerBand.toFixed(2)),
+            middle: roundToPriceScale(sma),
+            upper: roundToPriceScale(upperBand),
+            lower: roundToPriceScale(lowerBand),
             close: priceData[i].close,
         });
     }
@@ -12878,11 +13266,11 @@ function calculateEMA(priceData, { period = 20, period2 = 9 } = {}) {
     // Add first EMA(s)
     const firstEntry = {
         date: priceData[Math.max(period, period2 || 0) - 1].date,
-        ema: parseFloat(prevEMA.toFixed(2)),
+        ema: roundToPriceScale(prevEMA),
         close: priceData[Math.max(period, period2 || 0) - 1].close,
     };
     if (period2) {
-        firstEntry.ema2 = parseFloat(prevEMA2.toFixed(2));
+        firstEntry.ema2 = roundToPriceScale(prevEMA2);
     }
     result.push(firstEntry);
     // Calculate EMA for remaining periods
@@ -12892,18 +13280,55 @@ function calculateEMA(priceData, { period = 20, period2 = 9 } = {}) {
         prevEMA = currentEMA;
         const entry = {
             date: priceData[i].date,
-            ema: parseFloat(currentEMA.toFixed(2)),
+            ema: roundToPriceScale(currentEMA),
             close: currentClose,
         };
         if (period2) {
             const currentEMA2 = (currentClose - prevEMA2) * multiplier2 + prevEMA2;
             prevEMA2 = currentEMA2;
-            entry.ema2 = parseFloat(currentEMA2.toFixed(2));
+            entry.ema2 = roundToPriceScale(currentEMA2);
         }
         result.push(entry);
     }
     return result;
 }
+/**
+ * Locates a window's swing extremes and derives the direction of its most
+ * recent leg from the order in which those extremes print.
+ *
+ * A Fibonacci construction is anchored to the latest leg: an up-leg runs swing
+ * low to swing high, a down-leg swing high to swing low. Whichever extreme
+ * prints last therefore identifies the leg, which makes the direction a
+ * measurement of the window rather than a caller's assumption. When both
+ * extremes land on the same bar the window contains no leg and the direction
+ * is genuinely indeterminate.
+ *
+ * @param window - The lookback slice to analyse.
+ * @returns The window's swing extremes and derived leg direction.
+ */
+function analyzeSwingWindow(window) {
+    let swingHigh = -Infinity;
+    let swingLow = Infinity;
+    let highIndex = -1;
+    let lowIndex = -1;
+    // `>=` / `<=` keep the most recent occurrence of each extreme, which is the
+    // one the current leg is measured from.
+    for (let i = 0; i < window.length; i++) {
+        if (window[i].high >= swingHigh) {
+            swingHigh = window[i].high;
+            highIndex = i;
+        }
+        if (window[i].low <= swingLow) {
+            swingLow = window[i].low;
+            lowIndex = i;
+        }
+    }
+    return {
+        swingHigh,
+        swingLow,
+        trend: highIndex === lowIndex ? null : highIndex > lowIndex ? "uptrend" : "downtrend",
+    };
+}
 /**
  * Calculates Fibonacci retracement and extension levels based on price data.
  * Fibonacci levels are used to identify potential support and resistance levels.
@@ -12913,43 +13338,55 @@ function calculateEMA(priceData, { period = 20, period2 = 9 } = {}) {
  * @param params.lookbackPeriod - The number of periods to look back for swing high/low (default is 20).
  * @param params.retracementLevels - An array of retracement levels to calculate (default is [0.236, 0.382, 0.5, 0.618, 0.786]).
  * @param params.extensionLevels - An array of extension levels to calculate (default is [1.272, 1.618, 2.618]).
- * @param params.reverseDirection - A boolean indicating if the trend is reversed (default is false).
+ * @param params.reverseDirection - Forces the leg direction: `true` for a downtrend, `false` for an uptrend. Omit it to derive the direction per bar from the swing window.
  * @returns An array of FibonacciData objects containing the calculated levels.
  */
-function calculateFibonacciLevels(priceData, { lookbackPeriod = 20, retracementLevels = [0.236, 0.382, 0.5, 0.618, 0.786], extensionLevels = [1.272, 1.618, 2.618], reverseDirection = false, } = {}) {
+function calculateFibonacciLevels(priceData, { lookbackPeriod = 20, retracementLevels = [0.236, 0.382, 0.5, 0.618, 0.786], extensionLevels = [1.272, 1.618, 2.618], reverseDirection, } = {}) {
     const result = [];
     for (let i = 0; i < priceData.length; i++) {
         const periodSlice = priceData.slice(Math.max(0, i - lookbackPeriod + 1), i + 1);
-        const swingHigh = Math.max(...periodSlice.map((d) => d.high));
-        const swingLow = Math.min(...periodSlice.map((d) => d.low));
+        const { swingHigh, swingLow, trend: derivedTrend } = analyzeSwingWindow(periodSlice);
         const priceRange = swingHigh - swingLow;
-        const trend = reverseDirection ? "downtrend" : "uptrend";
+        // An explicit `reverseDirection` is the caller stating the leg it is
+        // measuring; absent that, the leg is read off the window itself.
+        const trend = reverseDirection === undefined
+            ? derivedTrend
+            : reverseDirection
+                ? "downtrend"
+                : "uptrend";
         const levels = [];
-        if (priceRange > 0) {
+        if (priceRange > 0 && trend !== null) {
+            const isDowntrend = trend === "downtrend";
             // Calculate retracement levels
             retracementLevels.forEach((level) => {
-                const price = reverseDirection
+                const price = isDowntrend
                     ? swingLow + priceRange * level
                     : swingHigh - priceRange * level;
                 levels.push({
                     level,
-                    price: parseFloat(price.toFixed(2)),
+                    price: roundToPriceScale(price),
                     type: "retracement",
                 });
             });
-            // Calculate extension levels
+            // Calculate extension levels — each is projected beyond the leg's
+            // terminal extreme: past the swing low for a down-leg, past the swing
+            // high for an up-leg. Anchoring both to the same extreme would place one
+            // side's targets a full swing range away from where the leg is running.
             extensionLevels.forEach((level) => {
-                const price = reverseDirection
-                    ? swingHigh - priceRange * (level - 1) // For downtrend
+                const price = isDowntrend
+                    ? swingLow - priceRange * (level - 1) // For downtrend
                     : swingHigh + priceRange * (level - 1); // For uptrend
                 levels.push({
                     level,
-                    price: parseFloat(price.toFixed(2)),
+                    price: roundToPriceScale(price),
                     type: "extension",
                 });
             });
             // Sort levels by price
-            levels.sort((a, b) => reverseDirection ? b.price - a.price : a.price - b.price);
+            levels.sort((a, b) => isDowntrend ? b.price - a.price : a.price - b.price);
+        }
+        else if (trend === null) {
+            logIfDebug(`Swing high and low fall on the same bar on date ${priceData[i].date}; trend is indeterminate and no levels calculated.`);
         }
         else {
             logIfDebug(`Price range is zero on date ${priceData[i].date}; no levels calculated.`);
@@ -13004,9 +13441,9 @@ function calculateMACD(priceData, { shortPeriod = 12, longPeriod = 26, signalPer
         const hist = macdValue - signalEMA;
         result.push({
             date: emaLong[i].date, // Use emaLong's date for alignment
-            macd: parseFloat(macdValue.toFixed(2)),
-            signal: parseFloat(signalEMA.toFixed(2)),
-            histogram: parseFloat(hist.toFixed(2)),
+            macd: roundToPriceScale(macdValue),
+            signal: roundToPriceScale(signalEMA),
+            histogram: roundToPriceScale(hist),
             close: emaLong[i].close,
         });
     }
@@ -13041,9 +13478,9 @@ function calculateRSI(priceData, { period = 14 } = {}) {
     }
     avgGain = avgGain / period;
     avgLoss = avgLoss / period;
-    // Calculate RSI for the first period
-    let rs = avgGain / avgLoss;
-    let rsi = 100 - 100 / (1 + rs);
+    // Calculate RSI for the first period (total on a flat window — see
+    // rsiFromAverages: a constant series scores the neutral 50, never NaN).
+    let rsi = rsiFromAverages(avgGain, avgLoss);
     result.push({
         date: priceData[period].date,
         rsi: parseFloat(rsi.toFixed(2)),
@@ -13057,8 +13494,7 @@ function calculateRSI(priceData, { period = 14 } = {}) {
         // Use smoothed averages
         avgGain = (avgGain * (period - 1) + gain) / period;
         avgLoss = (avgLoss * (period - 1) + loss) / period;
-        rs = avgGain / avgLoss;
-        rsi = 100 - 100 / (1 + rs);
+        rsi = rsiFromAverages(avgGain, avgLoss);
         result.push({
             date: priceData[i].date,
             rsi: parseFloat(rsi.toFixed(2)),
@@ -13079,6 +13515,20 @@ function calculateRSI(priceData, { period = 14 } = {}) {
  * @returns An array of StochData objects containing the calculated %K and %D values.
  */
 function calculateStochasticOscillator(priceData, { lookbackPeriod = 5, signalPeriod = 3, smoothingFactor = 3, } = {}) {
+    // Each period is a divisor (`kSum / min(len, smoothingFactor)`) and a slice
+    // width. A zero or fractional period therefore divides by zero or slices an
+    // empty window, producing NaN/Infinity %K and %D — an oscillator reading that
+    // is never true and never false. The periods are caller-supplied constants
+    // rather than market data, so an invalid one is a programming error and is
+    // reported as such, matching the ATR and volatility primitives.
+    if (!Number.isInteger(lookbackPeriod) ||
+        lookbackPeriod < 1 ||
+        !Number.isInteger(signalPeriod) ||
+        signalPeriod < 1 ||
+        !Number.isInteger(smoothingFactor) ||
+        smoothingFactor < 1) {
+        throw new Error("calculateStochasticOscillator: lookbackPeriod, signalPeriod and smoothingFactor must be positive integers");
+    }
     if (priceData.length < lookbackPeriod) {
         logIfDebug(`Insufficient data for Stochastic Oscillator calculation: required periods: ${lookbackPeriod}, but only received ${priceData.length} periods of data`);
         return [];
@@ -13119,6 +13569,48 @@ function calculateStochasticOscillator(priceData, { lookbackPeriod = 5, signalPe
     }
     return result;
 }
+/**
+ * Collapses a cluster of nearby pivots into one volume-weighted level, or
+ * reports that the cluster evidences no level at all.
+ *
+ * Both outputs are volume-weighted: the price is the volume-weighted mean of
+ * the cluster's pivots, and the strength is the pivot count weighted by each
+ * pivot's share of cluster volume. That weighting is undefined when the cluster
+ * transacted no volume — `0 / 0` makes both NaN. A NaN level is strictly worse
+ * than no level: every comparison against NaN is false, so a stop or target
+ * placed off one is silently never triggered, leaving the position unprotected
+ * while appearing protected.
+ *
+ * Zero cluster volume is a real market state rather than corrupt input — halted,
+ * pre-market-thin and synthetic warm-up bars all report it. A support or
+ * resistance level means price transacted enough there to turn the market, so a
+ * cluster with no volume has not evidenced one. `SupportResistanceLevel` types
+ * both fields as non-optional numbers, which leaves omitting the level as the
+ * only honest way to say so.
+ *
+ * @param cluster - The nearby pivots to collapse into a single level.
+ * @param currentPrice - The bar's close, which classifies the level's side.
+ * @returns The aggregated level, or null when the cluster evidences none.
+ */
+function aggregatePivotCluster(cluster, currentPrice) {
+    const totalVolume = cluster.reduce((sum, p) => sum + p.volume, 0);
+    // Negated `> 0` so NaN and negative totals are rejected alongside zero: no
+    // volume weighting survives any of them.
+    if (!(totalVolume > 0))
+        return null;
+    const avgPrice = cluster.reduce((sum, p) => sum + p.price * p.volume, 0) / totalVolume;
+    const strength = cluster.reduce((sum, p) => sum + p.count * (p.volume / totalVolume), 0);
+    if (!Number.isFinite(avgPrice) || !Number.isFinite(strength))
+        return null;
+    return {
+        // The level is a price, so its precision follows the price's magnitude
+        // (F7.2). Strength is a count-weighted score rather than a price and keeps
+        // the conventional 2dp.
+        price: roundToPriceScale(avgPrice),
+        strength: parseFloat(strength.toFixed(2)),
+        type: avgPrice > currentPrice ? "resistance" : "support",
+    };
+}
 /**
  * Calculates support and resistance levels based on price data.
  * Support and resistance levels are price levels at which a stock tends to stop and reverse.
@@ -13139,9 +13631,22 @@ function calculateSupportAndResistance(priceData, { maxLevels = 5, lookbackPerio
         const priceChanges = analysisWindow
             .slice(1)
             .map((bar, idx) => Math.abs(bar.close - analysisWindow[idx].close));
-        const avgPriceChange = priceChanges.reduce((sum, change) => sum + change, 0) /
-            priceChanges.length;
-        const volatility = avgPriceChange / analysisWindow[0].close; // Relative volatility
+        // A single-bar window produces no price changes to average, and a
+        // non-positive reference close cannot scale one — `0 / 0` and `x / 0` make
+        // the relative volatility NaN or Infinity. Volatility is the sole input to
+        // both the pivot sensitivity and the level-grouping gap below, so a
+        // non-finite value silently disables every comparison that depends on it
+        // (each is false against NaN). Unmeasurable volatility resolves to zero,
+        // under which each pivot stands as its own level instead of being merged on
+        // a meaningless ratio.
+        const referenceClose = analysisWindow[0].close;
+        const avgPriceChange = priceChanges.length > 0
+            ? priceChanges.reduce((sum, change) => sum + change, 0) /
+                priceChanges.length
+            : 0;
+        const volatility = referenceClose > 0 && Number.isFinite(avgPriceChange)
+            ? avgPriceChange / referenceClose
+            : 0; // Relative volatility
         // **Adjust Sensitivity and minGapBetweenLevels Dynamically**
         const sensitivity = volatility * 2; // Adjust the multiplier as needed
         const minGapBetweenLevels = volatility * 100; // Convert to percentage
@@ -13150,8 +13655,16 @@ function calculateSupportAndResistance(priceData, { maxLevels = 5, lookbackPerio
             const curr = analysisWindow[j];
             const prevBar = analysisWindow[j - 1];
             const nextBar = analysisWindow[j + 1];
+            // A pivot is matched against existing candidates by a *relative* gap
+            // measured against its own price, so a non-positive reference price makes
+            // that ratio meaningless: zero divides to NaN or Infinity (which never
+            // compares below the sensitivity, so the pivot never merges), and a
+            // negative price inverts the comparison (so everything merges). A bar
+            // without a positive high or low carries no tradeable level either way.
             // Check for high pivot
-            if (curr.high > prevBar.high && curr.high > nextBar.high) {
+            if (curr.high > 0 &&
+                curr.high > prevBar.high &&
+                curr.high > nextBar.high) {
                 const existingPivot = pivotPoints.find((p) => Math.abs(p.price - curr.high) / curr.high < sensitivity);
                 if (existingPivot) {
                     existingPivot.count++;
@@ -13162,7 +13675,7 @@ function calculateSupportAndResistance(priceData, { maxLevels = 5, lookbackPerio
                 }
             }
             // Check for low pivot
-            if (curr.low < prevBar.low && curr.low < nextBar.low) {
+            if (curr.low > 0 && curr.low < prevBar.low && curr.low < nextBar.low) {
                 const existingPivot = pivotPoints.find((p) => Math.abs(p.price - curr.low) / curr.low < sensitivity);
                 if (existingPivot) {
                     existingPivot.count++;
@@ -13192,33 +13705,17 @@ function calculateSupportAndResistance(priceData, { maxLevels = 5, lookbackPerio
                 }
                 else {
                     // Process current group
-                    if (currentGroup.length > 0) {
-                        const totalVolume = currentGroup.reduce((sum, p) => sum + p.volume, 0);
-                        const avgPrice = currentGroup.reduce((sum, p) => sum + p.price * p.volume, 0) /
-                            totalVolume;
-                        const totalStrength = currentGroup.reduce((sum, p) => sum + p.count * (p.volume / totalVolume), 0);
-                        levels.push({
-                            price: parseFloat(avgPrice.toFixed(2)),
-                            strength: parseFloat(totalStrength.toFixed(2)),
-                            type: avgPrice > currentPrice ? "resistance" : "support",
-                        });
-                    }
+                    const level = aggregatePivotCluster(currentGroup, currentPrice);
+                    if (level)
+                        levels.push(level);
                     currentGroup = [pivotPoints[j]];
                 }
             }
         }
         // Process final group
-        if (currentGroup.length > 0) {
-            const totalVolume = currentGroup.reduce((sum, p) => sum + p.volume, 0);
-            const avgPrice = currentGroup.reduce((sum, p) => sum + p.price * p.volume, 0) /
-                totalVolume;
-            const totalStrength = currentGroup.reduce((sum, p) => sum + p.count * (p.volume / totalVolume), 0);
-            levels.push({
-                price: parseFloat(avgPrice.toFixed(2)),
-                strength: parseFloat(totalStrength.toFixed(2)),
-                type: avgPrice > currentPrice ? "resistance" : "support",
-            });
-        }
+        const finalGroupLevel = aggregatePivotCluster(currentGroup, currentPrice);
+        if (finalGroupLevel)
+            levels.push(finalGroupLevel);
         // Sort by strength and limit
         const finalLevels = levels
             .sort((a, b) => b.strength - a.strength)
@@ -51971,7 +52468,8 @@ async function createBracketOrder(executor, params) {
  *
  * @example
  * ```typescript
- * // Add protection to an existing long position
+ * // Add protection to an existing long position (sell to close):
+ * // take profit above, stop below.
  * const result = await createProtectiveBracket(
  *   executor,
  *   {
@@ -51984,6 +52482,23 @@ async function createBracketOrder(executor, params) {
  *   }
  * );
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Add protection to an existing short position (buy to close):
+ * // take profit below, stop above.
+ * const result = await createProtectiveBracket(
+ *   executor,
+ *   {
+ *     symbol: 'TSLA',
+ *     qty: 50,
+ *     side: 'buy',
+ *     takeProfit: { limitPrice: 200.00 },
+ *     stopLoss: { stopPrice: 260.00 },
+ *     timeInForce: 'gtc',
+ *   }
+ * );
+ * ```
  */
 async function createProtectiveBracket(executor, params) {
     log$j(`Creating protective bracket for ${params.symbol}: ${params.qty} shares`, { type: "info" });
@@ -51996,15 +52511,28 @@ async function createProtectiveBracket(executor, params) {
     if (!params.qty || params.qty <= 0) {
         throw new Error("Quantity must be a positive number");
     }
+    // The closing side determines which of the two exit prices is the profit
+    // target, so it must be stated rather than inferred.
+    if (params.side !== "buy" && params.side !== "sell") {
+        throw new Error("Protective bracket requires a side of 'buy' or 'sell' matching the position being closed");
+    }
     if (!params.takeProfit?.limitPrice || params.takeProfit.limitPrice <= 0) {
         throw new Error("Take profit limit price is required and must be positive");
     }
     if (!params.stopLoss?.stopPrice || params.stopLoss.stopPrice <= 0) {
         throw new Error("Stop loss stop price is required and must be positive");
     }
-    // For a protective sell bracket, take profit should be higher than stop loss
-    if (params.takeProfit.limitPrice <= params.stopLoss.stopPrice) {
-        log$j("Warning: Take profit price should be higher than stop loss price for protective sell bracket", { type: "warn" });
+    // The take profit must sit on the profitable side of the position and the
+    // stop on the losing side. Which price is the higher one therefore depends
+    // on the closing side: selling to close a long takes profit above and stops
+    // below; buying to close a short is the exact mirror.
+    if (params.side === "sell") {
+        if (params.takeProfit.limitPrice <= params.stopLoss.stopPrice) {
+            log$j("Warning: Take profit price should be higher than stop loss price for protective sell bracket", { type: "warn" });
+        }
+    }
+    else if (params.takeProfit.limitPrice >= params.stopLoss.stopPrice) {
+        log$j("Warning: Take profit price should be lower than stop loss price for protective buy bracket", { type: "warn" });
     }
     try {
         // Build the OCO order parameters
@@ -53634,7 +54162,7 @@ async function createTrailingStop(client, params) {
         log$g(`Trailing stop creation failed for ${params.symbol}: ${err.message}`, {
             type: "error",
         });
-        throw new Error(`Failed to create trailing stop for ${params.symbol}: ${err.message}`);
+        throw enrichAlpacaError(new Error(`Failed to create trailing stop for ${params.symbol}: ${err.message}`), error);
     }
 }
 /**
@@ -53700,7 +54228,11 @@ async function updateTrailingStop(client, orderId, updates) {
         log$g(`Trailing stop update failed for ${orderId}: ${err.message}`, {
             type: "error",
         });
-        throw new Error(`Failed to update trailing stop ${orderId}: ${err.message}`);
+        // Preserve Alpaca's `response.data` (numeric code `42210000` etc.) that the
+        // SDK reduces to a bare "status code NNN" message. This is THE trailing-stop
+        // modify path; dropping the code here left the consumer unable to tell a
+        // stale-order reject from a benign race, blind-failing the profit lock.
+        throw enrichAlpacaError(new Error(`Failed to update trailing stop ${orderId}: ${err.message}`), error);
     }
 }
 /**
@@ -53741,7 +54273,7 @@ async function getTrailingStopHWM(client, orderId) {
         log$g(`Failed to get trailing stop HWM for ${orderId}: ${err.message}`, {
             type: "error",
         });
-        throw new Error(`Failed to get trailing stop HWM for ${orderId}: ${err.message}`);
+        throw enrichAlpacaError(new Error(`Failed to get trailing stop HWM for ${orderId}: ${err.message}`), error);
     }
 }
 /**
@@ -53770,19 +54302,22 @@ async function cancelTrailingStop(client, orderId) {
             log$g(`Trailing stop ${orderId} is not cancelable (may already be filled or canceled)`, {
                 type: "warn",
             });
-            throw new Error(`Trailing stop ${orderId} is not cancelable: order may already be filled or canceled`);
+            throw enrichAlpacaError(new Error(`Trailing stop ${orderId} is not cancelable: order may already be filled or canceled`), error);
         }
         log$g(`Failed to cancel trailing stop ${orderId}: ${err.message}`, {
             type: "error",
         });
-        throw new Error(`Failed to cancel trailing stop ${orderId}: ${err.message}`);
+        throw enrichAlpacaError(new Error(`Failed to cancel trailing stop ${orderId}: ${err.message}`), error);
     }
 }
 /**
- * Create trailing stops for all positions in a portfolio
+ * Create trailing stops for every position in a portfolio
  *
- * This function creates trailing stop orders for all long positions in the portfolio,
- * which is useful for applying blanket downside protection. Short positions are skipped.
+ * Applies blanket adverse-move protection across the book. The protective side
+ * is derived per position from the signed quantity reported by the broker — a
+ * long is protected by a trailing sell, a short by a trailing buy — so a
+ * position is never left unprotected because of the direction it happens to
+ * hold.
  *
  * @param client - AlpacaClient instance
  * @param params - Configuration for portfolio-wide trailing stops
@@ -53807,8 +54342,11 @@ async function createPortfolioTrailingStops(client, params) {
     if (params.trailPercent <= 0) {
         throw new Error("trailPercent must be greater than 0");
     }
-    if (params.trailPercent > 100) {
-        throw new Error("trailPercent cannot exceed 100");
+    // Reject against the broker's real ceiling up front. A looser outer bound
+    // lets an out-of-range value reach the per-position loop, where every single
+    // submission is rejected and the book silently ends up unprotected.
+    if (params.trailPercent > ALPACA_MAX_TRAIL_PERCENT) {
+        throw new Error(`trailPercent cannot exceed ${ALPACA_MAX_TRAIL_PERCENT} (Alpaca API limit)`);
     }
     const sdk = client.getSDK();
     const results = new Map();
@@ -53831,19 +54369,21 @@ async function createPortfolioTrailingStops(client, params) {
                 log$g(`Skipping ${symbol} (excluded)`, { type: "debug" });
                 continue;
             }
-            // Only create trailing stops for long positions
+            // Derive the protective side from the broker's signed quantity: a long
+            // (qty > 0) is closed by selling, a short (qty < 0) by buying. Direction
+            // is read from the position, never assumed — a stop on the wrong side
+            // doubles the exposure it was meant to cap.
             const qty = parseFloat(position.qty);
-            if (qty <= 0) {
-                log$g(`Skipping ${symbol} (not a long position, qty: ${qty})`, {
-                    type: "debug",
-                });
+            if (!Number.isFinite(qty) || qty === 0) {
+                log$g(`Skipping ${symbol}: position qty "${position.qty}" is not a usable non-zero number`, { type: "warn" });
                 continue;
             }
+            const side = qty > 0 ? "sell" : "buy";
             try {
                 const order = await createTrailingStop(client, {
                     symbol,
                     qty: Math.abs(qty),
-                    side: "sell",
+                    side,
                     trailPercent: params.trailPercent,
                     timeInForce: params.timeInForce || "gtc",
                 });
@@ -53851,9 +54391,14 @@ async function createPortfolioTrailingStops(client, params) {
             }
             catch (err) {
                 const errorMessage = err.message;
-                errors.push({ symbol, error: errorMessage });
+                // Preserve the broker's numeric code (e.g. 42210000) rather than
+                // reducing the swallowed per-item failure to its flattened message —
+                // this loop only logs failures, so the log is the preservation target.
+                const brokerCode = getAlpacaBrokerErrorCode(err);
+                errors.push({ symbol, error: errorMessage, brokerCode });
                 log$g(`Failed to create trailing stop for ${symbol}: ${errorMessage}`, {
                     type: "error",
+                    metadata: { brokerCode },
                 });
             }
         }
@@ -53863,7 +54408,9 @@ async function createPortfolioTrailingStops(client, params) {
         const skippedCount = positions.length - successCount - failureCount;
         log$g(`Portfolio trailing stops complete: ${successCount} created, ${failureCount} failed, ${skippedCount} skipped`, { type: "info" });
         if (errors.length > 0) {
-            log$g(`Failed symbols: ${errors.map((e) => `${e.symbol} (${e.error})`).join(", ")}`, {
+            log$g(`Failed symbols: ${errors
+                .map((e) => `${e.symbol} (${e.error}${e.brokerCode !== null ? `, code ${e.brokerCode}` : ""})`)
+                .join(", ")}`, {
                 type: "warn",
             });
         }
@@ -53874,7 +54421,7 @@ async function createPortfolioTrailingStops(client, params) {
         log$g(`Failed to create portfolio trailing stops: ${err.message}`, {
             type: "error",
         });
-        throw new Error(`Failed to create portfolio trailing stops: ${err.message}`);
+        throw enrichAlpacaError(new Error(`Failed to create portfolio trailing stops: ${err.message}`), error);
     }
 }
 /**
@@ -53913,7 +54460,7 @@ async function getOpenTrailingStops(client, symbol) {
     catch (error) {
         const err = error;
         log$g(`Failed to get open trailing stops: ${err.message}`, { type: "error" });
-        throw new Error(`Failed to get open trailing stops: ${err.message}`);
+        throw enrichAlpacaError(new Error(`Failed to get open trailing stops: ${err.message}`), error);
     }
 }
 /**
@@ -53961,7 +54508,10 @@ async function cancelTrailingStopsForSymbol(client, symbol) {
             canceledCount++;
         }
         catch (err) {
-            errors.push(`${order.id}: ${err.message}`);
+            // Keep the broker's numeric code alongside the message so the swallowed
+            // per-item cancel failure stays diagnosable in the summary log.
+            const brokerCode = getAlpacaBrokerErrorCode(err);
+            errors.push(`${order.id}: ${err.message}${brokerCode !== null ? ` (code ${brokerCode})` : ""}`);
         }
     }
     if (errors.length > 0) {
@@ -54781,13 +55331,25 @@ async function shortWithStopLoss(client, symbol, qty, entryPrice, stopLossPrice)
  * @param qty - Number of shares
  * @param entryPrice - Limit price for entry (null for market)
  * @param stopLossPercent - Stop loss percentage (e.g., 5 for 5%)
- * @param side - Order side ('buy' or 'sell')
+ * @param side - Order side ('buy' or 'sell'). Required: the entry direction is
+ *   the caller's decision, and a default would open a position in a direction
+ *   nobody chose.
  *
  * @example
  * // Buy AAPL at $150 with 3% stop loss (stop at $145.50)
  * const result = await entryWithPercentStopLoss(client, 'AAPL', 100, 150.00, 3, 'buy');
+ *
+ * @example
+ * // Short GOOGL at $140 with 3% stop loss (stop at $144.20)
+ * const result = await entryWithPercentStopLoss(client, 'GOOGL', 10, 140.00, 3, 'sell');
  */
-async function entryWithPercentStopLoss(client, symbol, qty, entryPrice, stopLossPercent, side = "buy") {
+async function entryWithPercentStopLoss(client, symbol, qty, entryPrice, stopLossPercent, side) {
+    // Guard the direction at runtime as well as in the signature: every price
+    // below is computed off `side`, so an unsupplied one would silently place
+    // the stop on the wrong side of the entry.
+    if (side !== "buy" && side !== "sell") {
+        throw new Error("entryWithPercentStopLoss requires an explicit side of 'buy' or 'sell'; the entry direction cannot be inferred");
+    }
     if (stopLossPercent <= 0 || stopLossPercent >= 100) {
         throw new Error("stopLossPercent must be between 0 and 100");
     }
@@ -58186,7 +58748,12 @@ async function resolveDuplicateSubmission(client, clientOrderId, symbol, cause)
     catch (lookupError) {
         const reason = lookupError instanceof Error ? lookupError.message : String(lookupError);
         log$6(`Duplicate-order lookup failed for ${clientOrderId}; failing closed (no resubmit): ${reason}`, { type: "error", symbol, metadata: { clientOrderId } });
-        throw new DuplicateClientOrderIdError(`Duplicate client_order_id "${clientOrderId}" rejected by Alpaca and the existing-order lookup failed; refusing to resubmit (possible live duplicate)`, clientOrderId, false, lookupError);
+        // The typed error represents the ORIGINAL duplicate rejection, so its broker
+        // payload must come from `cause` (the 422), not from the lookup failure.
+        // Chain the lookup error ahead of the original 422 (and carry the 422's
+        // normalized detail onto it) so both are diagnosable and
+        // getAlpacaBrokerErrorCode still resolves the duplicate code.
+        throw new DuplicateClientOrderIdError(`Duplicate client_order_id "${clientOrderId}" rejected by Alpaca and the existing-order lookup failed; refusing to resubmit (possible live duplicate)`, clientOrderId, false, enrichAlpacaError(lookupError instanceof Error ? lookupError : new Error(reason), cause));
     }
     if (existing && !TERMINAL_DEAD_ORDER_STATUSES.has(existing.status)) {
         log$6(`client_order_id ${clientOrderId} already submitted (status=${existing.status}); returning existing order ${existing.id} as idempotent success`, {
@@ -58320,7 +58887,7 @@ async function createOrder(client, params) {
             symbol,
             metadata: { params: submission },
         });
-        throw new Error(`Failed to create ${type} order for ${symbol}: ${errorMessage}`);
+        throw enrichAlpacaError(new Error(`Failed to create ${type} order for ${symbol}: ${errorMessage}`), error);
     }
 }
 /**
@@ -58349,7 +58916,7 @@ async function getOrder(client, orderId) {
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : "Unknown error";
         log$6(`Failed to fetch order ${orderId}: ${errorMessage}`, { type: "error" });
-        throw new Error(`Failed to fetch order ${orderId}: ${errorMessage}`);
+        throw enrichAlpacaError(new Error(`Failed to fetch order ${orderId}: ${errorMessage}`), error);
     }
 }
 /**
@@ -58412,7 +58979,7 @@ async function getOrders(client, params = {}) {
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : "Unknown error";
         log$6(`Failed to fetch orders: ${errorMessage}`, { type: "error" });
-        throw new Error(`Failed to fetch orders: ${errorMessage}`);
+        throw enrichAlpacaError(new Error(`Failed to fetch orders: ${errorMessage}`), error);
     }
 }
 /**
@@ -58442,16 +59009,16 @@ async function cancelOrder(client, orderId) {
             log$6(`Order ${orderId} is not cancelable (may already be filled or canceled)`, {
                 type: "warn",
             });
-            throw new Error(`Order ${orderId} is not cancelable`);
+            throw enrichAlpacaError(new Error(`Order ${orderId} is not cancelable`), error);
         }
         if (errorMessage.includes("404") || errorMessage.includes("not found")) {
             log$6(`Order ${orderId} not found`, { type: "error" });
-            throw new Error(`Order ${orderId} not found`);
+            throw enrichAlpacaError(new Error(`Order ${orderId} not found`), error);
         }
         log$6(`Failed to cancel order ${orderId}: ${errorMessage}`, {
             type: "error",
         });
-        throw new Error(`Failed to cancel order ${orderId}: ${errorMessage}`);
+        throw enrichAlpacaError(new Error(`Failed to cancel order ${orderId}: ${errorMessage}`), error);
     }
 }
 /**
@@ -58494,7 +59061,7 @@ async function cancelAllOrders(client) {
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : "Unknown error";
         log$6(`Failed to cancel all orders: ${errorMessage}`, { type: "error" });
-        throw new Error(`Failed to cancel all orders: ${errorMessage}`);
+        throw enrichAlpacaError(new Error(`Failed to cancel all orders: ${errorMessage}`), error);
     }
 }
 /**
@@ -58552,16 +59119,16 @@ async function replaceOrder(client, orderId, params) {
             log$6(`Order ${orderId} cannot be replaced (may already be filled)`, {
                 type: "error",
             });
-            throw new Error(`Order ${orderId} cannot be replaced: order may already be filled or canceled`);
+            throw enrichAlpacaError(new Error(`Order ${orderId} cannot be replaced: order may already be filled or canceled`), error);
         }
         if (errorMessage.includes("404")) {
             log$6(`Order ${orderId} not found`, { type: "error" });
-            throw new Error(`Order ${orderId} not found`);
+            throw enrichAlpacaError(new Error(`Order ${orderId} not found`), error);
         }
         log$6(`Failed to replace order ${orderId}: ${errorMessage}`, {
             type: "error",
         });
-        throw new Error(`Failed to replace order ${orderId}: ${errorMessage}`);
+        throw enrichAlpacaError(new Error(`Failed to replace order ${orderId}: ${errorMessage}`), error);
     }
 }
 /**
@@ -58650,7 +59217,7 @@ async function getOrderByClientId(client, clientOrderId) {
         log$6(`Failed to fetch order by client_order_id ${clientOrderId}: ${errorMessage}`, {
             type: "error",
         });
-        throw new Error(`Failed to fetch order by client_order_id ${clientOrderId}: ${errorMessage}`);
+        throw enrichAlpacaError(new Error(`Failed to fetch order by client_order_id ${clientOrderId}: ${errorMessage}`), error);
     }
 }
 
@@ -64851,6 +65418,15 @@ class AssetAllocationEngine {
      * Assess current market condition
      */
     assessMarketCondition(metrics) {
+        // Crisis detection runs first: it is the strictly more severe reading and
+        // its volatility threshold sits above the high-volatility one, so testing
+        // volatility first would classify every crisis-level VIX as merely high
+        // and never reach this branch at all.
+        if (metrics.volatilityIndex > 40 ||
+            metrics.sentimentScore < 20 ||
+            metrics.creditSpread > 500) {
+            return "CRISIS";
+        }
         // High volatility check
         if (metrics.volatilityIndex > 30) {
             return "HIGH_VOLATILITY";
@@ -64859,12 +65435,6 @@ class AssetAllocationEngine {
         if (metrics.volatilityIndex < 12) {
             return "LOW_VOLATILITY";
         }
-        // Crisis detection
-        if (metrics.volatilityIndex > 40 ||
-            metrics.sentimentScore < 20 ||
-            metrics.creditSpread > 500) {
-            return "CRISIS";
-        }
         // Bull market
         if (metrics.trendDirection === "UP" &&
             metrics.marketStrength > 60 &&
@@ -71160,6 +71730,14 @@ const DEFAULT_TRADING_POLICY = EffectiveTradingPolicySchema.parse({
     optionsEnabled: true,
     futuresEnabled: true,
     forexEnabled: true,
+    // Shorting and margin are capability opt-ins, not a directional stance.
+    // Both require a margin agreement and locate/borrow availability the
+    // package cannot verify, so an account that has not asserted the
+    // capability defaults to the one it is known to have. This is a statement
+    // about account permissions, never a preference for long over short — the
+    // side a strategy takes is derived from live data once the capability is
+    // enabled. Resolve these from the broker account's actual margin and
+    // shorting entitlements wherever those are available.
     shortingEnabled: false,
     marginEnabled: false,
     fractionalSharesEnabled: true,
@@ -71599,8 +72177,10 @@ exports.createTimeoutSignal = createTimeoutSignal;
 exports.createTrailingStop = createTrailingStop;
 exports.createVerticalSpread = createVerticalSpread$1;
 exports.createVerticalSpreadAdvanced = createVerticalSpread;
+exports.enrichAlpacaError = enrichAlpacaError;
 exports.entryWithPercentStopLoss = entryWithPercentStopLoss;
 exports.exerciseOption = exerciseOption;
+exports.extractAlpacaBrokerError = extractAlpacaBrokerError;
 exports.extractGreeks = extractGreeks;
 exports.filterByExpiration = filterByExpiration;
 exports.filterByStrike = filterByStrike;
@@ -71618,6 +72198,8 @@ exports.getAccountDetails = getAccountDetails;
 exports.getAccountSummary = getAccountSummary;
 exports.getAgentPoolStatus = getAgentPoolStatus;
 exports.getAllOrders = getAllOrders;
+exports.getAlpacaBrokerErrorCode = getAlpacaBrokerErrorCode;
+exports.getAlpacaBrokerErrorDetail = getAlpacaBrokerErrorDetail;
 exports.getAlpacaCalendar = getAlpacaCalendar;
 exports.getAlpacaClock = getAlpacaClock;
 exports.getAverageDailyVolume = getAverageDailyVolume;