@adaptic/utils 0.0.1007 → 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;
@@ -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;