@adaptic/utils 0.0.1006 → 0.0.1008

package/dist/index.cjs

@@ -2276,6 +2276,80 @@ function isTransientNetworkError(error) {
     }
     return false;
 }
+/**
+ * Error names that indicate the CLIENT's own request deadline expired (an
+ * `AbortSignal` timeout or an undici per-phase timeout) rather than a
+ * connection-phase fault. These faults have already consumed a full request
+ * timeout, so retrying them is expensive by construction.
+ */
+const DEADLINE_EXPIRY_ERROR_NAMES = new Set([
+    "AbortError",
+    "TimeoutError",
+    "RequestTimeoutError",
+    "ConnectTimeoutError",
+    "HeadersTimeoutError",
+    "BodyTimeoutError",
+]);
+/**
+ * Error codes that indicate an expired request/phase deadline (vs a fast
+ * connection-phase fault such as `ECONNRESET`/`ECONNREFUSED`).
+ */
+const DEADLINE_EXPIRY_ERROR_CODES = new Set([
+    "ETIMEDOUT",
+    "ESOCKETTIMEDOUT",
+    "ECONNABORTED",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+]);
+/** Message-pattern fallback for deadline-expiry errors that lost name/code. */
+const DEADLINE_EXPIRY_MESSAGE_PATTERNS = [
+    /timed out/i,
+    /timeout/i,
+    /aborted/i,
+];
+/**
+ * Whether an error represents the client's OWN deadline expiring (abort /
+ * timeout) rather than a connection-phase network fault. Both classes are
+ * "transient" per {@link isTransientNetworkError}, but they have very
+ * different retry economics: a connection fault (`ECONNRESET`, `EPIPE`,
+ * refused socket) settles in milliseconds and is cheap to retry, while a
+ * deadline expiry has already consumed the full per-attempt timeout — blindly
+ * retrying it multiplies time-to-failure exactly when the caller most needs
+ * to fail fast. Walks the `error.cause` chain like the transient classifier.
+ *
+ * @param error - The error to classify.
+ * @returns true when the fault is a client deadline/abort expiry.
+ */
+function isClientDeadlineExpiry(error) {
+    const MAX_CAUSE_DEPTH = 6;
+    let current = error;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH && current; depth++) {
+        if (current instanceof Error || typeof current === "object") {
+            const err = current;
+            if (typeof err.name === "string" &&
+                DEADLINE_EXPIRY_ERROR_NAMES.has(err.name)) {
+                return true;
+            }
+            if (typeof err.code === "string" &&
+                DEADLINE_EXPIRY_ERROR_CODES.has(err.code)) {
+                return true;
+            }
+            if (typeof err.message === "string") {
+                for (const pattern of DEADLINE_EXPIRY_MESSAGE_PATTERNS) {
+                    if (pattern.test(err.message)) {
+                        return true;
+                    }
+                }
+            }
+            current = err.cause;
+        }
+        else {
+            break;
+        }
+    }
+    return false;
+}
 /**
  * Analyzes an error and determines if it's retryable.
  * @param error - The error to analyze
@@ -2803,6 +2877,33 @@ class DataFormatError extends AdapticUtilsError {
         this.service = service;
     }
 }
+/**
+ * Broker-side duplicate `client_order_id` rejection (Alpaca HTTP 422,
+ * "client order id must be unique").
+ *
+ * Thrown by the order-creation paths of `AlpacaTradingAPI` so callers can
+ * distinguish "this exact order was already submitted" from a genuine order
+ * rejection. When {@link wasDerived} is `false` the id was caller-supplied and
+ * the caller owns idempotency semantics (a legitimate repeat needs a new
+ * explicit id or an `idempotencyNonce`). When `true`, the wrapper's automatic
+ * recovery (existing-order lookup, then one salted resubmit) was exhausted.
+ *
+ * Never retryable with the same id — resubmitting the identical
+ * `client_order_id` will 422 again.
+ */
+class DuplicateClientOrderIdError extends AlpacaApiError {
+    clientOrderId;
+    wasDerived;
+    constructor(message, 
+    /** The `client_order_id` that collided broker-side. */
+    clientOrderId, 
+    /** Whether the colliding id was derived by the wrapper (vs caller-supplied). */
+    wasDerived, cause) {
+        super(message, "DUPLICATE_CLIENT_ORDER_ID", 422, cause);
+        this.clientOrderId = clientOrderId;
+        this.wasDerived = wasDerived;
+    }
+}
 
 /**
  * Token bucket rate limiter for external API integrations
@@ -2900,8 +3001,11 @@ class TokenBucketRateLimiter {
     async acquire() {
         const logger = getLogger();
         this.refill();
-        if (this.tokens > 0) {
-            this.tokens--;
+        // Require a WHOLE token: refill() accrues fractionally, and admitting on
+        // any positive fraction would release a full request per accrual tick,
+        // driving the bucket negative and overrunning the configured rate.
+        if (this.tokens >= TOKENS_PER_REQUEST) {
+            this.tokens -= TOKENS_PER_REQUEST;
             logger.debug(`Rate limit token acquired for ${this.config.label}`, {
                 remainingTokens: this.tokens,
                 queueLength: this.queue.length,
@@ -2997,8 +3101,9 @@ class TokenBucketRateLimiter {
         this.processingQueue = true;
         const logger = getLogger();
         try {
-            while (this.queue.length > 0 && this.tokens > 0) {
-                this.tokens--;
+            // Whole-token admission — see the matching guard in acquire().
+            while (this.queue.length > 0 && this.tokens >= TOKENS_PER_REQUEST) {
+                this.tokens -= TOKENS_PER_REQUEST;
                 const next = this.queue.shift();
                 if (next) {
                     clearTimeout(next.timeoutHandle);
@@ -3160,6 +3265,23 @@ function transientRetryDelayMs(attempt) {
     const ceiling = TRANSIENT_NETWORK_RETRY_BASE_MS * 2 ** attempt;
     return Math.floor(Math.random() * ceiling);
 }
+/**
+ * Total-deadline multiple over the per-attempt client timeout for one
+ * {@link AlpacaMarketDataAPI.makeRequest} call INCLUDING transient retries.
+ * The ECONNRESET class this loop targets settles in milliseconds, so the
+ * retries fit comfortably inside 1.5x the single-attempt timeout — while a
+ * request whose attempts each consume the full client timeout is refused
+ * further retries instead of stretching a hot-path read to a multi-minute
+ * stall (worst case before this budget: 3 x (60s limiter wait + 30s fetch)).
+ */
+const TRANSIENT_RETRY_BUDGET_TIMEOUT_MULTIPLE = 1.5;
+/**
+ * Maximum retries for a fault classified as the client's OWN deadline expiry
+ * (see {@link isClientDeadlineExpiry}): such a fault already consumed a full
+ * per-attempt timeout, so it is retried at most once — and then only if the
+ * total budget still allows a further full-length attempt.
+ */
+const CLIENT_DEADLINE_EXPIRY_MAX_RETRIES = 1;
 const log$l = (message, options = { type: "info" }) => {
     log$m(message, { ...options, source: "AlpacaMarketDataAPI" });
 };
@@ -3673,7 +3795,15 @@ class AlpacaMarketDataAPI extends require$$0$1.EventEmitter {
             // Retry ONLY transient connection faults, and only on GET (every
             // market-data read here is idempotent). A non-2xx response is a real
             // answer from Alpaca and is never retried — that path still throws on
-            // the first attempt exactly as before.
+            // the first attempt exactly as before. The whole loop is bounded by a
+            // cumulative deadline so retries can never stretch a hot-path read far
+            // beyond a single attempt's timeout: connection-phase faults
+            // (ECONNRESET class, millisecond-scale) retry cheaply, while a fault
+            // that consumed the full client timeout retries at most once and only
+            // when the remaining budget still fits a full-length attempt.
+            const retryLoopStartedAt = Date.now();
+            const totalBudgetMs = Math.round(DEFAULT_TIMEOUTS.ALPACA_API * TRANSIENT_RETRY_BUDGET_TIMEOUT_MULTIPLE);
+            let deadlineExpiryRetries = 0;
             let response;
             let lastNetworkError;
             for (let attempt = 0; attempt < TRANSIENT_NETWORK_RETRY_ATTEMPTS; attempt += 1) {
@@ -3687,12 +3817,21 @@ class AlpacaMarketDataAPI extends require$$0$1.EventEmitter {
                 }
                 catch (networkErr) {
                     lastNetworkError = networkErr;
+                    const deadlineExpiry = isClientDeadlineExpiry(networkErr);
+                    const nextAttemptFitsBudget = Date.now() - retryLoopStartedAt + DEFAULT_TIMEOUTS.ALPACA_API <=
+                        totalBudgetMs;
                     const retryable = method === "GET" &&
                         isTransientNetworkError(networkErr) &&
-                        attempt < TRANSIENT_NETWORK_RETRY_ATTEMPTS - 1;
+                        attempt < TRANSIENT_NETWORK_RETRY_ATTEMPTS - 1 &&
+                        nextAttemptFitsBudget &&
+                        (!deadlineExpiry ||
+                            deadlineExpiryRetries < CLIENT_DEADLINE_EXPIRY_MAX_RETRIES);
                     if (!retryable) {
                         throw networkErr;
                     }
+                    if (deadlineExpiry) {
+                        deadlineExpiryRetries += 1;
+                    }
                     const delayMs = transientRetryDelayMs(attempt);
                     log$l(`Transient network fault on ${endpoint} (attempt ${attempt + 1}/${TRANSIENT_NETWORK_RETRY_ATTEMPTS}); retrying in ${delayMs}ms`, { type: "warn" });
                     await new Promise((resolve) => setTimeout(resolve, delayMs));
@@ -3713,8 +3852,7 @@ class AlpacaMarketDataAPI extends require$$0$1.EventEmitter {
                 });
                 throw new Error(`Market Data API error (${response.status}): ${errorText}`);
             }
-            const data = await response.json();
-            return data;
+            return (await response.json());
         }
         catch (err) {
             const error = err;
@@ -4401,7 +4539,7 @@ class AlpacaMarketDataAPI extends require$$0$1.EventEmitter {
                 });
                 throw new Error(`Alpaca news API error (${response.status}): ${errorText}`);
             }
-            const data = await response.json();
+            const data = (await response.json());
             if (!data.news || !Array.isArray(data.news)) {
                 log$l(`No news data found in Alpaca response for ${symbol}`, {
                     type: "warn",
@@ -4484,9 +4622,45 @@ const CLIENT_ORDER_ID_HASH_LENGTH = 32;
  * This derived default is a best-effort safety net; the guaranteed-idempotent
  * path is for the caller to pass an explicit `clientOrderId` tied to the
  * originating signal/decision id (which also permits legitimately-repeated
- * identical orders inside a single window).
+ * identical orders inside a single window). Callers that intentionally repeat
+ * an identical order inside one window without managing explicit ids can pass
+ * an `idempotencyNonce` (e.g. an attempt counter or signal id) instead — the
+ * nonce is folded into the derived id, so each distinct nonce yields a
+ * distinct id while a timeout+retry of the SAME attempt still collides
+ * broker-side as intended.
+ *
+ * When a DERIVED id is 422-rejected as a duplicate, {@link
+ * AlpacaTradingAPI.postOrderWithIdempotencyRecovery} recovers instead of
+ * failing the caller: if the previously-submitted order is still live (or
+ * filled) it is returned as idempotent success; if it is terminally dead
+ * (canceled/expired/rejected) the order is resubmitted exactly once with a
+ * fresh random salt. Caller-SUPPLIED ids are never recovered — they surface a
+ * typed {@link DuplicateClientOrderIdError} so the caller can distinguish a
+ * duplicate from a genuine rejection.
  */
 const CLIENT_ORDER_ID_WINDOW_MS = 300_000;
+/**
+ * Matches Alpaca's 422 duplicate-idempotency-key rejection message. Alpaca has
+ * used both "client_order_id must be unique" and "client order id must be
+ * unique" across API revisions, so separators are matched loosely.
+ */
+const DUPLICATE_CLIENT_ORDER_ID_PATTERN = /client[\s_-]?order[\s_-]?id must be unique/i;
+/** HTTP status Alpaca uses for duplicate `client_order_id` rejections. */
+const DUPLICATE_CLIENT_ORDER_ID_STATUS = 422;
+/**
+ * Order statuses in which a previously-submitted order can never execute.
+ * A derived-id duplicate colliding with an order in one of these states is a
+ * legitimate NEW order (e.g. cancel-then-recreate of an identical trailing
+ * stop) and is resubmitted with a fresh salt; any other status means the
+ * original order is live or executed, so it is returned as idempotent success.
+ */
+const TERMINAL_DEAD_ORDER_STATUSES = new Set([
+    "canceled",
+    "expired",
+    "rejected",
+    "replaced",
+    "done_for_day",
+]);
 /**
 Websocket example
   const alpacaAPI = createAlpacaTradingAPI(credentials); // type AlpacaCredentials
@@ -4594,6 +4768,142 @@ class AlpacaTradingAPI {
             .slice(0, CLIENT_ORDER_ID_HASH_LENGTH);
         return `${CLIENT_ORDER_ID_PREFIX}${digest}`;
     }
+    /**
+     * Running count of derived-id duplicate collisions resolved by returning the
+     * already-submitted order. Emitted in log metadata so operators can see the
+     * idempotency net firing.
+     */
+    idempotentDuplicateReturns = 0;
+    /**
+     * Running count of derived-id duplicate collisions resolved by resubmitting
+     * once with a fresh random salt (the colliding order was terminally dead).
+     */
+    saltedDuplicateResubmits = 0;
+    /**
+     * Whether an error thrown by {@link makeRequest} is Alpaca's 422
+     * duplicate-`client_order_id` rejection.
+     * @param error - The error thrown by the order POST.
+     * @returns true when the error is a duplicate-idempotency-key rejection.
+     */
+    isDuplicateClientOrderIdRejection(error) {
+        if (!(error instanceof Error))
+            return false;
+        return (error.message.includes(`(${DUPLICATE_CLIENT_ORDER_ID_STATUS})`) &&
+            DUPLICATE_CLIENT_ORDER_ID_PATTERN.test(error.message));
+    }
+    /**
+     * Look up an order by its `client_order_id` (Alpaca
+     * `GET /orders:by_client_order_id`).
+     * @param clientOrderId - The idempotency key the order was submitted with.
+     * @returns The order, or null when no order exists for the id (404).
+     */
+    async getOrderByClientOrderId(clientOrderId) {
+        try {
+            return await this.makeRequest("/orders:by_client_order_id", "GET", undefined, `?client_order_id=${encodeURIComponent(clientOrderId)}`);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes("(404)")) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * POST an order body with duplicate-`client_order_id` recovery.
+     *
+     * Sets `client_order_id` (explicit id wins; otherwise derived from
+     * `deriveParts`), submits, and on Alpaca's 422 duplicate rejection:
+     *
+     * - **Caller-supplied id**: throws a typed
+     *   {@link DuplicateClientOrderIdError} — the caller owns idempotency
+     *   semantics and must decide whether the duplicate is success or a bug.
+     * - **Derived id, colliding order live/filled**: returns the existing order
+     *   as idempotent success (this is the timeout+retry case the derived id
+     *   exists to de-duplicate).
+     * - **Derived id, colliding order terminally dead** (canceled / expired /
+     *   rejected — e.g. cancel-then-recreate of an identical trailing stop):
+     *   resubmits exactly once with a fresh random salt so the legitimate new
+     *   order is not blocked. A second duplicate rejection throws the typed
+     *   error.
+     * - **Derived id, status lookup fails**: fails CLOSED with the typed error —
+     *   the colliding order may be live, so resubmitting could double-fill; the
+     *   caller's next cycle retries when the lookup can succeed.
+     *
+     * Both recovery outcomes increment log-visible counters.
+     *
+     * @param body - The order payload (its `client_order_id` is set here).
+     * @param options - Idempotency inputs: optional explicit id and the derive
+     *   parts used both for the default id and for the salted resubmit.
+     * @returns The created (or pre-existing, on idempotent recovery) order.
+     */
+    async postOrderWithIdempotencyRecovery(body, options) {
+        const derived = options.explicitClientOrderId === undefined;
+        const clientOrderId = options.explicitClientOrderId ??
+            this.deriveClientOrderId(options.deriveParts);
+        body.client_order_id = clientOrderId;
+        const requestBody = body;
+        try {
+            return await this.makeRequest("/orders", "POST", requestBody);
+        }
+        catch (error) {
+            if (!this.isDuplicateClientOrderIdRejection(error)) {
+                throw error;
+            }
+            if (!derived) {
+                throw new DuplicateClientOrderIdError(`Duplicate client_order_id "${clientOrderId}" rejected by Alpaca (caller-supplied id)`, clientOrderId, false, error);
+            }
+            let existing = null;
+            try {
+                existing = await this.getOrderByClientOrderId(clientOrderId);
+            }
+            catch (lookupError) {
+                // Fail CLOSED: the 422 proves an order with this id exists, but its
+                // status is unverifiable. Resubmitting here could double-fill a live
+                // order (the timeout+retry case), which is strictly worse than the
+                // caller retrying on its next cycle — by then the lookup will resolve.
+                this.log(`Duplicate-order lookup failed for ${clientOrderId}; failing closed (no resubmit) to avoid a possible double order: ${lookupError instanceof Error
+                    ? lookupError.message
+                    : String(lookupError)}`, { symbol: options.logSymbol, type: "error" });
+                throw new DuplicateClientOrderIdError(`Duplicate client_order_id "${clientOrderId}" rejected by Alpaca and the existing-order lookup failed; refusing to resubmit (possible live duplicate)`, clientOrderId, true, lookupError);
+            }
+            if (existing && !TERMINAL_DEAD_ORDER_STATUSES.has(existing.status)) {
+                this.idempotentDuplicateReturns++;
+                this.log(`Derived client_order_id ${clientOrderId} already submitted (status=${existing.status}); returning existing order ${existing.id} as idempotent success`, {
+                    symbol: options.logSymbol,
+                    type: "warn",
+                    metadata: {
+                        outcome: "idempotent_return",
+                        idempotentDuplicateReturns: this.idempotentDuplicateReturns,
+                    },
+                });
+                return existing;
+            }
+            const saltedId = this.deriveClientOrderId([
+                ...options.deriveParts,
+                "resubmit",
+                node_crypto.randomUUID(),
+            ]);
+            this.saltedDuplicateResubmits++;
+            this.log(`Derived client_order_id ${clientOrderId} collided with a ${existing ? `terminal (${existing.status})` : "missing"} order; resubmitting once with fresh salt ${saltedId}`, {
+                symbol: options.logSymbol,
+                type: "warn",
+                metadata: {
+                    outcome: "salted_resubmit",
+                    saltedDuplicateResubmits: this.saltedDuplicateResubmits,
+                },
+            });
+            body.client_order_id = saltedId;
+            try {
+                return await this.makeRequest("/orders", "POST", requestBody);
+            }
+            catch (resubmitError) {
+                if (this.isDuplicateClientOrderIdRejection(resubmitError)) {
+                    throw new DuplicateClientOrderIdError(`Salted resubmit of duplicate client_order_id "${clientOrderId}" was itself rejected as a duplicate ("${saltedId}")`, saltedId, true, resubmitError);
+                }
+                throw resubmitError;
+            }
+        }
+    }
     /**
      * Collect the human-readable failure entries from a bulk Multi-Status (207)
      * response body (`DELETE /orders`, `DELETE /positions`). Each element carries
@@ -4896,7 +5206,7 @@ class AlpacaTradingAPI {
             }
             const contentType = response.headers.get("content-type");
             if (contentType && contentType.includes("application/json")) {
-                return await response.json();
+                return (await response.json());
             }
             // For non-JSON responses, return the text content
             const textContent = await response.text();
@@ -5044,9 +5354,15 @@ class AlpacaTradingAPI {
      * @param side (string) - the side of the order
      * @param trailPercent100 (number) - the trail percent of the order (scale 100, i.e. 0.5 = 0.5%)
      * @param position_intent (string) - the position intent of the order
+     * @param clientOrderId - Optional explicit idempotency key; when supplied it
+     *   is used verbatim and duplicate rejections surface as
+     *   {@link DuplicateClientOrderIdError}.
+     * @param idempotencyNonce - Optional attempt/signal discriminator folded into
+     *   the derived idempotency key so an intentionally-repeated identical order
+     *   inside one derivation window receives a distinct id.
      * @returns The created AlpacaOrder with order ID and details
      */
-    async createTrailingStop(symbol, qty, side, trailPercent100, position_intent, clientOrderId) {
+    async createTrailingStop(symbol, qty, side, trailPercent100, position_intent, clientOrderId, idempotencyNonce) {
         this.log(`Creating trailing stop ${side.toUpperCase()} ${qty} shares for ${symbol} with trail percent ${trailPercent100}%`, {
             symbol,
         });
@@ -5059,18 +5375,21 @@ class AlpacaTradingAPI {
             type: "trailing_stop",
             trail_percent: trailPercent100.toString(), // Already in decimal form (e.g., 4 for 4%)
             time_in_force: "gtc",
-            client_order_id: clientOrderId ??
-                this.deriveClientOrderId([
+        };
+        try {
+            const order = await this.postOrderWithIdempotencyRecovery(body, {
+                explicitClientOrderId: clientOrderId,
+                deriveParts: [
                     "trailing_stop",
                     symbol,
                     side,
                     position_intent,
                     Math.abs(qty),
                     trailPercent100,
-                ]),
-        };
-        try {
-            const order = await this.makeRequest(`/orders`, "POST", body);
+                    ...(idempotencyNonce !== undefined ? [String(idempotencyNonce)] : []),
+                ],
+                logSymbol: symbol,
+            });
             this.log(`Trailing stop order created for ${symbol}: orderId=${order.id}, trailPercent=${trailPercent100}%`, { symbol });
             return order;
         }
@@ -5088,8 +5407,14 @@ class AlpacaTradingAPI {
      * @param qty (number) - the quantity of the order
      * @param side (string) - the side of the order
      * @param position_intent (string) - the position intent of the order. Important for knowing if a position needs a trailing stop.
+     * @param client_order_id - Optional explicit idempotency key; duplicate
+     *   rejections of an explicit id surface as
+     *   {@link DuplicateClientOrderIdError}.
+     * @param idempotencyNonce - Optional attempt/signal discriminator folded into
+     *   the derived idempotency key so an intentionally-repeated identical order
+     *   inside one derivation window receives a distinct id.
      */
-    async createMarketOrder(symbol, qty, side, position_intent, client_order_id) {
+    async createMarketOrder(symbol, qty, side, position_intent, client_order_id, idempotencyNonce) {
         this.log(`Creating market order for ${symbol}: ${side} ${qty} shares (${position_intent})`, {
             symbol,
         });
@@ -5102,17 +5427,19 @@ class AlpacaTradingAPI {
             time_in_force: "day",
             order_class: "simple",
         };
-        body.client_order_id =
-            client_order_id ??
-                this.deriveClientOrderId([
+        try {
+            return await this.postOrderWithIdempotencyRecovery(body, {
+                explicitClientOrderId: client_order_id,
+                deriveParts: [
                     "market",
                     symbol,
                     side,
                     position_intent,
                     Math.abs(qty),
-                ]);
-        try {
-            return await this.makeRequest("/orders", "POST", body);
+                    ...(idempotencyNonce !== undefined ? [String(idempotencyNonce)] : []),
+                ],
+                logSymbol: symbol,
+            });
         }
         catch (error) {
             this.log(`Error creating market order: ${error}`, { type: "error" });
@@ -5269,9 +5596,14 @@ class AlpacaTradingAPI {
      * @param limitPrice (number) - the limit price of the order
      * @param position_intent (string) - the position intent of the order
      * @param extended_hours (boolean) - whether the order is in extended hours
-     * @param client_order_id (string) - the client order id of the order
+     * @param client_order_id - Optional explicit idempotency key; duplicate
+     *   rejections of an explicit id surface as
+     *   {@link DuplicateClientOrderIdError}.
+     * @param idempotencyNonce - Optional attempt/signal discriminator folded into
+     *   the derived idempotency key so an intentionally-repeated identical order
+     *   inside one derivation window receives a distinct id.
      */
-    async createLimitOrder(symbol, qty, side, limitPrice, position_intent, extended_hours = false, client_order_id) {
+    async createLimitOrder(symbol, qty, side, limitPrice, position_intent, extended_hours = false, client_order_id, idempotencyNonce) {
         this.log(`Creating limit order for ${symbol}: ${side} ${qty} shares at $${limitPrice.toFixed(2)} (${position_intent})`, {
             symbol,
         });
@@ -5286,9 +5618,10 @@ class AlpacaTradingAPI {
             order_class: "simple",
             extended_hours,
         };
-        body.client_order_id =
-            client_order_id ??
-                this.deriveClientOrderId([
+        try {
+            return await this.postOrderWithIdempotencyRecovery(body, {
+                explicitClientOrderId: client_order_id,
+                deriveParts: [
                     "limit",
                     symbol,
                     side,
@@ -5296,9 +5629,10 @@ class AlpacaTradingAPI {
                     Math.abs(qty),
                     this.roundPriceForAlpaca(limitPrice),
                     extended_hours,
-                ]);
-        try {
-            return await this.makeRequest("/orders", "POST", body);
+                    ...(idempotencyNonce !== undefined ? [String(idempotencyNonce)] : []),
+                ],
+                logSymbol: symbol,
+            });
         }
         catch (error) {
             this.log(`Error creating limit order: ${error}`, { type: "error" });
@@ -5451,10 +5785,14 @@ class AlpacaTradingAPI {
      * @param limitPrice Limit price (required for limit orders)
      * @param clientOrderId Optional idempotency key; a deterministic one is
      *   derived from the order parameters when omitted so a client-timeout retry
-     *   is de-duplicated broker-side.
+     *   is de-duplicated broker-side. Duplicate rejections of an explicit id
+     *   surface as {@link DuplicateClientOrderIdError}.
+     * @param idempotencyNonce Optional attempt/signal discriminator folded into
+     *   the derived idempotency key so an intentionally-repeated identical order
+     *   inside one derivation window receives a distinct id.
      * @returns The created order
      */
-    async createOptionOrder(symbol, qty, side, position_intent, type, limitPrice, clientOrderId) {
+    async createOptionOrder(symbol, qty, side, position_intent, type, limitPrice, clientOrderId, idempotencyNonce) {
         if (!Number.isInteger(qty) || qty <= 0) {
             this.log("Quantity must be a positive whole number for option orders", {
                 type: "error",
@@ -5479,20 +5817,22 @@ class AlpacaTradingAPI {
         if (type === "limit" && limitPrice !== undefined) {
             orderData.limit_price = this.roundPriceForAlpaca(limitPrice).toString();
         }
-        orderData.client_order_id =
-            clientOrderId ??
-                this.deriveClientOrderId([
-                    "option",
-                    type,
-                    symbol,
-                    side,
-                    position_intent,
-                    qty,
-                    type === "limit" && limitPrice !== undefined
-                        ? this.roundPriceForAlpaca(limitPrice)
-                        : undefined,
-                ]);
-        return this.makeRequest("/orders", "POST", orderData);
+        return this.postOrderWithIdempotencyRecovery(orderData, {
+            explicitClientOrderId: clientOrderId,
+            deriveParts: [
+                "option",
+                type,
+                symbol,
+                side,
+                position_intent,
+                qty,
+                type === "limit" && limitPrice !== undefined
+                    ? this.roundPriceForAlpaca(limitPrice)
+                    : undefined,
+                ...(idempotencyNonce !== undefined ? [String(idempotencyNonce)] : []),
+            ],
+            logSymbol: symbol,
+        });
     }
     /**
      * Create a multi-leg option order
@@ -5502,10 +5842,14 @@ class AlpacaTradingAPI {
      * @param limitPrice Limit price (required for limit orders)
      * @param clientOrderId Optional idempotency key; a deterministic one is
      *   derived from the legs and order parameters when omitted so a
-     *   client-timeout retry is de-duplicated broker-side.
+     *   client-timeout retry is de-duplicated broker-side. Duplicate rejections
+     *   of an explicit id surface as {@link DuplicateClientOrderIdError}.
+     * @param idempotencyNonce Optional attempt/signal discriminator folded into
+     *   the derived idempotency key so an intentionally-repeated identical order
+     *   inside one derivation window receives a distinct id.
      * @returns The created multi-leg order
      */
-    async createMultiLegOptionOrder(legs, qty, type, limitPrice, clientOrderId) {
+    async createMultiLegOptionOrder(legs, qty, type, limitPrice, clientOrderId, idempotencyNonce) {
         if (!Number.isInteger(qty) || qty <= 0) {
             this.log("Quantity must be a positive whole number for option orders", {
                 type: "error",
@@ -5531,18 +5875,20 @@ class AlpacaTradingAPI {
         if (type === "limit" && limitPrice !== undefined) {
             orderData.limit_price = this.roundPriceForAlpaca(limitPrice).toString();
         }
-        orderData.client_order_id =
-            clientOrderId ??
-                this.deriveClientOrderId([
-                    "mleg",
-                    type,
-                    qty,
-                    type === "limit" && limitPrice !== undefined
-                        ? this.roundPriceForAlpaca(limitPrice)
-                        : undefined,
-                    ...legs.map((leg) => `${leg.symbol}:${leg.side}:${leg.ratio_qty}:${leg.position_intent}`),
-                ]);
-        return this.makeRequest("/orders", "POST", orderData);
+        return this.postOrderWithIdempotencyRecovery(orderData, {
+            explicitClientOrderId: clientOrderId,
+            deriveParts: [
+                "mleg",
+                type,
+                qty,
+                type === "limit" && limitPrice !== undefined
+                    ? this.roundPriceForAlpaca(limitPrice)
+                    : undefined,
+                ...legs.map((leg) => `${leg.symbol}:${leg.side}:${leg.ratio_qty}:${leg.position_intent}`),
+                ...(idempotencyNonce !== undefined ? [String(idempotencyNonce)] : []),
+            ],
+            logSymbol: legSymbols,
+        });
     }
     /**
      * Exercise an option contract
@@ -5915,7 +6261,7 @@ class AlpacaTradingAPI {
      */
     async createEquitiesTrade(params, options) {
         const { symbol, qty, side, referencePrice } = params;
-        const { type = "market", limitPrice, extendedHours = false, useStopLoss = false, stopPrice, stopPercent100, useTakeProfit = false, takeProfitPrice, takeProfitPercent100, clientOrderId, } = options || {};
+        const { type = "market", limitPrice, extendedHours = false, useStopLoss = false, stopPrice, stopPercent100, useTakeProfit = false, takeProfitPrice, takeProfitPercent100, clientOrderId, idempotencyNonce, } = options || {};
         // Validation: Extended hours + market order is not allowed
         if (extendedHours && type === "market") {
             this.log("Cannot create market order with extended hours enabled", {
@@ -6019,26 +6365,25 @@ class AlpacaTradingAPI {
             extended_hours: extendedHours,
             position_intent: side === "buy" ? "buy_to_open" : "sell_to_open",
         };
-        orderData.client_order_id =
-            clientOrderId ??
-                this.deriveClientOrderId([
-                    "equities",
-                    orderClass,
-                    type,
-                    symbol,
-                    side,
-                    Math.abs(qty),
-                    type === "limit" && limitPrice !== undefined
-                        ? this.roundPriceForAlpaca(limitPrice)
-                        : undefined,
-                    extendedHours,
-                    useStopLoss && calculatedStopPrice !== undefined
-                        ? this.roundPriceForAlpaca(calculatedStopPrice)
-                        : undefined,
-                    useTakeProfit && calculatedTakeProfitPrice !== undefined
-                        ? this.roundPriceForAlpaca(calculatedTakeProfitPrice)
-                        : undefined,
-                ]);
+        const deriveParts = [
+            "equities",
+            orderClass,
+            type,
+            symbol,
+            side,
+            Math.abs(qty),
+            type === "limit" && limitPrice !== undefined
+                ? this.roundPriceForAlpaca(limitPrice)
+                : undefined,
+            extendedHours,
+            useStopLoss && calculatedStopPrice !== undefined
+                ? this.roundPriceForAlpaca(calculatedStopPrice)
+                : undefined,
+            useTakeProfit && calculatedTakeProfitPrice !== undefined
+                ? this.roundPriceForAlpaca(calculatedTakeProfitPrice)
+                : undefined,
+            ...(idempotencyNonce !== undefined ? [String(idempotencyNonce)] : []),
+        ];
         // Add limit price for limit orders
         if (type === "limit" && limitPrice !== undefined) {
             orderData.limit_price = this.roundPriceForAlpaca(limitPrice).toString();
@@ -6062,7 +6407,11 @@ class AlpacaTradingAPI {
             symbol,
         });
         try {
-            return await this.makeRequest("/orders", "POST", orderData);
+            return await this.postOrderWithIdempotencyRecovery(orderData, {
+                explicitClientOrderId: clientOrderId,
+                deriveParts,
+                logSymbol: symbol,
+            });
         }
         catch (error) {
             this.log(`Error creating equities trade: ${error}`, {
@@ -11045,7 +11394,9 @@ async function calculateTotalReturnYTD(portfolioHistory) {
  * @param accountId - The ID of the Alpaca account.
  * @param client - The Apollo client instance.
  * @param alpacaAccount - The Alpaca account object.
- * @returns A promise that resolves to a string representing the expense ratio in percentage format.
+ * @returns A promise that resolves to a string representing the expense ratio
+ *   in percentage format, or "N/A" when the ratio cannot be computed honestly
+ *   (missing account, fee-fetch failure, or non-positive/non-finite equity).
  */
 async function calculateExpenseRatio({ accountId, client, alpacaAccount, }) {
     if (!accountId && !alpacaAccount && !client) {
@@ -11079,12 +11430,15 @@ async function calculateExpenseRatio({ accountId, client, alpacaAccount, }) {
             return "N/A";
         }
     }
-    // Validate equity
-    if (!accountDetails.equity || isNaN(parseFloat(accountDetails.equity))) {
-        getLogger().warn("Invalid equity value.");
+    // Validate equity. A drained or freshly-funded account reports equity "0"
+    // (and a broken feed can yield NaN or a negative string); dividing by it
+    // would fabricate "Infinity%"/"NaN%" — return the deliberate "N/A"
+    // (unknown) instead, consistent with the fee-fetch failure path below.
+    const equity = parseFloat(accountDetails.equity);
+    if (!Number.isFinite(equity) || equity <= 0) {
+        getLogger().warn("Non-positive or non-finite equity value; cannot compute expense ratio.", { equity: accountDetails.equity });
         return "N/A";
     }
-    const equity = parseFloat(accountDetails.equity);
     // Fetch the account's real trailing fee expenses from Alpaca account
     // activities. A genuine data-source failure yields "N/A" (unknown) rather
     // than a fabricated 0.00%.
@@ -11410,8 +11764,13 @@ async function calculateAlphaAndBeta(portfolioHistory, benchmarkBars) {
     const alignedPortfolioReturns = [];
     const alignedBenchmarkReturns = [];
     for (const timestamp of commonTimestamps) {
+        // commonTimestamps is the key intersection of both maps, so both lookups
+        // are guaranteed present; the guard replaces a non-null assertion.
         const portfolioRet = portfolioReturnsMap.get(timestamp);
         const benchmarkRet = benchmarkReturnsMap.get(timestamp);
+        if (portfolioRet === undefined || benchmarkRet === undefined) {
+            continue;
+        }
         if (isFinite(portfolioRet) && isFinite(benchmarkRet)) {
             alignedPortfolioReturns.push(portfolioRet);
             alignedBenchmarkReturns.push(benchmarkRet);
@@ -11672,8 +12031,13 @@ function alignReturnsByDate(portfolioHistory, benchmarkBars) {
     const alignedPortfolioReturns = [];
     const alignedBenchmarkReturns = [];
     for (const timestamp of commonTimestamps) {
+        // commonTimestamps is the key intersection of both maps, so both lookups
+        // are guaranteed present; the guard replaces a non-null assertion.
         const portfolioRet = portfolioReturnsMap.get(timestamp);
         const benchmarkRet = benchmarkReturnsMap.get(timestamp);
+        if (portfolioRet === undefined || benchmarkRet === undefined) {
+            continue;
+        }
         alignedPortfolioReturns.push(portfolioRet);
         alignedBenchmarkReturns.push(benchmarkRet);
     }
@@ -11790,8 +12154,13 @@ async function calculateInformationRatio(portfolioHistory, benchmarkBars) {
     // Extract aligned returns
     const activeReturns = [];
     for (const timestamp of commonTimestamps) {
+        // commonTimestamps is the key intersection of both maps, so both lookups
+        // are guaranteed present; the guard replaces a non-null assertion.
         const portfolioRet = portfolioReturnsMap.get(timestamp);
         const benchmarkRet = benchmarkReturnsMap.get(timestamp);
+        if (portfolioRet === undefined || benchmarkRet === undefined) {
+            continue;
+        }
         activeReturns.push(portfolioRet - benchmarkRet);
     }
     const n = activeReturns.length;
@@ -14620,17 +14989,17 @@ var hasRequiredBrowser;
 function requireBrowser () {
 	if (hasRequiredBrowser) return browser.exports;
 	hasRequiredBrowser = 1;
-	(function (module, exports$1) {
+	(function (module, exports) {
 		/**
 		 * This is the web browser implementation of `debug()`.
 		 */
 
-		exports$1.formatArgs = formatArgs;
-		exports$1.save = save;
-		exports$1.load = load;
-		exports$1.useColors = useColors;
-		exports$1.storage = localstorage();
-		exports$1.destroy = (() => {
+		exports.formatArgs = formatArgs;
+		exports.save = save;
+		exports.load = load;
+		exports.useColors = useColors;
+		exports.storage = localstorage();
+		exports.destroy = (() => {
 			let warned = false;
 
 			return () => {
@@ -14645,7 +15014,7 @@ function requireBrowser () {
 		 * Colors.
 		 */
 
-		exports$1.colors = [
+		exports.colors = [
 			'#0000CC',
 			'#0000FF',
 			'#0033CC',
@@ -14810,7 +15179,7 @@ function requireBrowser () {
 		 *
 		 * @api public
 		 */
-		exports$1.log = console.debug || console.log || (() => {});
+		exports.log = console.debug || console.log || (() => {});
 
 		/**
 		 * Save `namespaces`.
@@ -14821,9 +15190,9 @@ function requireBrowser () {
 		function save(namespaces) {
 			try {
 				if (namespaces) {
-					exports$1.storage.setItem('debug', namespaces);
+					exports.storage.setItem('debug', namespaces);
 				} else {
-					exports$1.storage.removeItem('debug');
+					exports.storage.removeItem('debug');
 				}
 			} catch (error) {
 				// Swallow
@@ -14840,7 +15209,7 @@ function requireBrowser () {
 		function load() {
 			let r;
 			try {
-				r = exports$1.storage.getItem('debug') || exports$1.storage.getItem('DEBUG') ;
+				r = exports.storage.getItem('debug') || exports.storage.getItem('DEBUG') ;
 			} catch (error) {
 				// Swallow
 				// XXX (@Qix-) should we be logging these?
@@ -14876,7 +15245,7 @@ function requireBrowser () {
 			}
 		}
 
-		module.exports = requireCommon()(exports$1);
+		module.exports = requireCommon()(exports);
 
 		const {formatters} = module.exports;
 
@@ -15065,7 +15434,7 @@ var hasRequiredNode$1;
 function requireNode$1 () {
 	if (hasRequiredNode$1) return node$1.exports;
 	hasRequiredNode$1 = 1;
-	(function (module, exports$1) {
+	(function (module, exports) {
 		const tty = require$$1$1;
 		const util = require$$1$2;
 
@@ -15073,13 +15442,13 @@ function requireNode$1 () {
 		 * This is the Node.js implementation of `debug()`.
 		 */
 
-		exports$1.init = init;
-		exports$1.log = log;
-		exports$1.formatArgs = formatArgs;
-		exports$1.save = save;
-		exports$1.load = load;
-		exports$1.useColors = useColors;
-		exports$1.destroy = util.deprecate(
+		exports.init = init;
+		exports.log = log;
+		exports.formatArgs = formatArgs;
+		exports.save = save;
+		exports.load = load;
+		exports.useColors = useColors;
+		exports.destroy = util.deprecate(
 			() => {},
 			'Instance method `debug.destroy()` is deprecated and no longer does anything. It will be removed in the next major version of `debug`.'
 		);
@@ -15088,7 +15457,7 @@ function requireNode$1 () {
 		 * Colors.
 		 */
 
-		exports$1.colors = [6, 2, 3, 4, 5, 1];
+		exports.colors = [6, 2, 3, 4, 5, 1];
 
 		try {
 			// Optional dependency (as in, doesn't need to be installed, NOT like optionalDependencies in package.json)
@@ -15096,7 +15465,7 @@ function requireNode$1 () {
 			const supportsColor = requireSupportsColor();
 
 			if (supportsColor && (supportsColor.stderr || supportsColor).level >= 2) {
-				exports$1.colors = [
+				exports.colors = [
 					20,
 					21,
 					26,
@@ -15185,7 +15554,7 @@ function requireNode$1 () {
 		 *   $ DEBUG_COLORS=no DEBUG_DEPTH=10 DEBUG_SHOW_HIDDEN=enabled node script.js
 		 */
 
-		exports$1.inspectOpts = Object.keys(process.env).filter(key => {
+		exports.inspectOpts = Object.keys(process.env).filter(key => {
 			return /^debug_/i.test(key);
 		}).reduce((obj, key) => {
 			// Camel-case
@@ -15217,8 +15586,8 @@ function requireNode$1 () {
 		 */
 
 		function useColors() {
-			return 'colors' in exports$1.inspectOpts ?
-				Boolean(exports$1.inspectOpts.colors) :
+			return 'colors' in exports.inspectOpts ?
+				Boolean(exports.inspectOpts.colors) :
 				tty.isatty(process.stderr.fd);
 		}
 
@@ -15244,7 +15613,7 @@ function requireNode$1 () {
 		}
 
 		function getDate() {
-			if (exports$1.inspectOpts.hideDate) {
+			if (exports.inspectOpts.hideDate) {
 				return '';
 			}
 			return new Date().toISOString() + ' ';
@@ -15255,7 +15624,7 @@ function requireNode$1 () {
 		 */
 
 		function log(...args) {
-			return process.stderr.write(util.formatWithOptions(exports$1.inspectOpts, ...args) + '\n');
+			return process.stderr.write(util.formatWithOptions(exports.inspectOpts, ...args) + '\n');
 		}
 
 		/**
@@ -15295,13 +15664,13 @@ function requireNode$1 () {
 		function init(debug) {
 			debug.inspectOpts = {};
 
-			const keys = Object.keys(exports$1.inspectOpts);
+			const keys = Object.keys(exports.inspectOpts);
 			for (let i = 0; i < keys.length; i++) {
-				debug.inspectOpts[keys[i]] = exports$1.inspectOpts[keys[i]];
+				debug.inspectOpts[keys[i]] = exports.inspectOpts[keys[i]];
 			}
 		}
 
-		module.exports = requireCommon()(exports$1);
+		module.exports = requireCommon()(exports);
 
 		const {formatters} = module.exports;
 
@@ -15875,7 +16244,7 @@ function requireFollowRedirects () {
 	// Wraps the key/value object of protocols with redirect functionality
 	function wrap(protocols) {
 	  // Default settings
-	  var exports$1 = {
+	  var exports = {
 	    maxRedirects: 21,
 	    maxBodyLength: 10 * 1024 * 1024,
 	  };
@@ -15885,7 +16254,7 @@ function requireFollowRedirects () {
 	  Object.keys(protocols).forEach(function (scheme) {
 	    var protocol = scheme + ":";
 	    var nativeProtocol = nativeProtocols[protocol] = protocols[scheme];
-	    var wrappedProtocol = exports$1[scheme] = Object.create(nativeProtocol);
+	    var wrappedProtocol = exports[scheme] = Object.create(nativeProtocol);
 
 	    // Executes a request, following redirects
 	    function request(input, options, callback) {
@@ -15908,8 +16277,8 @@ function requireFollowRedirects () {
 
 	      // Set defaults
 	      options = Object.assign({
-	        maxRedirects: exports$1.maxRedirects,
-	        maxBodyLength: exports$1.maxBodyLength,
+	        maxRedirects: exports.maxRedirects,
+	        maxBodyLength: exports.maxBodyLength,
 	      }, input, options);
 	      options.nativeProtocols = nativeProtocols;
 	      if (!isString(options.host) && !isString(options.hostname)) {
@@ -15934,7 +16303,7 @@ function requireFollowRedirects () {
 	      get: { value: get, configurable: true, enumerable: true, writable: true },
 	    });
 	  });
-	  return exports$1;
+	  return exports;
 	}
 
 	function noop() { /* empty */ }
@@ -17540,7 +17909,7 @@ var hasRequiredLodash;
 function requireLodash () {
 	if (hasRequiredLodash) return lodash$1.exports;
 	hasRequiredLodash = 1;
-	(function (module, exports$1) {
+	(function (module, exports) {
 (function() {
 
 		  /** Used as a safe reference for `undefined` in pre-ES5 environments. */
@@ -17971,7 +18340,7 @@ function requireLodash () {
 		  var root = freeGlobal || freeSelf || Function('return this')();
 
 		  /** Detect free variable `exports`. */
-		  var freeExports = exports$1 && !exports$1.nodeType && exports$1;
+		  var freeExports = exports && !exports.nodeType && exports;
 
 		  /** Detect free variable `module`. */
 		  var freeModule = freeExports && 'object' == 'object' && module && !module.nodeType && module;
@@ -35801,12 +36170,12 @@ var hasRequiredIsBuffer;
 function requireIsBuffer () {
 	if (hasRequiredIsBuffer) return isBuffer.exports;
 	hasRequiredIsBuffer = 1;
-	(function (module, exports$1) {
+	(function (module, exports) {
 		var root = require_root(),
 		    stubFalse = requireStubFalse();
 
 		/** Detect free variable `exports`. */
-		var freeExports = exports$1 && !exports$1.nodeType && exports$1;
+		var freeExports = exports && !exports.nodeType && exports;
 
 		/** Detect free variable `module`. */
 		var freeModule = freeExports && 'object' == 'object' && module && !module.nodeType && module;
@@ -36026,11 +36395,11 @@ var hasRequired_nodeUtil;
 function require_nodeUtil () {
 	if (hasRequired_nodeUtil) return _nodeUtil.exports;
 	hasRequired_nodeUtil = 1;
-	(function (module, exports$1) {
+	(function (module, exports) {
 		var freeGlobal = require_freeGlobal();
 
 		/** Detect free variable `exports`. */
-		var freeExports = exports$1 && !exports$1.nodeType && exports$1;
+		var freeExports = exports && !exports.nodeType && exports;
 
 		/** Detect free variable `module`. */
 		var freeModule = freeExports && 'object' == 'object' && module && !module.nodeType && module;
@@ -44952,7 +45321,7 @@ var hasRequiredSafeBuffer;
 function requireSafeBuffer () {
 	if (hasRequiredSafeBuffer) return safeBuffer.exports;
 	hasRequiredSafeBuffer = 1;
-	(function (module, exports$1) {
+	(function (module, exports) {
 		/* eslint-disable node/no-deprecated-api */
 		var buffer = require$$0$5;
 		var Buffer = buffer.Buffer;
@@ -44967,8 +45336,8 @@ function requireSafeBuffer () {
 		  module.exports = buffer;
 		} else {
 		  // Copy properties from require('buffer')
-		  copyProps(buffer, exports$1);
-		  exports$1.Buffer = SafeBuffer;
+		  copyProps(buffer, exports);
+		  exports.Buffer = SafeBuffer;
 		}
 
 		function SafeBuffer (arg, encodingOrOffset, length) {
@@ -48166,22 +48535,22 @@ var hasRequiredReadable;
 function requireReadable () {
 	if (hasRequiredReadable) return readable.exports;
 	hasRequiredReadable = 1;
-	(function (module, exports$1) {
+	(function (module, exports) {
 		var Stream = require$$0$4;
 		if (process.env.READABLE_STREAM === 'disable' && Stream) {
 		  module.exports = Stream.Readable;
 		  Object.assign(module.exports, Stream);
 		  module.exports.Stream = Stream;
 		} else {
-		  exports$1 = module.exports = require_stream_readable();
-		  exports$1.Stream = Stream || exports$1;
-		  exports$1.Readable = exports$1;
-		  exports$1.Writable = require_stream_writable();
-		  exports$1.Duplex = require_stream_duplex();
-		  exports$1.Transform = require_stream_transform();
-		  exports$1.PassThrough = require_stream_passthrough();
-		  exports$1.finished = requireEndOfStream();
-		  exports$1.pipeline = requirePipeline();
+		  exports = module.exports = require_stream_readable();
+		  exports.Stream = Stream || exports;
+		  exports.Readable = exports;
+		  exports.Writable = require_stream_writable();
+		  exports.Duplex = require_stream_duplex();
+		  exports.Transform = require_stream_transform();
+		  exports.PassThrough = require_stream_passthrough();
+		  exports.finished = requireEndOfStream();
+		  exports.pipeline = requirePipeline();
 		} 
 	} (readable, readable.exports));
 	return readable.exports;
@@ -49616,12 +49985,12 @@ var hasRequiredWebsocket;
 function requireWebsocket () {
 	if (hasRequiredWebsocket) return websocket$1;
 	hasRequiredWebsocket = 1;
-	(function (exports$1) {
+	(function (exports) {
 		var __importDefault = (websocket$1 && websocket$1.__importDefault) || function (mod) {
 		    return (mod && mod.__esModule) ? mod : { "default": mod };
 		};
-		Object.defineProperty(exports$1, "__esModule", { value: true });
-		exports$1.AlpacaWebsocket = exports$1.ERROR = exports$1.CONN_ERROR = exports$1.EVENT = exports$1.STATE = void 0;
+		Object.defineProperty(exports, "__esModule", { value: true });
+		exports.AlpacaWebsocket = exports.ERROR = exports.CONN_ERROR = exports.EVENT = exports.STATE = void 0;
 		const events_1 = __importDefault(require$$0$1);
 		const ws_1 = __importDefault(requireWs());
 		const msgpack5_1 = __importDefault(requireMsgpack5());
@@ -49635,7 +50004,7 @@ function requireWebsocket () {
 		    STATE["DISCONNECTED"] = "disconnected";
 		    STATE["WAITING_TO_CONNECT"] = "waiting to connect";
 		    STATE["WAITING_TO_RECONNECT"] = "waiting to reconnect";
-		})(STATE || (exports$1.STATE = STATE = {}));
+		})(STATE || (exports.STATE = STATE = {}));
 		// Client events
 		var EVENT;
 		(function (EVENT) {
@@ -49654,9 +50023,9 @@ function requireWebsocket () {
 		    EVENT["CORRECTIONS"] = "corrections";
 		    EVENT["ORDERBOOKS"] = "orderbooks";
 		    EVENT["NEWS"] = "news";
-		})(EVENT || (exports$1.EVENT = EVENT = {}));
+		})(EVENT || (exports.EVENT = EVENT = {}));
 		// Connection errors by code
-		exports$1.CONN_ERROR = new Map([
+		exports.CONN_ERROR = new Map([
 		    [400, "invalid syntax"],
 		    [401, "not authenticated"],
 		    [402, "auth failed"],
@@ -49675,7 +50044,7 @@ function requireWebsocket () {
 		    ERROR["MISSING_SECERT_KEY"] = "missing secret key";
 		    ERROR["MISSING_API_KEY"] = "missing api key";
 		    ERROR["UNEXPECTED_MESSAGE"] = "unexpected message";
-		})(ERROR || (exports$1.ERROR = ERROR = {}));
+		})(ERROR || (exports.ERROR = ERROR = {}));
 		class AlpacaWebsocket extends events_1.default.EventEmitter {
 		    constructor(options) {
 		        super();
@@ -49832,7 +50201,7 @@ function requireWebsocket () {
 		                this.updateSubscriptions(data[0]);
 		                break;
 		            case "error":
-		                this.emit(EVENT.CLIENT_ERROR, exports$1.CONN_ERROR.get(data[0].code));
+		                this.emit(EVENT.CLIENT_ERROR, exports.CONN_ERROR.get(data[0].code));
 		                break;
 		            default:
 		                this.dataHandler(data);
@@ -49861,7 +50230,7 @@ function requireWebsocket () {
 		        }
 		    }
 		}
-		exports$1.AlpacaWebsocket = AlpacaWebsocket; 
+		exports.AlpacaWebsocket = AlpacaWebsocket; 
 	} (websocket$1));
 	return websocket$1;
 }
@@ -50495,8 +50864,8 @@ var hasRequiredWebsockets;
 function requireWebsockets () {
 	if (hasRequiredWebsockets) return websockets;
 	hasRequiredWebsockets = 1;
-	(function (exports$1) {
-		Object.defineProperty(exports$1, "__esModule", { value: true });
+	(function (exports) {
+		Object.defineProperty(exports, "__esModule", { value: true });
 		const events = require$$0$1;
 		const WebSocket = requireWs();
 		const entity = requireEntity();
@@ -50511,7 +50880,7 @@ function requireWebsockets () {
 		    STATE.DISCONNECTED = "disconnected";
 		    STATE.WAITING_TO_CONNECT = "waiting to connect";
 		    STATE.WAITING_TO_RECONNECT = "waiting to reconnect";
-		})((STATE = exports$1.STATE || (exports$1.STATE = {})));
+		})((STATE = exports.STATE || (exports.STATE = {})));
 		// Client events
 		var EVENT;
 		(function (EVENT) {
@@ -50525,7 +50894,7 @@ function requireWebsockets () {
 		    EVENT.STOCK_QUOTES = "stock_quotes";
 		    EVENT.STOCK_AGG_SEC = "stock_agg_sec";
 		    EVENT.STOCK_AGG_MIN = "stock_agg_min";
-		})((EVENT = exports$1.EVENT || (exports$1.EVENT = {})));
+		})((EVENT = exports.EVENT || (exports.EVENT = {})));
 		// Connection errors Each of these will also emit EVENT.ERROR
 		var ERROR;
 		(function (ERROR) {
@@ -50534,7 +50903,7 @@ function requireWebsockets () {
 		    ERROR.MISSING_API_KEY = "missing api key";
 		    ERROR.MISSING_SECRET_KEY = "missing secret key";
 		    ERROR.UNKNOWN = "unknown error";
-		})((ERROR = exports$1.ERROR || (exports$1.ERROR = {})));
+		})((ERROR = exports.ERROR || (exports.ERROR = {})));
 		/**
 		 * AlpacaStreamClient manages a connection to Alpaca's websocket api
 		 */
@@ -50847,7 +51216,7 @@ function requireWebsockets () {
 		        }
 		    }
 		}
-		exports$1.AlpacaStreamClient = AlpacaStreamClient; 
+		exports.AlpacaStreamClient = AlpacaStreamClient; 
 	} (websockets));
 	return websockets;
 }
@@ -51099,13 +51468,13 @@ var hasRequiredDist;
 function requireDist () {
 	if (hasRequiredDist) return dist$1.exports;
 	hasRequiredDist = 1;
-	(function (module, exports$1) {
+	(function (module, exports) {
 		var __importDefault = (dist && dist.__importDefault) || function (mod) {
 		    return (mod && mod.__esModule) ? mod : { "default": mod };
 		};
-		Object.defineProperty(exports$1, "__esModule", { value: true });
+		Object.defineProperty(exports, "__esModule", { value: true });
 		const alpaca_trade_api_1 = __importDefault(requireAlpacaTradeApi());
-		exports$1.default = alpaca_trade_api_1.default;
+		exports.default = alpaca_trade_api_1.default;
 		module.exports = alpaca_trade_api_1.default; 
 	} (dist$1, dist$1.exports));
 	return dist$1.exports;
@@ -63149,6 +63518,14 @@ class LRUCache {
     }
 }
 
+/**
+ * Default hard ceiling (ms) on a single loader invocation. Resolved at
+ * construction time into `options.loadTimeoutMs` so the effective value is
+ * always a validated number (see the constructor guard) — mirrors the
+ * engine-local copy's constructor-time resolution ahead of consolidating the
+ * two implementations onto this one.
+ */
+const DEFAULT_LOAD_TIMEOUT_MS = 30_000;
 /**
  * StampedeProtectedCache provides three-layer protection against cache stampedes
  *
@@ -63217,12 +63594,17 @@ class StampedeProtectedCache {
         loadTimeouts: 0,
     };
     constructor(options) {
+        if (options.loadTimeoutMs !== undefined &&
+            (!Number.isFinite(options.loadTimeoutMs) || options.loadTimeoutMs <= 0)) {
+            throw new RangeError(`StampedeProtectedCache loadTimeoutMs must be a positive finite number of milliseconds; received ${String(options.loadTimeoutMs)}`);
+        }
         this.options = {
             ...options,
             staleWhileRevalidateTtl: options.staleWhileRevalidateTtl ?? options.defaultTtl * 2,
             minJitter: options.minJitter ?? 0.9,
             maxJitter: options.maxJitter ?? 1.1,
             enableBackgroundRefresh: options.enableBackgroundRefresh ?? true,
+            loadTimeoutMs: options.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS,
             logger: options.logger ?? {
                 debug: () => { },
                 info: () => { },
@@ -63299,7 +63681,7 @@ class StampedeProtectedCache {
             cached.accessCount++;
             cached.lastAccessedAt = now;
             // Check if entry is still fresh (considering probabilistic expiration)
-            const jitteredExpiresAt = this.applyJitter(cached.expiresAt);
+            const jitteredExpiresAt = this.applyJitter(cached.expiresAt, cached.ttl);
             if (now < jitteredExpiresAt) {
                 // Fresh hit
                 this.stats.hits++;
@@ -63562,12 +63944,16 @@ class StampedeProtectedCache {
      * is logged rather than surfacing as an unhandled rejection.
      */
     async loadWithTimeout(key, loader, ttl) {
-        const timeoutMs = this.options.loadTimeoutMs ?? 30000;
-        const loadPromise = this.loadAndCache(key, loader, ttl);
+        const timeoutMs = this.options.loadTimeoutMs;
+        const invocation = { abandoned: false };
+        const loadPromise = this.loadAndCache(key, loader, ttl, invocation);
         let timeoutHandle;
         const timeoutPromise = new Promise((_, reject) => {
             timeoutHandle = setTimeout(() => {
                 this.stats.loadTimeouts++;
+                // Mark the invocation abandoned BEFORE evicting the pin: a retry that
+                // starts now must never be overwritten by this loader's late result.
+                invocation.abandoned = true;
                 // Evict the pin so the next caller retries fresh.
                 this.pendingRefreshes.delete(key);
                 this.options.logger.warn("Cache loader timed out — pin evicted", {
@@ -63600,11 +63986,19 @@ class StampedeProtectedCache {
     /**
      * Load data and cache it
      */
-    async loadAndCache(key, loader, ttl) {
+    async loadAndCache(key, loader, ttl, invocation = { abandoned: false }) {
         const startTime = Date.now();
         try {
             this.options.logger.debug("Loading data", { key });
             const value = await loader(key);
+            if (invocation.abandoned) {
+                // The pin was evicted at loadTimeoutMs and a retry may have cached
+                // fresher data since; writing this late value would overwrite it with
+                // a snapshot fetched before/through the hang.
+                const loadTime = Date.now() - startTime;
+                this.options.logger.warn("Abandoned cache loader resolved late — result discarded", { key, loadTime });
+                return value;
+            }
             // Cache the loaded value
             this.set(key, value, ttl);
             const loadTime = Date.now() - startTime;
@@ -63619,11 +64013,15 @@ class StampedeProtectedCache {
                 error,
                 loadTime,
             });
-            // Update cached entry with error if it exists
-            const cached = this.cache.get(key);
-            if (cached) {
-                cached.lastError = error;
-                cached.isRefreshing = false;
+            // Update cached entry with error if it exists — unless this invocation
+            // was abandoned, in which case the entry may already belong to a
+            // fresher retry and must not be marked with a stale error.
+            if (!invocation.abandoned) {
+                const cached = this.cache.get(key);
+                if (cached) {
+                    cached.lastError = error;
+                    cached.isRefreshing = false;
+                }
             }
             throw error;
         }
@@ -63655,13 +64053,23 @@ class StampedeProtectedCache {
         });
     }
     /**
-     * Apply probabilistic jitter to expiration time
+     * Apply probabilistic jitter to an entry's expiration time.
+     *
+     * The jitter must scale with the ENTRY's own TTL: using `defaultTtl` here
+     * (as this method originally did) mis-anchored `createdAt` for any entry
+     * cached with a custom TTL, swinging its effective expiry by up to
+     * ±(defaultTtl - ttl) — a 50ms entry under a 5s default could randomly
+     * read as already-expired at write time or fresh for 10x its TTL.
+     *
+     * @param originalExpiresAt - The entry's unjittered expiry timestamp (ms).
+     * @param ttl - The TTL (ms) the entry was cached with.
+     * @returns The jittered expiry timestamp.
      */
-    applyJitter(originalExpiresAt) {
+    applyJitter(originalExpiresAt, ttl) {
         const range = this.options.maxJitter - this.options.minJitter;
         const jitter = this.options.minJitter + Math.random() * range;
-        const createdAt = originalExpiresAt - this.options.defaultTtl;
-        const jitteredTtl = this.options.defaultTtl * jitter;
+        const createdAt = originalExpiresAt - ttl;
+        const jitteredTtl = ttl * jitter;
         return createdAt + jitteredTtl;
     }
     /**
@@ -63746,7 +64154,7 @@ const DEFAULT_CACHE_OPTIONS = {
     minJitter: 0.9, // 90%
     maxJitter: 1.1, // 110%
     enableBackgroundRefresh: true,
-    loadTimeoutMs: 30000, // 30s hard loader ceiling (anti-pinning)
+    loadTimeoutMs: DEFAULT_LOAD_TIMEOUT_MS, // hard loader ceiling (anti-pinning)
 };
 
 /**
@@ -70628,6 +71036,7 @@ exports.DEFAULT_RISK_FREE_RATE = DEFAULT_RISK_FREE_RATE;
 exports.DEFAULT_TIMEOUTS = DEFAULT_TIMEOUTS;
 exports.DEFAULT_TRADING_POLICY = DEFAULT_TRADING_POLICY;
 exports.DataFormatError = DataFormatError;
+exports.DuplicateClientOrderIdError = DuplicateClientOrderIdError;
 exports.HttpClientError = HttpClientError;
 exports.HttpServerError = HttpServerError;
 exports.KEEP_ALIVE_DEFAULTS = KEEP_ALIVE_DEFAULTS;