@adaptic/utils 0.0.1001 → 0.0.1003

package/dist/index.mjs

@@ -3,6 +3,7 @@ import { format, sub, set, add, startOfDay, endOfDay, isBefore, differenceInMill
 import { formatInTimeZone, toZonedTime, fromZonedTime } from 'date-fns-tz';
 import require$$0$4, { EventEmitter } from 'events';
 import WebSocket from 'ws';
+import { createHash } from 'node:crypto';
 import ms from 'ms';
 import require$$0$1 from 'fs';
 import require$$1 from 'path';
@@ -2357,6 +2358,23 @@ class NetworkError extends AdapticUtilsError {
         this.service = service;
     }
 }
+/**
+ * Unsupported brokerage provider errors
+ * Thrown when a broker operation is requested for a provider that has no
+ * implemented integration (e.g. IBKR or COINBASE before their adapters land,
+ * or an unrecognised provider string from an untyped caller).
+ * Never retryable — the caller must route to a supported provider.
+ */
+class UnsupportedBrokerError extends AdapticUtilsError {
+    provider;
+    constructor(
+    /** The provider that was requested but is not supported. */
+    provider, cause) {
+        super(`Brokerage provider "${provider}" is not supported. Supported providers: ALPACA`, "UNSUPPORTED_BROKER", "broker", false, // Unsupported providers are never retryable
+        cause);
+        this.provider = provider;
+    }
+}
 /**
  * Data parsing and format errors
  * Used when API responses cannot be parsed or are in unexpected format
@@ -2386,6 +2404,19 @@ class DataFormatError extends AdapticUtilsError {
  * const result = await makeAlpacaApiCall();
  * ```
  */
+/** Number of milliseconds in one second, used for token-refill timing math. */
+const MS_PER_SECOND$1 = 1000;
+/**
+ * Minimum delay (ms) for a scheduled queue wake-up. Guards against a `0`/`NaN`
+ * delay when the token deficit rounds down, ensuring the timer always makes
+ * forward progress rather than busy-looping on the event loop.
+ */
+const MIN_WAKE_DELAY_MS = 1;
+/**
+ * Number of whole tokens required to release a single queued request. The token
+ * bucket consumes exactly one token per admitted request.
+ */
+const TOKENS_PER_REQUEST = 1;
 /**
  * Token bucket rate limiter implementation
  *
@@ -2401,6 +2432,13 @@ class TokenBucketRateLimiter {
     queue = [];
     timeoutMs;
     processingQueue = false;
+    /**
+     * Single pending timer that wakes the limiter to refill tokens and drain the
+     * queue. Without this, a queued request would only be released by a
+     * subsequent {@link acquire} call and would otherwise stall until its own
+     * timeout fired. `null` means no wake-up is currently scheduled.
+     */
+    wakeTimer = null;
     /**
      * Creates a new rate limiter instance
      *
@@ -2474,8 +2512,48 @@ class TokenBucketRateLimiter {
                 reject(error);
             }, this.timeoutMs);
             this.queue.push({ resolve, reject, timeoutHandle });
+            // Ensure the queue is actively drained even if no further acquire() calls
+            // arrive: schedule a wake-up to refill tokens and release this request.
+            this.scheduleQueueWake();
         });
     }
+    /**
+     * Schedules a single wake-up timer that refills tokens and drains the queue.
+     *
+     * The delay is the time required to accrue the tokens still needed to release
+     * the next queued request at the configured refill rate. Only one timer is
+     * ever outstanding (guarded by {@link wakeTimer}); the timer is `unref`'d so
+     * it never keeps the Node.js process alive on its own. When it fires it
+     * refills, drains what it can, and re-arms itself if work remains.
+     */
+    scheduleQueueWake() {
+        // A wake-up is already pending, or there is nothing to wake for.
+        if (this.wakeTimer !== null || this.queue.length === 0) {
+            return;
+        }
+        const tokensNeeded = Math.max(0, TOKENS_PER_REQUEST - this.tokens);
+        const deficitMs = Math.max(MIN_WAKE_DELAY_MS, Math.ceil((tokensNeeded / this.config.refillRate) * MS_PER_SECOND$1));
+        const timer = setTimeout(() => {
+            this.wakeTimer = null;
+            // refill() drains the queue via processQueue(); if requests remain
+            // afterwards, processQueue() re-arms the wake-up.
+            this.refill();
+        }, deficitMs);
+        // Do not let a pending rate-limiter wake-up keep the process alive.
+        if (typeof timer.unref === "function") {
+            timer.unref();
+        }
+        this.wakeTimer = timer;
+    }
+    /**
+     * Clears any pending wake-up timer.
+     */
+    clearWakeTimer() {
+        if (this.wakeTimer !== null) {
+            clearTimeout(this.wakeTimer);
+            this.wakeTimer = null;
+        }
+    }
     /**
      * Refills tokens based on elapsed time and processes queued requests
      *
@@ -2520,6 +2598,15 @@ class TokenBucketRateLimiter {
         finally {
             this.processingQueue = false;
         }
+        // Keep the wake-up state consistent with the queue: if requests are still
+        // waiting (tokens ran out mid-drain), ensure a wake-up is armed; otherwise
+        // release any pending timer so it cannot fire needlessly.
+        if (this.queue.length > 0) {
+            this.scheduleQueueWake();
+        }
+        else {
+            this.clearWakeTimer();
+        }
     }
     /**
      * Gets the current number of available tokens
@@ -2551,6 +2638,7 @@ class TokenBucketRateLimiter {
             clearTimeout(request.timeoutHandle);
             request.reject(new RateLimitError(`Rate limiter reset for ${this.config.label}`, this.config.label, undefined));
         }
+        this.clearWakeTimer();
         this.queue = [];
         this.tokens = this.config.maxTokens;
         this.lastRefill = Date.now();
@@ -4300,6 +4388,46 @@ const limitPriceSlippagePercent100 = 0.1; // 0.1%
 const ORDER_PAGE_LIMIT = 500;
 /** Delay between order pagination pages to stay clear of rate limits. */
 const ORDER_PAGINATION_DELAY_MS = 300;
+/**
+ * HTTP status at or above which a Multi-Status (207) sub-result is a failure.
+ * Alpaca's bulk `DELETE /orders` and `DELETE /positions` endpoints return a 207
+ * envelope whose top-level status is 2xx even when individual orders/positions
+ * failed to cancel or close; each element carries its own per-item HTTP status.
+ * Treating >= 300 as a failure lets the engine failsafe see partial failures
+ * instead of recording a false success.
+ */
+const HTTP_STATUS_MIN_ERROR = 300;
+/**
+ * Prefix applied to engine-derived `client_order_id` idempotency keys so they
+ * are visibly attributable in Alpaca's dashboard and can never collide with a
+ * caller-supplied identifier.
+ */
+const CLIENT_ORDER_ID_PREFIX = "adaptic-";
+/**
+ * Number of leading hex characters of the SHA-256 digest retained in a derived
+ * `client_order_id`. 32 hex chars = 128 bits of entropy (collision-negligible),
+ * and keeps the full id (prefix + digest = 40 chars) within Alpaca's identifier
+ * length limit.
+ */
+const CLIENT_ORDER_ID_HASH_LENGTH = 32;
+/**
+ * Idempotency window (ms) used when deriving a default `client_order_id`.
+ *
+ * A client request timeout followed by an automatic retry re-submits the SAME
+ * logical order. Deriving the id from the order's semantic parameters plus the
+ * current time-window bucket makes Alpaca reject the retried duplicate
+ * (`client_order_id must be unique`) instead of double-filling. The window is
+ * deliberately much larger than the 30s Alpaca request timeout so a full
+ * timeout+retry sequence lands in the same bucket, while a genuinely new but
+ * otherwise-identical order placed in a later window still receives a distinct
+ * id.
+ *
+ * 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).
+ */
+const CLIENT_ORDER_ID_WINDOW_MS = 300_000;
 /**
 Websocket example
   const alpacaAPI = createAlpacaTradingAPI(credentials); // type AlpacaCredentials
@@ -4380,6 +4508,114 @@ class AlpacaTradingAPI {
             ? Math.round(price * 100) / 100
             : Math.round(price * 10000) / 10000;
     };
+    /**
+     * Derive a deterministic `client_order_id` from an order's semantic
+     * parameters so that a client-timeout-triggered retry re-submits the SAME id
+     * and Alpaca rejects the duplicate broker-side instead of double-filling.
+     *
+     * The id is stable for identical parameters within a single
+     * {@link CLIENT_ORDER_ID_WINDOW_MS} bucket and scoped per account. Callers
+     * that must place genuinely distinct yet otherwise-identical orders should
+     * pass an explicit `clientOrderId` rather than relying on this default.
+     *
+     * @param parts - Ordered, stringifiable components uniquely describing the
+     *   order (e.g. order kind, symbol, side, quantity, price, intent).
+     * @returns An Alpaca-safe `client_order_id` (prefix + truncated SHA-256 hex).
+     */
+    deriveClientOrderId(parts) {
+        const windowBucket = Math.floor(Date.now() / CLIENT_ORDER_ID_WINDOW_MS);
+        const material = [
+            this.credentials.accountName,
+            windowBucket,
+            ...parts.map((part) => (part === undefined ? "" : String(part))),
+        ].join("|");
+        const digest = createHash("sha256")
+            .update(material)
+            .digest("hex")
+            .slice(0, CLIENT_ORDER_ID_HASH_LENGTH);
+        return `${CLIENT_ORDER_ID_PREFIX}${digest}`;
+    }
+    /**
+     * Collect the human-readable failure entries from a bulk Multi-Status (207)
+     * response body (`DELETE /orders`, `DELETE /positions`). Each element carries
+     * its own per-item HTTP status; any element with status >=
+     * {@link HTTP_STATUS_MIN_ERROR} is a failure the caller must be able to see.
+     *
+     * @param entries - Parsed 207 response array.
+     * @returns One `"<identifier>:<status>"` string per failed entry.
+     */
+    collectMultiStatusFailures(entries) {
+        return entries
+            .filter((entry) => typeof entry.status === "number" &&
+            entry.status >= HTTP_STATUS_MIN_ERROR)
+            .map((entry) => `${entry.symbol ?? entry.id ?? "unknown"}:${entry.status}`);
+    }
+    /**
+     * Flatten a single position with a marketable limit order, deriving the
+     * closing side, intent, and slippage-adjusted limit price from the latest
+     * quote. Throws when no usable quote/price is available for the symbol so the
+     * caller can record a per-position failure via {@link Promise.allSettled}
+     * without aborting the flatten of the remaining positions.
+     *
+     * @param position - The position to close.
+     * @param quotesResponse - Latest quotes keyed by symbol.
+     * @param extendedHours - Whether the closing order is an extended-hours order.
+     */
+    async closePositionWithLimitOrder(position, quotesResponse, extendedHours) {
+        const quote = quotesResponse.quotes[position.symbol];
+        if (!quote) {
+            throw new Error(`No quote available for ${position.symbol}`);
+        }
+        const qty = Math.abs(parseFloat(position.qty));
+        const side = position.side === "long" ? "sell" : "buy";
+        const positionIntent = side === "sell" ? "sell_to_close" : "buy_to_close";
+        // Use bid for sells, ask for buys.
+        const currentPrice = side === "sell" ? quote.bp : quote.ap;
+        if (!currentPrice) {
+            throw new Error(`No valid price available for ${position.symbol}`);
+        }
+        const limitSlippagePercent1 = limitPriceSlippagePercent100 / 100;
+        const limitPrice = side === "sell"
+            ? this.roundPriceForAlpaca(currentPrice * (1 - limitSlippagePercent1)) // Sell slightly lower
+            : this.roundPriceForAlpaca(currentPrice * (1 + limitSlippagePercent1)); // Buy slightly higher
+        this.log(`Creating ${extendedHours ? "extended hours " : ""}limit order to close ${position.symbol} position: ${side} ${qty} shares at $${limitPrice.toFixed(2)}`, {
+            symbol: position.symbol,
+        });
+        await this.createLimitOrder(position.symbol, qty, side, limitPrice, positionIntent, extendedHours);
+    }
+    /**
+     * Flatten every supplied position independently and surface an aggregate
+     * failure if any could not be closed. Positions are attempted concurrently
+     * with {@link Promise.allSettled} so a data gap or broker rejection on one
+     * symbol never silently prevents the others from being flattened.
+     *
+     * @param positions - Positions to flatten.
+     * @param extendedHours - Whether the closing orders are extended-hours orders.
+     * @throws Error listing every symbol that failed to flatten.
+     */
+    async flattenPositionsWithLimitOrders(positions, extendedHours) {
+        const symbols = positions.map((position) => position.symbol);
+        const quotesResponse = await marketDataAPI.getLatestQuotes(symbols);
+        const results = await Promise.allSettled(positions.map((position) => this.closePositionWithLimitOrder(position, quotesResponse, extendedHours)));
+        const failures = [];
+        results.forEach((result, index) => {
+            if (result.status === "rejected") {
+                const symbol = positions[index]?.symbol ?? "unknown";
+                const reason = result.reason instanceof Error
+                    ? result.reason.message
+                    : String(result.reason);
+                failures.push(`${symbol}: ${reason}`);
+                this.log(`Failed to close position ${symbol}: ${reason}`, {
+                    symbol,
+                    type: "error",
+                });
+            }
+        });
+        if (failures.length > 0) {
+            throw new Error(`Failed to close ${failures.length} of ${positions.length} positions: ${failures.join("; ")}`);
+        }
+        this.log(`All positions closed: ${symbols.join(", ")}`);
+    }
     handleAuthMessage(data) {
         if (data.status === "authorized") {
             this.authenticated = true;
@@ -4751,21 +4987,31 @@ class AlpacaTradingAPI {
      * @param position_intent (string) - the position intent of the order
      * @returns The created AlpacaOrder with order ID and details
      */
-    async createTrailingStop(symbol, qty, side, trailPercent100, position_intent) {
+    async createTrailingStop(symbol, qty, side, trailPercent100, position_intent, clientOrderId) {
         this.log(`Creating trailing stop ${side.toUpperCase()} ${qty} shares for ${symbol} with trail percent ${trailPercent100}%`, {
             symbol,
         });
+        const body = {
+            symbol,
+            qty: Math.abs(qty).toString(),
+            side,
+            position_intent,
+            order_class: "simple",
+            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([
+                    "trailing_stop",
+                    symbol,
+                    side,
+                    position_intent,
+                    Math.abs(qty),
+                    trailPercent100,
+                ]),
+        };
         try {
-            const order = await this.makeRequest(`/orders`, "POST", {
-                symbol,
-                qty: Math.abs(qty),
-                side,
-                position_intent,
-                order_class: "simple",
-                type: "trailing_stop",
-                trail_percent: trailPercent100, // Already in decimal form (e.g., 4 for 4%)
-                time_in_force: "gtc",
-            });
+            const order = await this.makeRequest(`/orders`, "POST", body);
             this.log(`Trailing stop order created for ${symbol}: orderId=${order.id}, trailPercent=${trailPercent100}%`, { symbol });
             return order;
         }
@@ -4797,9 +5043,15 @@ class AlpacaTradingAPI {
             time_in_force: "day",
             order_class: "simple",
         };
-        if (client_order_id !== undefined) {
-            body.client_order_id = client_order_id;
-        }
+        body.client_order_id =
+            client_order_id ??
+                this.deriveClientOrderId([
+                    "market",
+                    symbol,
+                    side,
+                    position_intent,
+                    Math.abs(qty),
+                ]);
         try {
             return await this.makeRequest("/orders", "POST", body);
         }
@@ -4900,16 +5152,31 @@ class AlpacaTradingAPI {
         }
     }
     /**
-     * Cancel all open orders
+     * Cancel all open orders.
+     *
+     * Alpaca's bulk cancel returns a 207 Multi-Status body whose top-level status
+     * is 2xx even when individual orders failed to cancel; this method inspects
+     * the per-order statuses and throws if any order could not be canceled, so a
+     * caller acting as a live-stop failsafe cannot record success while orders
+     * remain live. Transport/HTTP errors propagate unchanged (matching the
+     * throw-on-failure contract of {@link cancelOrder}).
+     *
+     * @throws Error if the bulk cancel request fails or any individual order
+     *   could not be canceled.
      */
     async cancelAllOrders() {
         this.log(`Canceling all open orders`);
-        try {
-            await this.makeRequest("/orders", "DELETE");
+        const results = await this.makeRequest("/orders", "DELETE");
+        if (!Array.isArray(results)) {
+            return;
         }
-        catch (error) {
-            this.log(`Error canceling all orders: ${error}`, { type: "error" });
+        const failures = this.collectMultiStatusFailures(results);
+        if (failures.length > 0) {
+            const detail = failures.join(", ");
+            this.log(`Error canceling all orders: ${failures.length}/${results.length} orders failed to cancel (${detail})`, { type: "error" });
+            throw new Error(`Failed to cancel ${failures.length} of ${results.length} orders: ${detail}`);
         }
+        this.log(`Successfully canceled ${results.length} open orders`);
     }
     /**
      * Cancel a specific order by its ID
@@ -4960,9 +5227,17 @@ class AlpacaTradingAPI {
             order_class: "simple",
             extended_hours,
         };
-        if (client_order_id !== undefined) {
-            body.client_order_id = client_order_id;
-        }
+        body.client_order_id =
+            client_order_id ??
+                this.deriveClientOrderId([
+                    "limit",
+                    symbol,
+                    side,
+                    position_intent,
+                    Math.abs(qty),
+                    this.roundPriceForAlpaca(limitPrice),
+                    extended_hours,
+                ]);
         try {
             return await this.makeRequest("/orders", "POST", body);
         }
@@ -4990,55 +5265,21 @@ class AlpacaTradingAPI {
                 return;
             }
             this.log(`Found ${positions.length} positions to close`);
-            // Get latest quotes for all positions
-            const symbols = positions.map((position) => position.symbol);
-            const quotesResponse = await marketDataAPI.getLatestQuotes(symbols);
-            const lengthOfQuotes = Object.keys(quotesResponse.quotes).length;
-            if (lengthOfQuotes === 0) {
-                this.log("No quotes available for positions, received 0 quotes", {
-                    type: "error",
-                });
-                return;
-            }
-            if (lengthOfQuotes !== positions.length) {
-                this.log(`Received ${lengthOfQuotes} quotes for ${positions.length} positions, expected ${positions.length} quotes`, { type: "warn" });
-                return;
-            }
-            // Create limit orders to close each position
-            for (const position of positions) {
-                const quote = quotesResponse.quotes[position.symbol];
-                if (!quote) {
-                    this.log(`No quote available for ${position.symbol}, skipping limit order`, {
-                        symbol: position.symbol,
-                        type: "warn",
-                    });
-                    continue;
-                }
-                const qty = Math.abs(parseFloat(position.qty));
-                const side = position.side === "long" ? "sell" : "buy";
-                const positionIntent = side === "sell" ? "sell_to_close" : "buy_to_close";
-                // Get the current price from the quote
-                const currentPrice = side === "sell" ? quote.bp : quote.ap; // Use bid for sells, ask for buys
-                if (!currentPrice) {
-                    this.log(`No valid price available for ${position.symbol}, skipping limit order`, {
-                        symbol: position.symbol,
-                        type: "warn",
-                    });
-                    continue;
-                }
-                // Apply slippage from config
-                const limitSlippagePercent1 = limitPriceSlippagePercent100 / 100;
-                const limitPrice = side === "sell"
-                    ? this.roundPriceForAlpaca(currentPrice * (1 - limitSlippagePercent1)) // Sell slightly lower
-                    : this.roundPriceForAlpaca(currentPrice * (1 + limitSlippagePercent1)); // Buy slightly higher
-                this.log(`Creating limit order to close ${position.symbol} position: ${side} ${qty} shares at $${limitPrice.toFixed(2)}`, {
-                    symbol: position.symbol,
-                });
-                await this.createLimitOrder(position.symbol, qty, side, limitPrice, positionIntent);
-            }
+            // Flatten each position independently. A missing quote or broker
+            // rejection on one symbol must never abort the flatten of the others; any
+            // per-position failure is surfaced as an aggregate error.
+            await this.flattenPositionsWithLimitOrders(positions, false);
         }
         else {
-            await this.makeRequest("/positions", "DELETE", undefined, options.cancel_orders ? "?cancel_orders=true" : "");
+            const results = await this.makeRequest("/positions", "DELETE", undefined, options.cancel_orders ? "?cancel_orders=true" : "");
+            if (Array.isArray(results)) {
+                const failures = this.collectMultiStatusFailures(results);
+                if (failures.length > 0) {
+                    const detail = failures.join(", ");
+                    this.log(`Error closing all positions: ${failures.length}/${results.length} positions failed to close (${detail})`, { type: "error" });
+                    throw new Error(`Failed to close ${failures.length} of ${results.length} positions: ${detail}`);
+                }
+            }
         }
     }
     /**
@@ -5055,44 +5296,22 @@ class AlpacaTradingAPI {
             this.log("No positions to close");
             return;
         }
-        await this.cancelAllOrders();
-        this.log(`Cancelled all open orders`);
-        // Get latest quotes for all positions
-        const symbols = positions.map((position) => position.symbol);
-        const quotesResponse = await marketDataAPI.getLatestQuotes(symbols);
-        // Create limit orders to close each position
-        for (const position of positions) {
-            const quote = quotesResponse.quotes[position.symbol];
-            if (!quote) {
-                this.log(`No quote available for ${position.symbol}, skipping limit order`, {
-                    symbol: position.symbol,
-                    type: "warn",
-                });
-                continue;
-            }
-            const qty = Math.abs(parseFloat(position.qty));
-            const side = position.side === "long" ? "sell" : "buy";
-            const positionIntent = side === "sell" ? "sell_to_close" : "buy_to_close";
-            // Get the current price from the quote
-            const currentPrice = side === "sell" ? quote.bp : quote.ap; // Use bid for sells, ask for buys
-            if (!currentPrice) {
-                this.log(`No valid price available for ${position.symbol}, skipping limit order`, {
-                    symbol: position.symbol,
-                    type: "warn",
-                });
-                continue;
-            }
-            // Apply slippage from config
-            const limitSlippagePercent1 = limitPriceSlippagePercent100 / 100;
-            const limitPrice = side === "sell"
-                ? this.roundPriceForAlpaca(currentPrice * (1 - limitSlippagePercent1)) // Sell slightly lower
-                : this.roundPriceForAlpaca(currentPrice * (1 + limitSlippagePercent1)); // Buy slightly higher
-            this.log(`Creating extended hours limit order to close ${position.symbol} position: ${side} ${qty} shares at $${limitPrice.toFixed(2)}`, {
-                symbol: position.symbol,
-            });
-            await this.createLimitOrder(position.symbol, qty, side, limitPrice, positionIntent, true);
+        // Cancelling stale open orders is secondary to the primary failsafe goal of
+        // flattening positions. A cancel failure is logged but must not abort the
+        // flatten, otherwise a single un-cancelable order would leave every position
+        // open. The flatten step below surfaces its own aggregate failure.
+        try {
+            await this.cancelAllOrders();
+            this.log(`Cancelled all open orders`);
+        }
+        catch (error) {
+            this.log(`Proceeding to flatten despite cancelAllOrders failure: ${error instanceof Error ? error.message : String(error)}`, { type: "error" });
         }
-        this.log(`All positions closed: ${positions.map((p) => p.symbol).join(", ")}`);
+        // Flatten each position independently with extended-hours limit orders. A
+        // missing quote or broker rejection on one symbol must never silently leave
+        // the remaining positions open; per-position failures are surfaced as an
+        // aggregate error.
+        await this.flattenPositionsWithLimitOrders(positions, true);
     }
     onTradeUpdate(callback) {
         this.tradeUpdateCallback = callback;
@@ -5171,9 +5390,12 @@ class AlpacaTradingAPI {
      * @param position_intent Position intent (buy_to_open, buy_to_close, sell_to_open, sell_to_close)
      * @param type Order type (market or limit)
      * @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.
      * @returns The created order
      */
-    async createOptionOrder(symbol, qty, side, position_intent, type, limitPrice) {
+    async createOptionOrder(symbol, qty, side, position_intent, type, limitPrice, clientOrderId) {
         if (!Number.isInteger(qty) || qty <= 0) {
             this.log("Quantity must be a positive whole number for option orders", {
                 type: "error",
@@ -5198,6 +5420,19 @@ 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);
     }
     /**
@@ -5206,9 +5441,12 @@ class AlpacaTradingAPI {
      * @param qty Quantity of the multi-leg order (must be a whole number)
      * @param type Order type (market or limit)
      * @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.
      * @returns The created multi-leg order
      */
-    async createMultiLegOptionOrder(legs, qty, type, limitPrice) {
+    async createMultiLegOptionOrder(legs, qty, type, limitPrice, clientOrderId) {
         if (!Number.isInteger(qty) || qty <= 0) {
             this.log("Quantity must be a positive whole number for option orders", {
                 type: "error",
@@ -5234,6 +5472,17 @@ 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);
     }
     /**
@@ -5711,9 +5960,26 @@ class AlpacaTradingAPI {
             extended_hours: extendedHours,
             position_intent: side === "buy" ? "buy_to_open" : "sell_to_open",
         };
-        if (clientOrderId) {
-            orderData.client_order_id = clientOrderId;
-        }
+        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,
+                ]);
         // Add limit price for limit orders
         if (type === "limit" && limitPrice !== undefined) {
             orderData.limit_price = this.roundPriceForAlpaca(limitPrice).toString();
@@ -5771,9 +6037,18 @@ class AlpacaTradingAPI {
  *
  * @param auth - The authentication details for Alpaca
  * @returns Validated authentication credentials
+ * @throws UnsupportedBrokerError if `auth.provider` is set to a non-ALPACA provider
  * @throws Error if authentication details are missing or invalid
  */
 async function validateAuth(auth) {
+    // Multi-broker guard (SP2): this seam only resolves Alpaca credentials.
+    // `auth.provider` is typed as "ALPACA" on AlpacaAuth, but untyped callers
+    // (or future BrokerAuth adapters) may pass other providers at runtime —
+    // fail fast with a typed error instead of silently hitting Alpaca hosts.
+    const requestedProvider = auth.provider;
+    if (requestedProvider !== undefined && requestedProvider !== "ALPACA") {
+        throw new UnsupportedBrokerError(requestedProvider);
+    }
     const inlineKey = auth.alpacaApiKey && auth.alpacaApiKey.trim().length > 0
         ? auth.alpacaApiKey
         : undefined;
@@ -5795,26 +6070,54 @@ async function validateAuth(auth) {
         };
     }
     if (auth.adapticAccountId) {
-        const client = await getSharedApolloClient();
-        const alpacaAccount = (await adaptic$1.alpacaAccount.get({
-            id: auth.adapticAccountId,
-        }, client));
-        if (!alpacaAccount || !alpacaAccount.APIKey || !alpacaAccount.APISecret) {
-            throw new Error("Alpaca account not found or incomplete");
-        }
-        validateAlpacaCredentials({
-            apiKey: alpacaAccount.APIKey,
-            apiSecret: alpacaAccount.APISecret,
-            isPaper: alpacaAccount.type === "PAPER",
-        });
-        return {
-            APIKey: alpacaAccount.APIKey,
-            APISecret: alpacaAccount.APISecret,
-            type: alpacaAccount.type,
-        };
+        return resolveBrokerCredentials(auth.adapticAccountId);
     }
     throw new Error("Either adapticAccountId or both alpacaApiKey and alpacaApiSecret must be provided");
 }
+/**
+ * Resolves broker credentials for a backend brokerage-account id.
+ *
+ * This is the SINGLE backend-coupled credential lookup in this package —
+ * every account-id-based credential resolution must flow through here so
+ * that backend model changes touch exactly one function.
+ *
+ * SP2 transition note: today the id is an `AlpacaAccount.id` resolved via
+ * `adaptic.alpacaAccount.get`. When backend-legacy publishes the
+ * `BrokerageAccount` model (backfilled with `id = AlpacaAccount.id`, so the
+ * id space is identical), the switch to `adaptic.brokerageAccount.get`
+ * happens INSIDE this function only, following the sequencing rule in
+ * CLAUDE.md ("Multi-Broker Sequencing Rule"): backend-legacy publishes →
+ * utils bumps the dependency and switches this helper → utils publishes →
+ * engine bumps its pin. Do not reference `brokerageAccount` anywhere in
+ * this package before the pinned backend-legacy version exports it.
+ *
+ * The lookup is a no-cache GraphQL round trip to backend-legacy; callers
+ * holding inline credentials should never reach it (see `validateAuth`
+ * precedence).
+ *
+ * @param brokerageAccountId - Backend brokerage-account id (currently the AlpacaAccount id)
+ * @returns Validated authentication credentials
+ * @throws Error if the account is not found or its credentials are incomplete
+ */
+async function resolveBrokerCredentials(brokerageAccountId) {
+    const client = await getSharedApolloClient();
+    const alpacaAccount = (await adaptic$1.alpacaAccount.get({
+        id: brokerageAccountId,
+    }, client));
+    if (!alpacaAccount || !alpacaAccount.APIKey || !alpacaAccount.APISecret) {
+        throw new Error("Alpaca account not found or incomplete");
+    }
+    validateAlpacaCredentials({
+        apiKey: alpacaAccount.APIKey,
+        apiSecret: alpacaAccount.APISecret,
+        isPaper: alpacaAccount.type === "PAPER",
+    });
+    return {
+        APIKey: alpacaAccount.APIKey,
+        APISecret: alpacaAccount.APISecret,
+        type: alpacaAccount.type,
+    };
+}
 
 /**
  * Legacy Alpaca Utility Functions
@@ -7944,6 +8247,7 @@ var index$1 = /*#__PURE__*/Object.freeze({
     getOrders: getOrders$1,
     makeRequest: makeRequest,
     replaceOrder: replaceOrder$1,
+    resolveBrokerCredentials: resolveBrokerCredentials,
     roundPriceForAlpaca: roundPriceForAlpaca$5,
     updateConfiguration: updateConfiguration,
     validateAuth: validateAuth
@@ -8351,6 +8655,13 @@ var atrNs = /*#__PURE__*/Object.freeze({
 });
 
 const ALPACA_API_BASE = MARKET_DATA_API.CRYPTO;
+/**
+ * Hard upper bound on the number of paginated news pages fetched in a single
+ * {@link fetchNews} call. Acts as a runaway-loop backstop that is independent of
+ * the caller-supplied `limit`, mirroring the max-page guard the equities
+ * paginator already enforces.
+ */
+const MAX_NEWS_PAGES = 100;
 /**
  * Fetches cryptocurrency bars for the specified parameters.
  * This function retrieves historical price data for multiple cryptocurrencies.
@@ -8450,17 +8761,25 @@ async function fetchNews(params, auth) {
         include_content: includeContent.toString(),
         limit: limit.toString(),
     });
-    const url = `${ALPACA_API_BASE}/news?${queryParams}`;
-    logIfDebug(`Fetching news from: ${url}`);
-    let newsArticles = [];
+    const authHeaders = {
+        "APCA-API-KEY-ID": auth.APIKey,
+        "APCA-API-SECRET-KEY": auth.APISecret,
+    };
+    const newsArticles = [];
     let pageToken = null;
-    let hasMorePages = true;
-    while (hasMorePages) {
+    let pageCount = 0;
+    while (pageCount < MAX_NEWS_PAGES) {
+        // Rebuild the request URL on every iteration so the pagination cursor is
+        // actually applied. Using `set` (not `append`) overwrites the previous
+        // cursor instead of accumulating stale `page_token` values across pages.
         if (pageToken) {
-            queryParams.append("page_token", pageToken);
+            queryParams.set("page_token", pageToken);
         }
+        const url = `${ALPACA_API_BASE}/news?${queryParams.toString()}`;
+        logIfDebug(`Fetching news from: ${url}`);
         await withRetry(async () => {
             const response = await fetch(url, {
+                headers: authHeaders,
                 signal: createTimeoutSignal(DEFAULT_TIMEOUTS.ALPACA_API),
             });
             if (!response.ok) {
@@ -8468,7 +8787,7 @@ async function fetchNews(params, auth) {
                 throw new Error(`Alpaca API error (${response.status}): ${errorText}`);
             }
             const data = await response.json();
-            newsArticles = newsArticles.concat(data.news.map((article) => ({
+            const pageArticles = (data.news ?? []).map((article) => ({
                 id: article.id,
                 author: article.author,
                 content: article.content,
@@ -8480,11 +8799,17 @@ async function fetchNews(params, auth) {
                 url: article.url,
                 symbols: article.symbols,
                 images: article.images,
-            })));
+            }));
+            newsArticles.push(...pageArticles);
             pageToken = data.next_page_token ?? null;
-            hasMorePages = !!pageToken;
-            logIfDebug(`Received ${data.news.length} news articles. More pages: ${hasMorePages}`);
+            logIfDebug(`Received ${pageArticles.length} news articles. Next page token: ${pageToken ? "present" : "none"}`);
         }, API_RETRY_CONFIGS.CRYPTO, `Crypto.fetchNews(${symbol})`);
+        pageCount++;
+        // Terminate once the API reports no further pages or once we have
+        // accumulated at least the requested number of articles.
+        if (!pageToken || newsArticles.length >= limit) {
+            break;
+        }
     }
     // If sort is "asc" and limit is 10, return only the 10 most recent articles
     if (sort === "asc" && limit === 10) {
@@ -9701,33 +10026,138 @@ const formatIndicesBarData = (data) => {
 };
 
 // price-utils.ts
+// ---------------------------------------------------------------------------
+// Transaction-cost (fee) model
+//
+// Alpaca's REST order object does not expose the realized per-order fee, so the
+// transaction cost is reconstructed from the published fee schedules, branching
+// on the order's ACTUAL asset class (never a hardcoded STOCK). Every rate is a
+// named constant sourced from Alpaca / SEC / FINRA public schedules (2024-2025)
+// so it can be audited and updated in one place.
+// ---------------------------------------------------------------------------
+/** Basis points in one whole unit (1 = 10,000 bps). */
+const BPS_PER_UNIT = 10_000;
+/** Shares represented by one US listed option contract. */
+const OPTIONS_CONTRACT_MULTIPLIER = 100;
+/**
+ * SEC Section 31 fee, charged on the principal of SELL orders for equities and
+ * options. FY2024+ rate: USD 8.00 per USD 1,000,000 of principal.
+ */
+const SEC_SECTION31_FEE_PER_USD = 8.0 / 1_000_000;
+/** FINRA Trading Activity Fee (TAF) for equity sells: USD per share sold. */
+const FINRA_TAF_EQUITY_PER_SHARE = 0.000166;
+/** FINRA TAF for option sells: USD per contract sold. */
+const FINRA_TAF_OPTIONS_PER_CONTRACT = 0.00279;
+/** FINRA TAF is capped per trade regardless of size. */
+const FINRA_TAF_MAX_PER_TRADE = 8.3;
+/** OCC clearing fee per option contract, capped per trade. */
+const OCC_CLEARING_FEE_PER_CONTRACT = 0.02;
+const OCC_CLEARING_FEE_MAX_PER_TRADE = 55.0;
+/**
+ * Options Regulatory Fee (ORF) pass-through, charged on both sides, USD per
+ * contract. Published, exchange-set pass-through rate.
+ */
+const OPTIONS_REGULATORY_FEE_PER_CONTRACT = 0.02685;
+/**
+ * Alpaca crypto TAKER fee schedule as `[minTrailing30dVolumeUsd, takerBps]`,
+ * ordered ascending by volume threshold. Market orders are takers; absent a
+ * known trailing-30-day volume we conservatively select the tier-1 (highest)
+ * taker rate. Source: Alpaca Crypto fee schedule.
+ */
+const ALPACA_CRYPTO_TAKER_FEE_TIERS_BPS = [
+    [0, 25],
+    [100_000, 22],
+    [500_000, 20],
+    [1_000_000, 18],
+    [10_000_000, 15],
+    [25_000_000, 13],
+    [50_000_000, 12],
+    [100_000_000, 10],
+];
+/**
+ * Resolve the applicable Alpaca crypto taker fee (in bps) for a trailing
+ * 30-day USD volume. Defaults to the tier-1 rate when the volume is unknown.
+ * @param trailing30dVolumeUsd - Trailing 30-day traded notional in USD.
+ * @returns The taker fee in basis points.
+ */
+function resolveCryptoTakerBps(trailing30dVolumeUsd) {
+    let bps = ALPACA_CRYPTO_TAKER_FEE_TIERS_BPS[0][1];
+    for (const [threshold, tierBps] of ALPACA_CRYPTO_TAKER_FEE_TIERS_BPS) {
+        if (trailing30dVolumeUsd >= threshold) {
+            bps = tierBps;
+        }
+        else {
+            break;
+        }
+    }
+    return bps;
+}
+/**
+ * Computes the realized transaction cost (fees + regulatory charges) for the
+ * Alpaca order backing a single {@link types.Action}, branching on the order's
+ * actual asset class. Returns 0 only when there is genuinely no order to price
+ * (no linked order id, order not found, or nothing filled) — never as a
+ * fabricated success.
+ * @param action - The action whose linked Alpaca order should be priced.
+ * @param trade - The parent trade (supplies the Alpaca account id).
+ * @param alpacaAccount - The Alpaca account supplying broker credentials.
+ * @returns The total fee in account currency (USD).
+ */
 const calculateFees = async (action, trade, alpacaAccount) => {
-    let fee = 0;
     const alpacaOrderId = action.alpacaOrderId;
     if (!alpacaOrderId)
-        return fee;
+        return 0;
     const order = await getOrder$1({
         adapticAccountId: trade.alpacaAccountId,
         alpacaApiKey: alpacaAccount.APIKey,
         alpacaApiSecret: alpacaAccount.APISecret,
     }, alpacaOrderId);
     if (!order)
-        return fee;
-    const assetType = "STOCK";
-    Number(order.qty) || 0;
-    order.notional || 0;
-    Number(order.filled_avg_price || order.limit_price || order.stop_price) ||
+        return 0;
+    const filledQty = Number(order.filled_qty) || 0;
+    const filledPrice = Number(order.filled_avg_price ?? order.limit_price ?? order.stop_price) ||
         0;
-    switch (assetType) {
-        case "STOCK":
-            // Currently zero fees for stocks via Alpaca
-            fee = 0;
-            break;
-        default:
-            fee = 0;
-            break;
+    // Realized notional prefers the actual fill (qty * avg price); it falls back
+    // to the order's notional field for dollar-notional (fractional) orders.
+    const notional = filledQty > 0 && filledPrice > 0
+        ? filledQty * filledPrice
+        : Number(order.notional ?? 0) || 0;
+    if (notional <= 0)
+        return 0;
+    const isSell = order.side === "sell";
+    switch (order.asset_class) {
+        case "crypto": {
+            // Crypto fees are bps of notional. Without a known 30-day volume we use
+            // the conservative tier-1 taker rate.
+            const takerBps = resolveCryptoTakerBps(0);
+            return (notional * takerBps) / BPS_PER_UNIT;
+        }
+        case "us_option": {
+            const contracts = filledQty > 0 ? filledQty : Number(order.qty) || 0;
+            const occFee = Math.min(contracts * OCC_CLEARING_FEE_PER_CONTRACT, OCC_CLEARING_FEE_MAX_PER_TRADE);
+            const orfFee = contracts * OPTIONS_REGULATORY_FEE_PER_CONTRACT;
+            let fee = occFee + orfFee;
+            if (isSell) {
+                // Option premium is quoted per share; SEC fee applies to the full
+                // principal (premium * contract multiplier).
+                const optionPrincipal = notional * OPTIONS_CONTRACT_MULTIPLIER;
+                const secFee = optionPrincipal * SEC_SECTION31_FEE_PER_USD;
+                const taf = Math.min(contracts * FINRA_TAF_OPTIONS_PER_CONTRACT, FINRA_TAF_MAX_PER_TRADE);
+                fee += secFee + taf;
+            }
+            return fee;
+        }
+        case "us_equity":
+        default: {
+            // Alpaca charges USD 0 commission on US equities; only sell-side
+            // regulatory charges (SEC Section 31 + FINRA TAF) apply.
+            if (!isSell)
+                return 0;
+            const secFee = notional * SEC_SECTION31_FEE_PER_USD;
+            const taf = Math.min(filledQty * FINRA_TAF_EQUITY_PER_SHARE, FINRA_TAF_MAX_PER_TRADE);
+            return secFee + taf;
+        }
     }
-    return fee;
 };
 const computeTotalFees = async (trade) => {
     let totalFees = 0;
@@ -10596,16 +11026,76 @@ async function calculateExpenseRatio({ accountId, client, alpacaAccount, }) {
         return "N/A";
     }
     const equity = parseFloat(accountDetails.equity);
-    // Fetch portfolio expenses from your system (Assuming you have this data)
-    const expenses = await getPortfolioExpensesFromYourSystem();
-    // Calculate expense ratio
+    // 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%.
+    const auth = {
+        adapticAccountId: alpacaAccountId,
+        alpacaApiKey: alpacaAccount?.APIKey,
+        alpacaApiSecret: alpacaAccount?.APISecret,
+    };
+    let expenses;
+    try {
+        expenses = await fetchTrailingFeeExpenses(auth);
+    }
+    catch (error) {
+        getLogger().warn("Failed to fetch Alpaca account fee activities for expense ratio.", { error });
+        return "N/A";
+    }
+    // Calculate expense ratio (trailing fees as a percentage of current equity).
     const expenseRatio = (expenses / equity) * 100;
     return `${expenseRatio.toFixed(2)}%`;
 }
-// Mock function to represent fetching expenses from your system
-async function getPortfolioExpensesFromYourSystem(_accountId) {
-    // Implement this function based on your data storage
-    return 0; // Placeholder
+/** Trailing window over which account fees are aggregated for the expense ratio. */
+const EXPENSE_TRAILING_WINDOW_DAYS = 365;
+/** Milliseconds in one day. */
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/** Alpaca account-activity types that represent fees/regulatory charges. */
+const FEE_ACTIVITY_TYPES = "FEE,REG,CFEE";
+/** Page size for the paginated Alpaca account-activities endpoint. */
+const ACTIVITIES_PAGE_SIZE = 100;
+/** Hard cap on activity pages to bound pagination on unexpected responses. */
+const ACTIVITIES_MAX_PAGES = 1000;
+/**
+ * Aggregates the account's fee/regulatory charges over the trailing window from
+ * the Alpaca account-activities endpoint, following id-based pagination.
+ * @param auth - Alpaca authentication (account id and/or direct API keys).
+ * @returns Total fees in account currency (USD) as a positive number.
+ */
+async function fetchTrailingFeeExpenses(auth) {
+    const after = new Date(Date.now() - EXPENSE_TRAILING_WINDOW_DAYS * MS_PER_DAY).toISOString();
+    let total = 0;
+    let pageToken;
+    for (let page = 0; page < ACTIVITIES_MAX_PAGES; page++) {
+        const queryParams = new URLSearchParams({
+            activity_types: FEE_ACTIVITY_TYPES,
+            after,
+            page_size: String(ACTIVITIES_PAGE_SIZE),
+        });
+        if (pageToken) {
+            queryParams.append("page_token", pageToken);
+        }
+        const activities = await makeRequest(auth, {
+            endpoint: "/account/activities",
+            method: "GET",
+            queryString: `?${queryParams.toString()}`,
+        });
+        if (!Array.isArray(activities) || activities.length === 0) {
+            break;
+        }
+        for (const activity of activities) {
+            const amount = parseFloat(activity.net_amount ?? "");
+            if (Number.isFinite(amount)) {
+                // Fee entries are debits (negative net_amount); accumulate magnitude.
+                total += Math.abs(amount);
+            }
+        }
+        if (activities.length < ACTIVITIES_PAGE_SIZE) {
+            break;
+        }
+        pageToken = activities[activities.length - 1].id;
+    }
+    return total;
 }
 /**
  * Calculates the liquidity ratio for a given Alpaca account.
@@ -11166,9 +11656,16 @@ function calculateBetaFromReturns(portfolioReturns, benchmarkReturns) {
     const denom = n > 1 ? n - 1 : 1;
     covariance /= denom;
     variance /= denom;
-    // Handle zero variance
-    if (variance === 0) {
-        getLogger().warn("Benchmark variance is zero. Setting beta to 0.");
+    // Handle zero (or numerically-degenerate) variance. A constant benchmark
+    // series can still produce a tiny nonzero variance because the computed
+    // mean differs from the constant by an ulp; dividing covariance by that
+    // rounding noise yields a meaningless beta. Treat any variance at or
+    // below the summation noise floor — (n * eps * |mean|)^2, the square of
+    // the worst-case naive-summation error — as zero. When the mean is
+    // exactly 0 this reduces to the exact zero check.
+    const varianceNoiseFloor = (n * Number.EPSILON * Math.abs(averageBenchmarkReturn)) ** 2;
+    if (variance <= varianceNoiseFloor) {
+        getLogger().warn("Benchmark variance is zero or below the floating-point noise floor. Setting beta to 0.");
         return {
             beta: 0,
             covariance,
@@ -11258,6 +11755,58 @@ async function calculateInformationRatio(portfolioHistory, benchmarkBars) {
     }
     return informationRatio.toFixed(4);
 }
+/**
+ * Maps a portfolio-history timeframe token to the Alpaca market-data
+ * {@link TimeFrame} accepted by the historical-bars endpoint. Benchmark
+ * comparison is daily by default when no timeframe is supplied.
+ * @param timeframe - The portfolio-history timeframe token.
+ * @returns The equivalent Alpaca market-data timeframe.
+ */
+function toAlpacaTimeFrame(timeframe) {
+    switch (timeframe) {
+        case "1Min":
+            return "1Min";
+        case "5Min":
+            return "5Min";
+        case "15Min":
+            return "15Min";
+        case "1H":
+            return "1Hour";
+        case "1D":
+            return "1Day";
+        default:
+            return "1Day";
+    }
+}
+/** Milliseconds per second, for RFC-3339 → Unix-second conversion. */
+const MS_PER_SECOND = 1000;
+/**
+ * Fetches benchmark OHLCV bars from the wrapped Alpaca market-data vendor and
+ * maps them into {@link BenchmarkBar}s (Unix-second timestamp + close price)
+ * expected by the alpha/beta/information-ratio calculators.
+ * @param request - Benchmark symbol, RFC-3339 start/end, and timeframe token.
+ * @returns The benchmark bars, sorted ascending by time; empty if none.
+ */
+async function fetchBenchmarkBars(request) {
+    const { symbol, start, end, timeframe } = request;
+    const response = await marketDataAPI.getHistoricalBars({
+        symbols: [symbol],
+        timeframe: toAlpacaTimeFrame(timeframe),
+        start,
+        end,
+        sort: "asc",
+    });
+    const bars = response.bars[symbol];
+    if (!Array.isArray(bars) || bars.length === 0) {
+        return [];
+    }
+    return bars
+        .map((bar) => ({
+        t: Math.floor(new Date(bar.t).getTime() / MS_PER_SECOND),
+        c: bar.c,
+    }))
+        .filter((bar) => Number.isFinite(bar.t) && Number.isFinite(bar.c));
+}
 /**
  * Fetches performance metrics for a given Alpaca account.
  * @param params - The parameters for fetching performance metrics.
@@ -11322,7 +11871,10 @@ async function fetchPerformanceMetrics({ params, client, accountId, alpacaAccoun
             getLogger().error("[fetchPerformanceMetrics] Error fetching portfolio history:", error);
             throw new Error("Failed to retrieve portfolio history data");
         }
-        // Fetch benchmark data with enhanced error handling
+        // Fetch benchmark data directly from the wrapped Alpaca market-data vendor.
+        // (Previously this hit a relative "/api/market-data/historical-prices"
+        // Next.js route that only resolves in a browser; in a Node/engine runtime
+        // the relative fetch always threw, silently zeroing out alpha/beta/IR.)
         const benchmarkSymbol = "SPY";
         let benchmarkBars = [];
         try {
@@ -11333,24 +11885,16 @@ async function fetchPerformanceMetrics({ params, client, accountId, alpacaAccoun
                     : params?.period
                         ? params?.period
                         : "1Y",
-                outputFormat: "unix-ms",
+                outputFormat: "iso",
                 intraday_reporting: params?.intraday_reporting,
             });
-            const response = await fetch(`/api/market-data/historical-prices?symbol=${benchmarkSymbol}&start=${start.toString()}&end=${end.toString()}&timeframe=${params.timeframe}`, {
-                method: "GET",
-                headers: {
-                    "Content-Type": "application/json",
-                },
-                signal: createTimeoutSignal(DEFAULT_TIMEOUTS.GENERAL),
+            benchmarkBars = await fetchBenchmarkBars({
+                symbol: benchmarkSymbol,
+                start: String(start),
+                end: String(end),
+                timeframe: params.timeframe,
             });
-            if (!response.ok) {
-                const errorText = await response.text();
-                throw new Error(`Failed to fetch benchmark data: ${response.statusText} - ${errorText}`);
-            }
-            benchmarkBars = await response.json();
-            if (!benchmarkBars ||
-                !Array.isArray(benchmarkBars) ||
-                benchmarkBars.length === 0) {
+            if (benchmarkBars.length === 0) {
                 throw new Error("Received empty or invalid benchmark data");
             }
         }
@@ -12347,8 +12891,33 @@ const timeDiffString = (milliseconds) => {
     return parts.join(", ");
 };
 
+/**
+ * Multi-broker foundation types
+ *
+ * Provider-agnostic brokerage types for the org → fund → brokerageAccount →
+ * broker alignment (SP2). These are strictly ADDITIVE: the existing
+ * Alpaca-specific types (`AlpacaAuth`, `AlpacaCredentials`,
+ * `AlpacaClientConfig`) remain the canonical shapes consumed by the engine
+ * and are unchanged. New provider-aware call sites should prefer these
+ * types; only ALPACA is implemented today — IBKR and COINBASE arms are
+ * typed placeholders that resolve to `UnsupportedBrokerError` at runtime.
+ *
+ * @module @adaptic/utils/types/broker-types
+ */
+/**
+ * Type guard narrowing {@link BrokerCredentials} to the implemented
+ * ALPACA arm.
+ *
+ * @param credentials - Any broker credentials union member
+ * @returns True when the credentials belong to the ALPACA provider
+ */
+function isAlpacaBrokerCredentials(credentials) {
+    return credentials.provider === "ALPACA";
+}
+
 var Types = /*#__PURE__*/Object.freeze({
-    __proto__: null
+    __proto__: null,
+    isAlpacaBrokerCredentials: isAlpacaBrokerCredentials
 });
 
 /**
@@ -50661,12 +51230,16 @@ class AlpacaClient {
 }
 // Client cache for connection pooling
 const clientCache = new Map();
+// Provider discriminant for cache-key scoping (multi-broker SP2 seam):
+// keeps Alpaca pool entries disjoint from future providers that might
+// reuse an identical apiKey string.
+const ALPACA_PROVIDER = "ALPACA";
 /**
  * Create or get a cached Alpaca client
- * Uses apiKey as cache key for connection pooling
+ * Uses provider + apiKey + accountType as cache key for connection pooling
  */
 function createAlpacaClient(config) {
-    const cacheKey = `${config.apiKey}-${config.accountType}`;
+    const cacheKey = `${ALPACA_PROVIDER}-${config.apiKey}-${config.accountType}`;
     if (clientCache.has(cacheKey)) {
         log$k(`Returning cached client for ${config.accountType}`, { type: "debug" });
         return clientCache.get(cacheKey);
@@ -68786,6 +69359,49 @@ function verifyFetchKeepAlive() {
     };
 }
 
+/**
+ * Broker Client Factory
+ *
+ * Provider-agnostic entry point for broker trading clients (SP2 multi-broker
+ * seam). Strictly ADDITIVE: `createAlpacaClient`, `createAlpacaTradingAPI`,
+ * and `createAlpacaMarketDataAPI` remain the canonical Alpaca factories and
+ * are unchanged. Only ALPACA is implemented — all other providers throw a
+ * typed {@link UnsupportedBrokerError}.
+ *
+ * @module @adaptic/utils/broker
+ */
+/**
+ * Create (or reuse from cache) a broker trading client for the given
+ * credentials.
+ *
+ * ALPACA delegates to `createAlpacaClient`, whose connection-pool cache key
+ * is provider-scoped (`ALPACA-<apiKey>-<accountType>`), so a future
+ * provider reusing an identical apiKey string can never collide with an
+ * Alpaca client. All other providers — including unknown provider strings
+ * from untyped callers — throw {@link UnsupportedBrokerError}.
+ *
+ * @param credentials - Discriminated broker credentials union
+ * @returns A provider-appropriate {@link BrokerTradingClient}
+ * @throws UnsupportedBrokerError for any provider other than ALPACA
+ */
+function createBrokerClient(credentials) {
+    switch (credentials.provider) {
+        case "ALPACA":
+            return createAlpacaClient({
+                apiKey: credentials.apiKey,
+                apiSecret: credentials.apiSecret,
+                accountType: credentials.type,
+            });
+        case "IBKR":
+        case "COINBASE":
+            throw new UnsupportedBrokerError(credentials.provider);
+    }
+    // Unreachable for typed callers (the switch above is exhaustive), but
+    // untyped runtime callers may pass an unrecognised provider string —
+    // fail fast with the same typed error rather than undefined behaviour.
+    throw new UnsupportedBrokerError(String(credentials.provider));
+}
+
 /**
  * Mirror enums for the trading policy preference system.
  * These enums are used by both the trading engine and the frontend app
@@ -69866,5 +70482,5 @@ const adaptic = {
 };
 const adptc = adaptic;
 
-export { API_RETRY_CONFIGS, AVNewsArticleSchema, AVNewsResponseSchema, AdapticUtilsError, AlpacaAccountDetailsSchema, AlpacaApiError, AlpacaBarSchema, AlpacaClient, AlpacaCryptoBarsResponseSchema, AlpacaHistoricalBarsResponseSchema, AlpacaLatestBarsResponseSchema, AlpacaLatestQuotesResponseSchema, AlpacaLatestTradesResponseSchema, AlpacaMarketDataAPI, AlpacaNewsArticleSchema, AlpacaNewsResponseSchema, AlpacaOrderSchema, AlpacaOrdersArraySchema, AlpacaPortfolioHistoryResponseSchema, AlpacaPositionSchema, AlpacaPositionsArraySchema, AlpacaQuoteSchema, AlpacaTradeSchema, AlpacaTradingAPI, AlphaVantageError, AlphaVantageQuoteResponseSchema, AssetAllocationEngine, AuthenticationError, AutonomyMode, BTC_PAIRS, BarError, CircuitOpenError, CryptoDataError, CryptoOrderError, DEFAULT_CACHE_OPTIONS, DEFAULT_RISK_FREE_RATE, DEFAULT_TIMEOUTS, DEFAULT_TRADING_POLICY, DataFormatError, DecisionMemoryOutcome, DecisionOutcome, DecisionRecordStatus, HttpClientError, HttpServerError, KEEP_ALIVE_DEFAULTS, LlmProvider, MARKET_DATA_API, MassiveAggregatesResponseSchema, MassiveApiError, MassiveDailyOpenCloseSchema, MassiveErrorResponseSchema, MassiveGroupedDailyResponseSchema, MassiveLastTradeResponseSchema, MassiveTickerDetailsResponseSchema, MassiveTickerInfoSchema, MassiveTradeSchema as MassiveTradeZodSchema, MassiveTradesResponseSchema, NetworkError, NewsError, OptionStrategyError, OptionsDataError, OverlaySeverity, OverlayStatus, OverlayType, QuoteError, RISK_FREE_RATE_TTL_MS, RateLimitError, RawMassivePriceDataSchema, StampedeProtectedCache, TRADING_API, TimeoutError, TokenBucketRateLimiter, TradeError, TrailingStopValidationError, USDC_PAIRS, USDT_PAIRS, USD_PAIRS, ValidationError, ValidationResponseError, WEBSOCKET_STREAMS, WebSocketError, account, adaptic, adptc, alpaca, analyzeBars, approximateImpliedVolatility, atrNs as atr, bracketOrders, buildOCCSymbol, buildOptionSymbol, buyCryptoNotional, buyToClose, buyToOpen, buyWithStopLoss, buyWithTrailingStop, calculateMoneyness, calculateOrderValue, calculatePeriodPerformance, calculatePutCallRatio, calculateTotalFilledValue, cancelAllCryptoOrders, cancelOCOOrder, cancelOTOOrder, cancelTrailingStop, cancelTrailingStopsForSymbol, checkTradingEligibility, clearClientCache, clock, closeAllOptionPositions, closeOptionPosition, createAlpacaClient, createAlpacaMarketDataAPI, createAlpacaTradingAPI, createBracketOrder, createButterflySpread, createClientFromEnv, createCoveredCall, createCryptoLimitOrder, createCryptoMarketOrder, createCryptoOrder, createCryptoStopLimitOrder, createCryptoStopOrder, createExecutorFromTradingAPI, createIronCondor$1 as createIronCondor, createIronCondor as createIronCondorAdvanced, createMultiLegOptionOrder, createOCOOrder, createOTOOrder, createOptionOrder, createPortfolioTrailingStops, createProtectiveBracket, createStampedeProtectedCache, createStraddle$1 as createStraddle, createStraddle as createStraddleAdvanced, createStrangle$1 as createStrangle, createStrangle as createStrangleAdvanced, createStreamManager, createTimeoutSignal, createTrailingStop, createVerticalSpread$1 as createVerticalSpread, createVerticalSpread as createVerticalSpreadAdvanced, entryWithPercentStopLoss, exerciseOption, extractGreeks, filterByExpiration, filterByStrike, filterByType, filterOrdersByDateRange, findATMOptions, findATMStrikes, findNearestExpiration, findOptionsByDelta, formatOrderForLog, formatOrderSummary, generateOptimalAllocation, getAccountConfiguration, getAccountDetails, getAccountSummary, getAgentPoolStatus, getAllOrders, getAlpacaCalendar, getAlpacaClock, getAverageDailyVolume, getBars, getBuyingPower, getCachedRiskFreeRateSync, getCachedRiskFreeRateSyncWithProvenance, getCrypto24HourChange, getCryptoBars, getCryptoDailyPrices, getCryptoPairsByQuote, getCryptoPrice, getCryptoSnapshots, getCryptoSpread, getCryptoStreamUrl, getCryptoTrades, getCurrentPrice, getCurrentPrices, getDailyPrices, getDailyReturns, getDaysToExpiration, getDefaultRiskProfile, getEquityCurve, getExpirationDates, getFilledOrders, getGroupedOptionChain, getHistoricalOptionsBars, getHistoricalTrades, getIntradayPrices, getLatestBars, getLatestCryptoQuotes, getLatestCryptoTrades, getLatestNews, getLatestOptionsQuotes, getLatestOptionsTrades, getLatestQuote, getLatestQuotes, getLatestTrade, getLatestTrades, getLogger, getMarginInfo, getNews, getNewsForSymbols, getOCOOrderStatus, getOTOOrderStatus, getOpenCryptoOrders, getOpenOrders$1 as getOpenOrdersQuery, getOpenTrailingStops, getOptionChain, getOptionContract, getOptionContracts, getOptionSpread, getOptionsChain, getOptionsSnapshots, getOptionsStreamUrl, getOptionsTradingLevel, getOrderHistory, getOrdersBySymbol, getPDTStatus, getPopularCryptoPairs, getPortfolioHistory, getPreviousClose, getPriceRange, getRiskFreeRate, getRiskFreeRateWithProvenance, getSpread, getSpreads, getStockStreamUrl, getStrikePrices, getSupportedCryptoPairs, getSymbolSentiment, getTimeout, getTradeVolume, getTradingApiUrl, getTradingWebSocketUrl, getTrailingStopHWM, groupOrdersByStatus, groupOrdersBySymbol, hasActiveTrailingStop, hasGoodLiquidity as hasOptionLiquidity, hasGoodLiquidity$1 as hasStockLiquidity, hasSufficientVolume, httpAgent, httpsAgent, isContractTradable, isCryptoPair, isExpiringWithin, isMarginAccount, isOptionOrderCancelable, isOptionOrderTerminal, isOrderFillable, isOrderFilled, isOrderOpen, isOrderTerminal$1 as isOrderTerminalStatus, isSupportedCryptoPair, isTransientNetworkError, index$1 as legacyApi, limitBuyWithTakeProfit, ocoOrders, orderUtils, otoOrders, paginate, paginateAll, parseOCCSymbol, protectLongPosition, protectShortPosition, rateLimiters, resetLogger, resetRiskFreeRateCache, riskNs as risk, rollOptionPosition, roundPriceForAlpaca$3 as roundPriceForAlpaca, roundPriceForAlpacaNumber, safeValidateResponse, searchNews, sellAllCrypto, sellCryptoNotional, sellToClose, sellToOpen, setLogger, setRiskFreeRate, shortWithStopLoss, sortOrdersByDate, strategyNs as strategy, index as tradingPolicy, trailingStops, updateAccountConfiguration, updateTrailingStop, validateAlpacaCredentials, validateAlphaVantageApiKey, validateMassiveApiKey$1 as validateMassiveApiKey, validateMultiLegOrder, validateResponse, verifyFetchKeepAlive, volatilityNs as volatility, waitForOrderFill, withRetry, withTimeout };
+export { API_RETRY_CONFIGS, AVNewsArticleSchema, AVNewsResponseSchema, AdapticUtilsError, AlpacaAccountDetailsSchema, AlpacaApiError, AlpacaBarSchema, AlpacaClient, AlpacaCryptoBarsResponseSchema, AlpacaHistoricalBarsResponseSchema, AlpacaLatestBarsResponseSchema, AlpacaLatestQuotesResponseSchema, AlpacaLatestTradesResponseSchema, AlpacaMarketDataAPI, AlpacaNewsArticleSchema, AlpacaNewsResponseSchema, AlpacaOrderSchema, AlpacaOrdersArraySchema, AlpacaPortfolioHistoryResponseSchema, AlpacaPositionSchema, AlpacaPositionsArraySchema, AlpacaQuoteSchema, AlpacaTradeSchema, AlpacaTradingAPI, AlphaVantageError, AlphaVantageQuoteResponseSchema, AssetAllocationEngine, AuthenticationError, AutonomyMode, BTC_PAIRS, BarError, CircuitOpenError, CryptoDataError, CryptoOrderError, DEFAULT_CACHE_OPTIONS, DEFAULT_RISK_FREE_RATE, DEFAULT_TIMEOUTS, DEFAULT_TRADING_POLICY, DataFormatError, DecisionMemoryOutcome, DecisionOutcome, DecisionRecordStatus, HttpClientError, HttpServerError, KEEP_ALIVE_DEFAULTS, LlmProvider, MARKET_DATA_API, MassiveAggregatesResponseSchema, MassiveApiError, MassiveDailyOpenCloseSchema, MassiveErrorResponseSchema, MassiveGroupedDailyResponseSchema, MassiveLastTradeResponseSchema, MassiveTickerDetailsResponseSchema, MassiveTickerInfoSchema, MassiveTradeSchema as MassiveTradeZodSchema, MassiveTradesResponseSchema, NetworkError, NewsError, OptionStrategyError, OptionsDataError, OverlaySeverity, OverlayStatus, OverlayType, QuoteError, RISK_FREE_RATE_TTL_MS, RateLimitError, RawMassivePriceDataSchema, StampedeProtectedCache, TRADING_API, TimeoutError, TokenBucketRateLimiter, TradeError, TrailingStopValidationError, USDC_PAIRS, USDT_PAIRS, USD_PAIRS, UnsupportedBrokerError, ValidationError, ValidationResponseError, WEBSOCKET_STREAMS, WebSocketError, account, adaptic, adptc, alpaca, analyzeBars, approximateImpliedVolatility, atrNs as atr, bracketOrders, buildOCCSymbol, buildOptionSymbol, buyCryptoNotional, buyToClose, buyToOpen, buyWithStopLoss, buyWithTrailingStop, calculateMoneyness, calculateOrderValue, calculatePeriodPerformance, calculatePutCallRatio, calculateTotalFilledValue, cancelAllCryptoOrders, cancelOCOOrder, cancelOTOOrder, cancelTrailingStop, cancelTrailingStopsForSymbol, checkTradingEligibility, clearClientCache, clock, closeAllOptionPositions, closeOptionPosition, createAlpacaClient, createAlpacaMarketDataAPI, createAlpacaTradingAPI, createBracketOrder, createBrokerClient, createButterflySpread, createClientFromEnv, createCoveredCall, createCryptoLimitOrder, createCryptoMarketOrder, createCryptoOrder, createCryptoStopLimitOrder, createCryptoStopOrder, createExecutorFromTradingAPI, createIronCondor$1 as createIronCondor, createIronCondor as createIronCondorAdvanced, createMultiLegOptionOrder, createOCOOrder, createOTOOrder, createOptionOrder, createPortfolioTrailingStops, createProtectiveBracket, createStampedeProtectedCache, createStraddle$1 as createStraddle, createStraddle as createStraddleAdvanced, createStrangle$1 as createStrangle, createStrangle as createStrangleAdvanced, createStreamManager, createTimeoutSignal, createTrailingStop, createVerticalSpread$1 as createVerticalSpread, createVerticalSpread as createVerticalSpreadAdvanced, entryWithPercentStopLoss, exerciseOption, extractGreeks, filterByExpiration, filterByStrike, filterByType, filterOrdersByDateRange, findATMOptions, findATMStrikes, findNearestExpiration, findOptionsByDelta, formatOrderForLog, formatOrderSummary, generateOptimalAllocation, getAccountConfiguration, getAccountDetails, getAccountSummary, getAgentPoolStatus, getAllOrders, getAlpacaCalendar, getAlpacaClock, getAverageDailyVolume, getBars, getBuyingPower, getCachedRiskFreeRateSync, getCachedRiskFreeRateSyncWithProvenance, getCrypto24HourChange, getCryptoBars, getCryptoDailyPrices, getCryptoPairsByQuote, getCryptoPrice, getCryptoSnapshots, getCryptoSpread, getCryptoStreamUrl, getCryptoTrades, getCurrentPrice, getCurrentPrices, getDailyPrices, getDailyReturns, getDaysToExpiration, getDefaultRiskProfile, getEquityCurve, getExpirationDates, getFilledOrders, getGroupedOptionChain, getHistoricalOptionsBars, getHistoricalTrades, getIntradayPrices, getLatestBars, getLatestCryptoQuotes, getLatestCryptoTrades, getLatestNews, getLatestOptionsQuotes, getLatestOptionsTrades, getLatestQuote, getLatestQuotes, getLatestTrade, getLatestTrades, getLogger, getMarginInfo, getNews, getNewsForSymbols, getOCOOrderStatus, getOTOOrderStatus, getOpenCryptoOrders, getOpenOrders$1 as getOpenOrdersQuery, getOpenTrailingStops, getOptionChain, getOptionContract, getOptionContracts, getOptionSpread, getOptionsChain, getOptionsSnapshots, getOptionsStreamUrl, getOptionsTradingLevel, getOrderHistory, getOrdersBySymbol, getPDTStatus, getPopularCryptoPairs, getPortfolioHistory, getPreviousClose, getPriceRange, getRiskFreeRate, getRiskFreeRateWithProvenance, getSpread, getSpreads, getStockStreamUrl, getStrikePrices, getSupportedCryptoPairs, getSymbolSentiment, getTimeout, getTradeVolume, getTradingApiUrl, getTradingWebSocketUrl, getTrailingStopHWM, groupOrdersByStatus, groupOrdersBySymbol, hasActiveTrailingStop, hasGoodLiquidity as hasOptionLiquidity, hasGoodLiquidity$1 as hasStockLiquidity, hasSufficientVolume, httpAgent, httpsAgent, isAlpacaBrokerCredentials, isContractTradable, isCryptoPair, isExpiringWithin, isMarginAccount, isOptionOrderCancelable, isOptionOrderTerminal, isOrderFillable, isOrderFilled, isOrderOpen, isOrderTerminal$1 as isOrderTerminalStatus, isSupportedCryptoPair, isTransientNetworkError, index$1 as legacyApi, limitBuyWithTakeProfit, ocoOrders, orderUtils, otoOrders, paginate, paginateAll, parseOCCSymbol, protectLongPosition, protectShortPosition, rateLimiters, resetLogger, resetRiskFreeRateCache, riskNs as risk, rollOptionPosition, roundPriceForAlpaca$3 as roundPriceForAlpaca, roundPriceForAlpacaNumber, safeValidateResponse, searchNews, sellAllCrypto, sellCryptoNotional, sellToClose, sellToOpen, setLogger, setRiskFreeRate, shortWithStopLoss, sortOrdersByDate, strategyNs as strategy, index as tradingPolicy, trailingStops, updateAccountConfiguration, updateTrailingStop, validateAlpacaCredentials, validateAlphaVantageApiKey, validateMassiveApiKey$1 as validateMassiveApiKey, validateMultiLegOrder, validateResponse, verifyFetchKeepAlive, volatilityNs as volatility, waitForOrderFill, withRetry, withTimeout };
 //# sourceMappingURL=index.mjs.map