@adaptic/utils 0.0.1009 → 0.0.1011

package/dist/index.mjs

@@ -2175,6 +2175,247 @@ function validateAlphaVantageApiKey(apiKey) {
     }
 }
 
+/**
+ * Structured error type hierarchy for all API integrations
+ *
+ * This module provides a comprehensive error handling system for external API integrations,
+ * including Alpaca, Massive, and AlphaVantage services.
+ */
+/**
+ * Base error class for all @adaptic/utils errors
+ * Extends Error with additional context about service, error code, and retry capability
+ */
+class AdapticUtilsError extends Error {
+    code;
+    service;
+    isRetryable;
+    cause;
+    name;
+    constructor(message, code, service, isRetryable = false, cause) {
+        super(message);
+        this.code = code;
+        this.service = service;
+        this.isRetryable = isRetryable;
+        this.cause = cause;
+        this.name = this.constructor.name;
+        // Maintains proper stack trace for where error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Alpaca API specific errors
+ * Handles all errors from Alpaca trading and market data APIs
+ */
+class AlpacaApiError extends AdapticUtilsError {
+    statusCode;
+    constructor(message, code, statusCode, cause) {
+        // Rate limit (429) and server errors (5xx) are retryable
+        const isRetryable = statusCode === 429 || (statusCode !== undefined && statusCode >= 500);
+        super(message, code, "alpaca", isRetryable, cause);
+        this.statusCode = statusCode;
+    }
+}
+/**
+ * Massive.com API specific errors
+ * Handles all errors from Massive market data API
+ */
+class MassiveApiError extends AdapticUtilsError {
+    statusCode;
+    constructor(message, code, statusCode, cause) {
+        // Rate limit (429) and server errors (5xx) are retryable
+        const isRetryable = statusCode === 429 || (statusCode !== undefined && statusCode >= 500);
+        super(message, code, "massive", isRetryable, cause);
+        this.statusCode = statusCode;
+    }
+}
+/**
+ * AlphaVantage API specific errors
+ * Handles all errors from AlphaVantage financial data API
+ */
+class AlphaVantageError extends AdapticUtilsError {
+    statusCode;
+    constructor(message, code, statusCode, cause) {
+        // Rate limit (429) and server errors (5xx) are retryable
+        const isRetryable = statusCode === 429 || (statusCode !== undefined && statusCode >= 500);
+        super(message, code, "alphavantage", isRetryable, cause);
+        this.statusCode = statusCode;
+    }
+}
+/**
+ * Network timeout errors
+ * Used when API requests exceed configured timeout limits
+ * Always retryable as timeouts are often transient
+ */
+class TimeoutError extends AdapticUtilsError {
+    service;
+    timeoutMs;
+    constructor(message, service, timeoutMs, cause) {
+        super(message, "TIMEOUT", service, true, // Timeouts are always retryable
+        cause);
+        this.service = service;
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * Input validation errors
+ * Used when function inputs fail validation checks
+ * Never retryable as the inputs need to be corrected
+ */
+class ValidationError extends AdapticUtilsError {
+    service;
+    invalidField;
+    constructor(message, service, invalidField, cause) {
+        super(message, "VALIDATION_ERROR", service, false, // Validation errors are never retryable
+        cause);
+        this.service = service;
+        this.invalidField = invalidField;
+    }
+}
+/**
+ * Authentication and authorization errors
+ * Used when API credentials are invalid, expired, or lack permissions
+ * Never retryable as credentials need to be updated
+ */
+class AuthenticationError extends AdapticUtilsError {
+    service;
+    statusCode;
+    constructor(message, service, statusCode, cause) {
+        super(message, "AUTH_ERROR", service, false, // Auth errors are never retryable
+        cause);
+        this.service = service;
+        this.statusCode = statusCode;
+    }
+}
+/**
+ * HTTP client errors (4xx)
+ * Used for client-side errors that are not authentication or validation related
+ * Generally not retryable unless specific status codes indicate otherwise
+ */
+class HttpClientError extends AdapticUtilsError {
+    service;
+    statusCode;
+    constructor(message, service, statusCode, cause) {
+        super(message, "CLIENT_ERROR", service, false, // Client errors are generally not retryable
+        cause);
+        this.service = service;
+        this.statusCode = statusCode;
+    }
+}
+/**
+ * HTTP server errors (5xx)
+ * Used for server-side errors from external APIs
+ * Always retryable as server issues are often transient
+ */
+class HttpServerError extends AdapticUtilsError {
+    service;
+    statusCode;
+    constructor(message, service, statusCode, cause) {
+        super(message, "SERVER_ERROR", service, true, // Server errors are always retryable
+        cause);
+        this.service = service;
+        this.statusCode = statusCode;
+    }
+}
+/**
+ * Rate limit errors (429)
+ * Used when API rate limits are exceeded
+ * Always retryable, often with retry-after header information
+ */
+class RateLimitError extends AdapticUtilsError {
+    service;
+    retryAfterMs;
+    constructor(message, service, retryAfterMs, cause) {
+        super(message, "RATE_LIMIT", service, true, // Rate limit errors are always retryable
+        cause);
+        this.service = service;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/**
+ * WebSocket connection errors
+ * Used for WebSocket-specific connection and communication failures
+ * Retryability depends on the specific error condition
+ */
+class WebSocketError extends AdapticUtilsError {
+    service;
+    constructor(message, service, isRetryable = true, cause) {
+        super(message, "WEBSOCKET_ERROR", service, isRetryable, cause);
+        this.service = service;
+    }
+}
+/**
+ * Network errors (connection failures, DNS issues, etc.)
+ * Used for low-level network failures
+ * Always retryable as network issues are often transient
+ */
+class NetworkError extends AdapticUtilsError {
+    service;
+    constructor(message, service, cause) {
+        super(message, "NETWORK_ERROR", service, true, // Network errors are always retryable
+        cause);
+        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
+ * Not retryable as the data format issue needs investigation
+ */
+class DataFormatError extends AdapticUtilsError {
+    service;
+    constructor(message, service, cause) {
+        super(message, "DATA_FORMAT_ERROR", service, false, // Data format errors are not retryable
+        cause);
+        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;
+    }
+}
+
 const DEFAULT_RETRY_CONFIG = {
     maxRetries: 3,
     baseDelayMs: 1000,
@@ -2349,128 +2590,224 @@ function isClientDeadlineExpiry(error) {
     return false;
 }
 /**
- * Analyzes an error and determines if it's retryable.
- * @param error - The error to analyze
- * @param response - Optional Response object for HTTP errors
- * @param config - Retry configuration
- * @returns Structured error details
+ * HTTP statuses the classifier reasons about, named rather than inlined.
+ */
+const HTTP_STATUS = {
+    /** Too Many Requests — retryable, honouring `Retry-After`. */
+    RATE_LIMIT: 429,
+    /** Unauthorized — never retryable, the credentials are wrong. */
+    UNAUTHORIZED: 401,
+    /** Forbidden — never retryable, the permissions are wrong. */
+    FORBIDDEN: 403,
+    /** Lowest status in the client-error band. */
+    CLIENT_ERROR_MIN: 400,
+    /** Lowest status in the server-error band. */
+    SERVER_ERROR_MIN: 500,
+    /** First status above the server-error band. */
+    SERVER_ERROR_MAX_EXCLUSIVE: 600,
+};
+/** `Retry-After` is expressed in seconds; delays are handled in milliseconds. */
+const MILLISECONDS_PER_SECOND = 1000;
+/**
+ * Narrows an unknown value to an index-signature record so its properties can
+ * be probed without an `any` cast.
+ * @param value - The value to test.
+ * @returns true when the value is a non-null object.
  */
-function analyzeError(error, response, config) {
-    // Handle Response objects with error status codes
-    if (response && !response.ok) {
-        const status = response.status;
-        // Rate limit errors - always retryable
-        if (status === 429) {
-            const retryAfterHeader = response.headers.get("Retry-After");
-            const retryAfter = retryAfterHeader
-                ? parseInt(retryAfterHeader, 10) * 1000
-                : undefined;
-            return {
-                type: "RATE_LIMIT",
-                reason: "Rate limit exceeded",
-                status,
-                retryAfter,
-                isRetryable: true,
-            };
-        }
-        // Authentication errors - never retry
-        if (status === 401 || status === 403) {
-            return {
-                type: "AUTH_ERROR",
-                reason: status === 401
-                    ? "Authentication failed - invalid credentials"
-                    : "Access forbidden - insufficient permissions",
-                status,
-                isRetryable: false,
-            };
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Reads a `Retry-After` header (seconds) from either a `Headers` instance or a
+ * plain header map, and converts it to milliseconds.
+ * @param headers - The headers carrier from a Response or an HTTP client error.
+ * @returns The delay in milliseconds, or undefined when absent/unparseable.
+ */
+function readRetryAfterMs(headers) {
+    let raw;
+    if (headers instanceof Headers) {
+        raw = headers.get("Retry-After");
+    }
+    else if (isRecord(headers)) {
+        raw = headers["retry-after"] ?? headers["Retry-After"];
+    }
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        return raw * MILLISECONDS_PER_SECOND;
+    }
+    if (typeof raw === "string") {
+        const seconds = Number.parseInt(raw, 10);
+        if (Number.isFinite(seconds)) {
+            return seconds * MILLISECONDS_PER_SECOND;
         }
-        // Server errors - check if in retryable list
-        if (status >= 500 && status < 600) {
-            return {
-                type: "SERVER_ERROR",
-                reason: `Server error (${status})`,
-                status,
-                isRetryable: config.retryableStatusCodes.includes(status),
-            };
+    }
+    return undefined;
+}
+/**
+ * Reads a numeric HTTP status from an unknown property value.
+ * @param value - The candidate status value.
+ * @returns The status when it is a finite number, otherwise null.
+ */
+function asStatus(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Extracts the HTTP status from a **typed** carrier: a `Response`, a typed
+ * {@link AdapticUtilsError}, an HTTP-client error exposing `response.status`
+ * (axios/the Alpaca SDK), or an error exposing a numeric `status`/`statusCode`.
+ *
+ * @param error - The thrown value.
+ * @returns The typed failure, or null when the value carries no status.
+ */
+function extractTypedHttpFailure(error) {
+    if (error instanceof Response) {
+        return {
+            status: error.status,
+            retryAfterMs: readRetryAfterMs(error.headers),
+        };
+    }
+    if (error instanceof AdapticUtilsError) {
+        const status = asStatus(error.statusCode);
+        if (status !== null) {
+            return { status };
         }
-        // Other client errors - never retry
-        if (status >= 400 && status < 500) {
-            return {
-                type: "CLIENT_ERROR",
-                reason: `Client error (${status})`,
-                status,
-                isRetryable: false,
-            };
+        return null;
+    }
+    if (!isRecord(error)) {
+        return null;
+    }
+    const nested = error.response;
+    if (nested instanceof Response) {
+        return {
+            status: nested.status,
+            retryAfterMs: readRetryAfterMs(nested.headers),
+        };
+    }
+    if (isRecord(nested)) {
+        const status = asStatus(nested.status);
+        if (status !== null) {
+            return { status, retryAfterMs: readRetryAfterMs(nested.headers) };
         }
     }
-    // Handle network errors (TypeError from fetch API)
-    if (error instanceof TypeError && error.message.includes("fetch")) {
+    const direct = asStatus(error.status) ?? asStatus(error.statusCode);
+    return direct === null ? null : { status: direct };
+}
+/**
+ * Maps an HTTP status to the typed retry verdict. This is the single place
+ * retryability is decided for status-bearing failures.
+ *
+ * @param failure - The status (and any upstream-mandated delay).
+ * @param config - Effective retry configuration.
+ * @returns The typed classification.
+ */
+function classifyByStatus(failure, config) {
+    const { status } = failure;
+    if (status === HTTP_STATUS.RATE_LIMIT) {
         return {
-            type: "NETWORK_ERROR",
-            reason: "Network connectivity issue",
+            type: "RATE_LIMIT",
+            reason: "Rate limit exceeded",
+            status,
+            retryAfter: failure.retryAfterMs,
+            isRetryable: true,
+        };
+    }
+    if (status === HTTP_STATUS.UNAUTHORIZED ||
+        status === HTTP_STATUS.FORBIDDEN) {
+        return {
+            type: "AUTH_ERROR",
+            reason: status === HTTP_STATUS.UNAUTHORIZED
+                ? "Authentication failed - invalid credentials"
+                : "Access forbidden - insufficient permissions",
+            status,
+            isRetryable: false,
+        };
+    }
+    if (status >= HTTP_STATUS.SERVER_ERROR_MIN &&
+        status < HTTP_STATUS.SERVER_ERROR_MAX_EXCLUSIVE) {
+        return {
+            type: "SERVER_ERROR",
+            reason: `Server error (${status})`,
+            status,
+            retryAfter: failure.retryAfterMs,
+            isRetryable: config.retryableStatusCodes.includes(status),
+        };
+    }
+    if (status >= HTTP_STATUS.CLIENT_ERROR_MIN &&
+        status < HTTP_STATUS.SERVER_ERROR_MIN) {
+        return {
+            type: "CLIENT_ERROR",
+            reason: `Client error (${status})`,
+            status,
+            isRetryable: false,
+        };
+    }
+    return {
+        type: "UNKNOWN",
+        reason: `Unexpected HTTP status (${status})`,
+        status,
+        isRetryable: false,
+    };
+}
+/**
+ * Classifies a failure into the typed {@link RetryErrorDetails} taxonomy.
+ *
+ * **An HTTP status is only ever read from a typed carrier.** There is no path
+ * from the characters of an error message to a status, and therefore none to a
+ * retry decision derived from a status (F-0035). A throw site that wants its
+ * status honoured must attach it: throw the `Response`, set `response.status`
+ * (axios / the Alpaca SDK do this), set a numeric `status` / `statusCode`, or
+ * raise an {@link AdapticUtilsError}. A plain `Error` whose text mentions
+ * "429", "503" or "CLIENT_ERROR: 422" is `UNKNOWN` and is **not** retried.
+ *
+ * Precedence, strongest evidence first:
+ *
+ * 1. an explicit `Response`, or a thrown `Response`;
+ * 2. a **typed** carrier — {@link AdapticUtilsError} (status, else its declared
+ *    `isRetryable`), `error.response.status` (axios / Alpaca SDK), or a numeric
+ *    `error.status` / `error.statusCode`;
+ * 3. transient network conditions — {@link isTransientNetworkError}, which
+ *    reads `error.code` / `error.name` / the `cause` chain. This decides
+ *    *transience*, never a status, so it can never turn a broker rejection into
+ *    a 5xx; a rejection that carries a typed status is already resolved above;
+ * 4. otherwise `UNKNOWN`, which is **not** retryable.
+ *
+ * @param error - The thrown value.
+ * @param response - Optional Response already in hand for this failure.
+ * @param config - Optional retry-configuration overrides.
+ * @returns The typed classification.
+ */
+function classifyRetryError(error, response = null, config = {}) {
+    const fullConfig = { ...DEFAULT_RETRY_CONFIG, ...config };
+    if (response && !response.ok) {
+        return classifyByStatus({
+            status: response.status,
+            retryAfterMs: readRetryAfterMs(response.headers),
+        }, fullConfig);
+    }
+    const typedFailure = extractTypedHttpFailure(error);
+    if (typedFailure) {
+        return classifyByStatus(typedFailure, fullConfig);
+    }
+    // A typed error class that declares its own retryability but carries no
+    // status (timeouts, validation failures, network wrappers) is authoritative.
+    if (error instanceof AdapticUtilsError) {
+        return {
+            type: error.isRetryable ? "NETWORK_ERROR" : "CLIENT_ERROR",
+            reason: error.message,
             status: null,
-            isRetryable: config.retryOnNetworkError,
+            isRetryable: error.isRetryable && fullConfig.retryOnNetworkError,
         };
     }
-    // Handle transient network conditions: AbortError, TimeoutError,
-    // Node/undici error codes (ETIMEDOUT, ECONNRESET, UND_ERR_*), and
-    // wrapped failures exposed via error.cause. This catches the broad class
-    // of infrastructure flakes that the TypeError-only check above misses.
-    if (isTransientNetworkError(error)) {
-        const reason = error instanceof Error ? error.message : "Transient network error";
+    // Transient network conditions: fetch TypeErrors, AbortError/TimeoutError,
+    // Node/undici error codes, and failures wrapped via `error.cause`.
+    if ((error instanceof TypeError && error.message.includes("fetch")) ||
+        isTransientNetworkError(error)) {
         return {
             type: "NETWORK_ERROR",
-            reason,
+            reason: error instanceof Error ? error.message : "Transient network error",
             status: null,
-            isRetryable: config.retryOnNetworkError,
+            isRetryable: fullConfig.retryOnNetworkError,
         };
     }
-    // Handle error objects with messages
-    if (error instanceof Error) {
-        // Parse error messages that might contain status information
-        if (error.message.includes("429") || error.message.includes("RATE_LIMIT")) {
-            const match = error.message.match(/RATE_LIMIT: 429:(\d+)/);
-            const retryAfter = match ? parseInt(match[1], 10) : undefined;
-            return {
-                type: "RATE_LIMIT",
-                reason: "Rate limit exceeded",
-                status: 429,
-                retryAfter,
-                isRetryable: true,
-            };
-        }
-        if (error.message.includes("401") ||
-            error.message.includes("403") ||
-            error.message.includes("AUTH_ERROR")) {
-            const status = error.message.includes("401") ? 401 : 403;
-            return {
-                type: "AUTH_ERROR",
-                reason: `Authentication error (${status})`,
-                status,
-                isRetryable: false,
-            };
-        }
-        if (error.message.includes("SERVER_ERROR") ||
-            error.message.match(/50[0-9]/)) {
-            const statusMatch = error.message.match(/50[0-9]/);
-            const status = statusMatch ? parseInt(statusMatch[0], 10) : 500;
-            return {
-                type: "SERVER_ERROR",
-                reason: `Server error (${status})`,
-                status,
-                isRetryable: config.retryableStatusCodes.includes(status),
-            };
-        }
-        if (error.message.includes("network") ||
-            error.message.includes("NETWORK_ERROR")) {
-            return {
-                type: "NETWORK_ERROR",
-                reason: error.message,
-                status: null,
-                isRetryable: config.retryOnNetworkError,
-            };
-        }
-    }
     // Unknown error - not retryable by default for safety
     return {
         type: "UNKNOWN",
@@ -2480,13 +2817,16 @@ function analyzeError(error, response, config) {
     };
 }
 /**
- * Calculates the delay before the next retry attempt using exponential backoff with jitter.
+ * Calculates the delay before the next retry attempt using exponential backoff
+ * with jitter, capped at `maxDelay`. Exported so the backoff contract (growth,
+ * cap, jitter) is directly testable rather than only observable through timers.
+ *
  * @param attempt - Current attempt number (1-indexed)
  * @param baseDelay - Base delay in milliseconds
- * @param maxDelay - Maximum delay in milliseconds
+ * @param maxDelay - Maximum delay in milliseconds (before jitter)
  * @returns Delay in milliseconds
  */
-function calculateBackoff(attempt, baseDelay, maxDelay) {
+function calculateRetryBackoff(attempt, baseDelay, maxDelay) {
     // Exponential backoff: baseDelay * 2^(attempt-1)
     const exponentialDelay = baseDelay * Math.pow(2, attempt - 1);
     // Cap at maxDelay
@@ -2578,7 +2918,7 @@ async function withRetry(fn, config = {}, label = "unknown") {
             }
             // Analyze the error to determine if we should retry
             const response = error instanceof Response ? error : null;
-            const errorDetails = analyzeError(error, response, fullConfig);
+            const errorDetails = classifyRetryError(error, response, fullConfig);
             // If error is not retryable, fail immediately
             if (!errorDetails.isRetryable) {
                 getLogger().error(`[${label}] Non-retryable error (${errorDetails.type})`, {
@@ -2596,11 +2936,11 @@ async function withRetry(fn, config = {}, label = "unknown") {
             }
             else if (errorDetails.type === "RATE_LIMIT") {
                 // For rate limits without Retry-After, use a longer minimum delay
-                delayMs = Math.max(calculateBackoff(attempt, fullConfig.baseDelayMs, fullConfig.maxDelayMs), 5000);
+                delayMs = Math.max(calculateRetryBackoff(attempt, fullConfig.baseDelayMs, fullConfig.maxDelayMs), 5000);
             }
             else {
                 // Standard exponential backoff with jitter
-                delayMs = calculateBackoff(attempt, fullConfig.baseDelayMs, fullConfig.maxDelayMs);
+                delayMs = calculateRetryBackoff(attempt, fullConfig.baseDelayMs, fullConfig.maxDelayMs);
             }
             // Log the retry attempt
             getLogger().warn(`[${label}] Attempt ${attempt}/${fullConfig.maxRetries} failed: ${errorDetails.reason}. Retrying in ${delayMs}ms...`, {
@@ -2662,247 +3002,6 @@ const API_RETRY_CONFIGS = {
     },
 };
 
-/**
- * Structured error type hierarchy for all API integrations
- *
- * This module provides a comprehensive error handling system for external API integrations,
- * including Alpaca, Massive, and AlphaVantage services.
- */
-/**
- * Base error class for all @adaptic/utils errors
- * Extends Error with additional context about service, error code, and retry capability
- */
-class AdapticUtilsError extends Error {
-    code;
-    service;
-    isRetryable;
-    cause;
-    name;
-    constructor(message, code, service, isRetryable = false, cause) {
-        super(message);
-        this.code = code;
-        this.service = service;
-        this.isRetryable = isRetryable;
-        this.cause = cause;
-        this.name = this.constructor.name;
-        // Maintains proper stack trace for where error was thrown (only available on V8)
-        if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, this.constructor);
-        }
-    }
-}
-/**
- * Alpaca API specific errors
- * Handles all errors from Alpaca trading and market data APIs
- */
-class AlpacaApiError extends AdapticUtilsError {
-    statusCode;
-    constructor(message, code, statusCode, cause) {
-        // Rate limit (429) and server errors (5xx) are retryable
-        const isRetryable = statusCode === 429 || (statusCode !== undefined && statusCode >= 500);
-        super(message, code, "alpaca", isRetryable, cause);
-        this.statusCode = statusCode;
-    }
-}
-/**
- * Massive.com API specific errors
- * Handles all errors from Massive market data API
- */
-class MassiveApiError extends AdapticUtilsError {
-    statusCode;
-    constructor(message, code, statusCode, cause) {
-        // Rate limit (429) and server errors (5xx) are retryable
-        const isRetryable = statusCode === 429 || (statusCode !== undefined && statusCode >= 500);
-        super(message, code, "massive", isRetryable, cause);
-        this.statusCode = statusCode;
-    }
-}
-/**
- * AlphaVantage API specific errors
- * Handles all errors from AlphaVantage financial data API
- */
-class AlphaVantageError extends AdapticUtilsError {
-    statusCode;
-    constructor(message, code, statusCode, cause) {
-        // Rate limit (429) and server errors (5xx) are retryable
-        const isRetryable = statusCode === 429 || (statusCode !== undefined && statusCode >= 500);
-        super(message, code, "alphavantage", isRetryable, cause);
-        this.statusCode = statusCode;
-    }
-}
-/**
- * Network timeout errors
- * Used when API requests exceed configured timeout limits
- * Always retryable as timeouts are often transient
- */
-class TimeoutError extends AdapticUtilsError {
-    service;
-    timeoutMs;
-    constructor(message, service, timeoutMs, cause) {
-        super(message, "TIMEOUT", service, true, // Timeouts are always retryable
-        cause);
-        this.service = service;
-        this.timeoutMs = timeoutMs;
-    }
-}
-/**
- * Input validation errors
- * Used when function inputs fail validation checks
- * Never retryable as the inputs need to be corrected
- */
-class ValidationError extends AdapticUtilsError {
-    service;
-    invalidField;
-    constructor(message, service, invalidField, cause) {
-        super(message, "VALIDATION_ERROR", service, false, // Validation errors are never retryable
-        cause);
-        this.service = service;
-        this.invalidField = invalidField;
-    }
-}
-/**
- * Authentication and authorization errors
- * Used when API credentials are invalid, expired, or lack permissions
- * Never retryable as credentials need to be updated
- */
-class AuthenticationError extends AdapticUtilsError {
-    service;
-    statusCode;
-    constructor(message, service, statusCode, cause) {
-        super(message, "AUTH_ERROR", service, false, // Auth errors are never retryable
-        cause);
-        this.service = service;
-        this.statusCode = statusCode;
-    }
-}
-/**
- * HTTP client errors (4xx)
- * Used for client-side errors that are not authentication or validation related
- * Generally not retryable unless specific status codes indicate otherwise
- */
-class HttpClientError extends AdapticUtilsError {
-    service;
-    statusCode;
-    constructor(message, service, statusCode, cause) {
-        super(message, "CLIENT_ERROR", service, false, // Client errors are generally not retryable
-        cause);
-        this.service = service;
-        this.statusCode = statusCode;
-    }
-}
-/**
- * HTTP server errors (5xx)
- * Used for server-side errors from external APIs
- * Always retryable as server issues are often transient
- */
-class HttpServerError extends AdapticUtilsError {
-    service;
-    statusCode;
-    constructor(message, service, statusCode, cause) {
-        super(message, "SERVER_ERROR", service, true, // Server errors are always retryable
-        cause);
-        this.service = service;
-        this.statusCode = statusCode;
-    }
-}
-/**
- * Rate limit errors (429)
- * Used when API rate limits are exceeded
- * Always retryable, often with retry-after header information
- */
-class RateLimitError extends AdapticUtilsError {
-    service;
-    retryAfterMs;
-    constructor(message, service, retryAfterMs, cause) {
-        super(message, "RATE_LIMIT", service, true, // Rate limit errors are always retryable
-        cause);
-        this.service = service;
-        this.retryAfterMs = retryAfterMs;
-    }
-}
-/**
- * WebSocket connection errors
- * Used for WebSocket-specific connection and communication failures
- * Retryability depends on the specific error condition
- */
-class WebSocketError extends AdapticUtilsError {
-    service;
-    constructor(message, service, isRetryable = true, cause) {
-        super(message, "WEBSOCKET_ERROR", service, isRetryable, cause);
-        this.service = service;
-    }
-}
-/**
- * Network errors (connection failures, DNS issues, etc.)
- * Used for low-level network failures
- * Always retryable as network issues are often transient
- */
-class NetworkError extends AdapticUtilsError {
-    service;
-    constructor(message, service, cause) {
-        super(message, "NETWORK_ERROR", service, true, // Network errors are always retryable
-        cause);
-        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
- * Not retryable as the data format issue needs investigation
- */
-class DataFormatError extends AdapticUtilsError {
-    service;
-    constructor(message, service, cause) {
-        super(message, "DATA_FORMAT_ERROR", service, false, // Data format errors are not retryable
-        cause);
-        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
  *
@@ -4642,9 +4741,9 @@ const CLIENT_ORDER_ID_WINDOW_MS = 300_000;
  * 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;
+const DUPLICATE_CLIENT_ORDER_ID_PATTERN$1 = /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;
+const DUPLICATE_CLIENT_ORDER_ID_STATUS$1 = 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
@@ -4652,7 +4751,7 @@ const DUPLICATE_CLIENT_ORDER_ID_STATUS = 422;
  * 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([
+const TERMINAL_DEAD_ORDER_STATUSES$1 = new Set([
     "canceled",
     "expired",
     "rejected",
@@ -4786,8 +4885,8 @@ class AlpacaTradingAPI {
     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));
+        return (error.message.includes(`(${DUPLICATE_CLIENT_ORDER_ID_STATUS$1})`) &&
+            DUPLICATE_CLIENT_ORDER_ID_PATTERN$1.test(error.message));
     }
     /**
      * Look up an order by its `client_order_id` (Alpaca
@@ -4864,7 +4963,7 @@ class AlpacaTradingAPI {
                     : 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)) {
+            if (existing && !TERMINAL_DEAD_ORDER_STATUSES$1.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,
@@ -57850,6 +57949,10 @@ var optionOrders = /*#__PURE__*/Object.freeze({
     validateMultiLegOrder: validateMultiLegOrder
 });
 
+/**
+ * Alpaca Order Management Module
+ * Provides functions for creating, managing, and canceling orders using the official SDK
+ */
 const LOG_SOURCE$4 = "AlpacaOrders";
 /**
  * Internal logging helper with consistent source
@@ -57857,23 +57960,295 @@ const LOG_SOURCE$4 = "AlpacaOrders";
 const log$6 = (message, options = { type: "info" }) => {
     log$m(message, { ...options, source: LOG_SOURCE$4 });
 };
+/**
+ * Maximum length Alpaca accepts for a `client_order_id`.
+ */
+const MAX_CLIENT_ORDER_ID_LENGTH = 128;
+/**
+ * Characters Alpaca does **not** accept inside a `client_order_id`. Anything
+ * matching is rewritten before submission.
+ */
+const UNSAFE_CLIENT_ORDER_ID_CHARS = /[^A-Za-z0-9._:-]/g;
+/**
+ * Hex characters of the SHA-256 digest appended when an idempotency key had to
+ * be rewritten (unsafe characters or over-length). 16 hex chars = 64 bits,
+ * which keeps two keys that sanitise to the same head distinguishable.
+ */
+const CLIENT_ORDER_ID_DIGEST_LENGTH = 16;
+/** Separator between the sanitised head and the digest tag. */
+const CLIENT_ORDER_ID_DIGEST_SEPARATOR = "-";
+/** HTTP status Alpaca uses for a duplicate `client_order_id`. */
+const DUPLICATE_CLIENT_ORDER_ID_STATUS = 422;
+/** HTTP status Alpaca returns when no order carries the given id. */
+const ORDER_NOT_FOUND_STATUS = 404;
+/**
+ * Matches Alpaca's duplicate-idempotency-key rejection text. Alpaca has used
+ * both "client_order_id must be unique" and "client order id must be unique"
+ * across API revisions, so the separator is matched loosely.
+ */
+const DUPLICATE_CLIENT_ORDER_ID_PATTERN = /client[\s_-]?order[\s_-]?id must be unique/i;
+/**
+ * Order statuses in which a previously-submitted order can never execute. A
+ * duplicate colliding with an order in one of these states is NOT an idempotent
+ * success — the caller asked for an order that cannot exist under that id, so
+ * the typed duplicate error is raised instead of a silent resubmission.
+ */
+const TERMINAL_DEAD_ORDER_STATUSES = new Set([
+    "canceled",
+    "expired",
+    "rejected",
+    "replaced",
+    "done_for_day",
+]);
+/**
+ * Prefix marking a `client_order_id` this module minted because the caller
+ * supplied no identity of its own. It makes the un-migrated call sites
+ * greppable broker-side and in fill telemetry, and it can never collide with
+ * the engine's `trade.id` convention.
+ */
+const GENERATED_IDEMPOTENCY_KEY_PREFIX = "adptc-auto";
+/**
+ * Mints a per-submission idempotency key for a caller that supplied none.
+ *
+ * The key is a fresh random UUID, so it is unique to **this call** and is held
+ * constant for the whole of it — which is precisely what makes the transport
+ * retry inside {@link AlpacaClient.executeWithRateLimit} idempotent: a POST
+ * that already landed is refused broker-side on the re-send instead of filling
+ * twice (F-0035). It deliberately carries no other meaning. It is **not**
+ * derived from the order's contents or from the clock, because either would
+ * claim a de-duplication across separate calls that a generated key cannot
+ * honestly provide: content-derived keys would silently swallow a legitimate
+ * repeat order, and clock-derived keys would de-duplicate or not depending on
+ * which side of a bucket boundary the second call fell.
+ *
+ * @returns A broker-safe, unique key for a single submission.
+ */
+function generateSubmissionIdempotencyKey() {
+    return `${GENERATED_IDEMPOTENCY_KEY_PREFIX}-${randomUUID()}`;
+}
+/**
+ * Validates a caller-supplied idempotency key.
+ * @param idempotencyKey - The key to validate.
+ * @returns The trimmed key.
+ * @throws Error when the key is empty or whitespace-only.
+ */
+function requireIdempotencyKey(idempotencyKey) {
+    const key = idempotencyKey.trim();
+    if (key.length === 0) {
+        throw new Error("Order submission requires a non-empty idempotency key identifying the logical order");
+    }
+    return key;
+}
+/**
+ * Derives the broker-side `client_order_id` from a caller-supplied idempotency
+ * key. Deterministic: the same key always yields the same id, so a retry of the
+ * same logical order collides broker-side instead of creating a second order.
+ *
+ * A key that is already broker-safe is used **verbatim**, which preserves the
+ * engine's `client_order_id === trade.id` convention (and keeps every
+ * reconciliation path that joins on `trade.id` working). A key needing
+ * sanitisation or truncation is rewritten and tagged with a SHA-256 digest of
+ * the original, so two distinct keys can never collapse onto one id.
+ *
+ * @param idempotencyKey - Identity of the logical order.
+ * @returns An Alpaca-safe, length-bounded `client_order_id`.
+ * @throws Error when the key is empty or whitespace-only.
+ */
+function deriveClientOrderId(idempotencyKey) {
+    const key = requireIdempotencyKey(idempotencyKey);
+    const sanitized = key.replace(UNSAFE_CLIENT_ORDER_ID_CHARS, "-");
+    if (sanitized === key && key.length <= MAX_CLIENT_ORDER_ID_LENGTH) {
+        return key;
+    }
+    const digest = createHash("sha256")
+        .update(key)
+        .digest("hex")
+        .slice(0, CLIENT_ORDER_ID_DIGEST_LENGTH);
+    const headLength = MAX_CLIENT_ORDER_ID_LENGTH -
+        digest.length -
+        CLIENT_ORDER_ID_DIGEST_SEPARATOR.length;
+    return `${sanitized.slice(0, headLength)}${CLIENT_ORDER_ID_DIGEST_SEPARATOR}${digest}`;
+}
+/**
+ * Validates a `client_order_id` a caller supplied **explicitly**, instead of
+ * letting it be derived from the idempotency key.
+ *
+ * An explicit id bypasses {@link deriveClientOrderId}, so it must satisfy the
+ * same broker contract on its own: non-empty, within Alpaca's length bound, and
+ * free of characters Alpaca rejects. A blank or malformed id is refused here
+ * rather than submitted — a submission the broker ignores or rejects leaves the
+ * POST non-idempotent, which is the F-0035 failure this contract exists to
+ * close. It is never silently rewritten: rewriting a caller-chosen id would
+ * break every reconciliation path that joins on it.
+ *
+ * @param clientOrderId - The explicitly supplied broker id.
+ * @returns The id, unchanged.
+ * @throws Error when the id is blank, over-length, or contains characters
+ *   Alpaca does not accept.
+ */
+function requireExplicitClientOrderId(clientOrderId) {
+    if (clientOrderId.trim().length === 0) {
+        throw new Error("Order submission was given a blank client_order_id; supply a non-empty id or omit it and let the idempotency key derive one");
+    }
+    if (clientOrderId.length > MAX_CLIENT_ORDER_ID_LENGTH) {
+        throw new Error(`Order submission client_order_id exceeds Alpaca's ${MAX_CLIENT_ORDER_ID_LENGTH}-character limit (${clientOrderId.length})`);
+    }
+    if (clientOrderId.replace(UNSAFE_CLIENT_ORDER_ID_CHARS, "-") !== clientOrderId) {
+        throw new Error(`Order submission client_order_id "${clientOrderId}" contains characters Alpaca does not accept`);
+    }
+    return clientOrderId;
+}
+/**
+ * Renders everything the broker said about a rejection: the error message plus
+ * the vendor payload, which is where Alpaca puts the actual reason (the SDK's
+ * own message is only "Request failed with status code NNN").
+ *
+ * @param error - The thrown value.
+ * @returns A single human-readable description.
+ */
+function describeRejection(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (typeof error !== "object" || error === null) {
+        return message;
+    }
+    const response = error.response;
+    if (typeof response !== "object" || response === null) {
+        return message;
+    }
+    const data = response.data;
+    if (data === undefined || data === null) {
+        return message;
+    }
+    const rendered = typeof data === "string" ? data : JSON.stringify(data);
+    return `${message}: ${rendered}`;
+}
+/**
+ * Whether a rejection is Alpaca's duplicate-`client_order_id` refusal — decided
+ * from the typed HTTP status plus the vendor payload, never from a status-shaped
+ * number found loose in the text.
+ *
+ * @param error - The thrown value.
+ * @returns true when the broker refused the order as a duplicate.
+ */
+function isDuplicateClientOrderIdRejection(error) {
+    if (classifyRetryError(error).status !== DUPLICATE_CLIENT_ORDER_ID_STATUS) {
+        return false;
+    }
+    return DUPLICATE_CLIENT_ORDER_ID_PATTERN.test(describeRejection(error));
+}
+/**
+ * Looks up an order by its `client_order_id`.
+ *
+ * @param client - The AlpacaClient instance
+ * @param clientOrderId - The idempotency key the order was submitted with
+ * @returns The order, or null when the broker holds no order for that id
+ * @throws The underlying error when the lookup fails for any reason other than
+ *   "not found" — an unverifiable lookup must never be read as "no order".
+ *
+ * @example
+ * const existing = await getOrderByClientOrderId(client, trade.id);
+ */
+async function getOrderByClientOrderId(client, clientOrderId) {
+    try {
+        const sdk = client.getSDK();
+        return await client.executeWithRateLimit(() => sdk.getOrderByClientId(clientOrderId), `getOrderByClientOrderId ${clientOrderId}`);
+    }
+    catch (error) {
+        if (classifyRetryError(error).status === ORDER_NOT_FOUND_STATUS) {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Resolves a duplicate-`client_order_id` rejection **without ever issuing a
+ * second POST**.
+ *
+ * - Colliding order live or filled → returned as idempotent success. This is
+ *   the retry-after-network-failure case the key exists to de-duplicate.
+ * - Colliding order terminally dead, absent, or unverifiable → typed
+ *   {@link DuplicateClientOrderIdError}. Fails **closed**: the 422 proves an
+ *   order with this id exists, so resubmitting could double-fill.
+ *
+ * @param client - The AlpacaClient instance
+ * @param clientOrderId - The id the broker refused as a duplicate
+ * @param symbol - Symbol, for log attribution
+ * @param cause - The original duplicate rejection
+ * @returns The already-submitted order when it is live or filled
+ */
+async function resolveDuplicateSubmission(client, clientOrderId, symbol, cause) {
+    let existing;
+    try {
+        existing = await getOrderByClientOrderId(client, clientOrderId);
+    }
+    catch (lookupError) {
+        const reason = lookupError instanceof Error ? lookupError.message : String(lookupError);
+        log$6(`Duplicate-order lookup failed for ${clientOrderId}; failing closed (no resubmit): ${reason}`, { type: "error", symbol, metadata: { clientOrderId } });
+        throw new DuplicateClientOrderIdError(`Duplicate client_order_id "${clientOrderId}" rejected by Alpaca and the existing-order lookup failed; refusing to resubmit (possible live duplicate)`, clientOrderId, false, lookupError);
+    }
+    if (existing && !TERMINAL_DEAD_ORDER_STATUSES.has(existing.status)) {
+        log$6(`client_order_id ${clientOrderId} already submitted (status=${existing.status}); returning existing order ${existing.id} as idempotent success`, {
+            type: "warn",
+            symbol,
+            metadata: {
+                outcome: "idempotent_return",
+                clientOrderId,
+                orderId: existing.id,
+                status: existing.status,
+            },
+        });
+        return existing;
+    }
+    throw new DuplicateClientOrderIdError(existing
+        ? `Duplicate client_order_id "${clientOrderId}" collided with a terminal (${existing.status}) order; a new logical order needs a new idempotency key`
+        : `Duplicate client_order_id "${clientOrderId}" rejected by Alpaca but no order carries that id; refusing to resubmit`, clientOrderId, false, cause);
+}
 /**
  * Creates a new order using the Alpaca SDK.
  * Supports market, limit, stop, and stop_limit order types.
  *
+ * Every submission carries a `client_order_id`, so the retry the underlying
+ * client performs on transient network failure can never fill the same order
+ * twice: the re-sent POST is refused broker-side and the order that landed is
+ * returned (F-0035).
+ *
+ * Where that id comes from, in precedence order:
+ *
+ * 1. an explicit `params.client_order_id` — validated (non-empty, length- and
+ *    charset-safe) and used verbatim, never blanked, never silently rewritten;
+ * 2. `params.idempotencyKey` — the identity of the **logical** order, from
+ *    which {@link deriveClientOrderId} derives the id deterministically, so a
+ *    resubmission of the same logical order collides at the broker instead of
+ *    creating a second position;
+ * 3. neither — a key is minted for this submission alone. **This is the
+ *    deprecated path.** It closes the transport-retry double-fill and nothing
+ *    more: two `createOrder` calls for the same logical order are two distinct
+ *    ids and therefore two live orders. It exists because published callers
+ *    that carry no order identity would otherwise fail to compile, it logs a
+ *    warning with `outcome: "generated_idempotency_key"` on every submission,
+ *    and it is removed once those callers pass their own identity.
+ *
  * @param client - The AlpacaClient instance
- * @param params - Order parameters including symbol, qty, side, type, and time_in_force
- * @returns The created order object
- * @throws Error if order creation fails
+ * @param params - Order parameters (symbol, qty, side, type, time_in_force);
+ *   supply `idempotencyKey` (or an explicit `client_order_id`) to get
+ *   caller-level idempotency rather than transport-level only
+ * @returns The created order, or the already-submitted order when the broker
+ *   refused the submission as a duplicate of a live/filled order
+ * @throws DuplicateClientOrderIdError when the id collides with an order that
+ *   cannot be treated as this submission's success
+ * @throws Error when a supplied idempotency key is blank, when an explicitly
+ *   supplied `client_order_id` is blank/over-length/unsafe, or if order
+ *   creation fails
  *
  * @example
- * // Create a market order
+ * // Create a market order, keyed on the originating trade
  * const order = await createOrder(client, {
  *   symbol: 'AAPL',
  *   qty: '10',
  *   side: 'buy',
  *   type: 'market',
  *   time_in_force: 'day',
+ *   idempotencyKey: trade.id,
  * });
  *
  * @example
@@ -57885,22 +58260,47 @@ const log$6 = (message, options = { type: "info" }) => {
  *   type: 'limit',
  *   limit_price: '150.00',
  *   time_in_force: 'gtc',
+ *   idempotencyKey: `${trade.id}-limit`,
  * });
  */
 async function createOrder(client, params) {
-    const { symbol, qty, side, type } = params;
-    log$6(`Creating ${type} order: ${side} ${qty || params.notional} ${symbol}`, {
+    const { idempotencyKey, ...orderParams } = params;
+    // A key that is present must be well-formed even when an explicit
+    // `client_order_id` would have won: a blank key is a caller defect, not a
+    // silent fall-through to some other identity.
+    const suppliedKey = idempotencyKey === undefined ? null : requireIdempotencyKey(idempotencyKey);
+    const isGeneratedKey = suppliedKey === null && orderParams.client_order_id === undefined;
+    // `??` would let `client_order_id: ""` through: the broker would then mint its
+    // own id and the submission would be non-idempotent again despite a valid key
+    // having been supplied. An explicit id is validated, never defaulted past.
+    const clientOrderId = orderParams.client_order_id === undefined
+        ? deriveClientOrderId(suppliedKey ?? generateSubmissionIdempotencyKey())
+        : requireExplicitClientOrderId(orderParams.client_order_id);
+    const submission = {
+        ...orderParams,
+        client_order_id: clientOrderId,
+    };
+    const { symbol, qty, side, type } = submission;
+    if (isGeneratedKey) {
+        log$6(`Order submitted with no caller idempotency key; minted ${clientOrderId} for this submission only — the transport retry is de-duplicated, a caller-level resubmission is NOT`, {
+            type: "warn",
+            symbol,
+            metadata: { outcome: "generated_idempotency_key", clientOrderId },
+        });
+    }
+    log$6(`Creating ${type} order: ${side} ${qty || submission.notional} ${symbol} (client_order_id=${clientOrderId})`, {
         type: "info",
         symbol,
     });
     try {
         const sdk = client.getSDK();
-        const order = await client.executeWithRateLimit(() => sdk.createOrder(params), `createOrder ${symbol}`);
+        const order = (await client.executeWithRateLimit(() => sdk.createOrder(submission), `createOrder ${symbol}`));
         log$6(`Order created successfully: ${order.id}`, {
             type: "info",
             symbol,
             metadata: {
                 orderId: order.id,
+                clientOrderId,
                 status: order.status,
                 type: order.type,
                 side: order.side,
@@ -57909,11 +58309,14 @@ async function createOrder(client, params) {
         return order;
     }
     catch (error) {
-        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (isDuplicateClientOrderIdRejection(error)) {
+            return await resolveDuplicateSubmission(client, clientOrderId, symbol, error);
+        }
+        const errorMessage = describeRejection(error);
         log$6(`Failed to create order for ${symbol}: ${errorMessage}`, {
             type: "error",
             symbol,
-            metadata: { params },
+            metadata: { params: submission },
         });
         throw new Error(`Failed to create ${type} order for ${symbol}: ${errorMessage}`);
     }
@@ -58251,12 +58654,15 @@ async function getOrderByClientId(client, clientOrderId) {
 
 var trading = /*#__PURE__*/Object.freeze({
     __proto__: null,
+    MAX_CLIENT_ORDER_ID_LENGTH: MAX_CLIENT_ORDER_ID_LENGTH,
     cancelAllOrders: cancelAllOrders,
     cancelOrder: cancelOrder,
     createOrder: createOrder,
+    deriveClientOrderId: deriveClientOrderId,
     getOpenOrders: getOpenOrders,
     getOrder: getOrder,
     getOrderByClientId: getOrderByClientId,
+    getOrderByClientOrderId: getOrderByClientOrderId,
     getOrders: getOrders,
     isOrderCancelable: isOrderCancelable,
     isOrderTerminal: isOrderTerminal,
@@ -63779,6 +64185,29 @@ class StampedeProtectedCache {
     has(key) {
         return this.cache.has(key);
     }
+    /**
+     * Synchronous peek at a cached value without triggering a loader.
+     *
+     * @description Returns the cached value when present and FRESH (inside its
+     * per-entry TTL), `undefined` otherwise — never coalesces onto or starts a
+     * load, never serves stale-while-revalidate data, and counts a hit only
+     * when a fresh value is returned (mirroring the read-path hit semantics so
+     * hitRatio stays truthful). Added 2026-08-08 for the engine cache
+     * consolidation: its fork exposed peek() and consumers rely on the
+     * no-load contract on hot paths.
+     *
+     * @param key - Cache key to inspect.
+     * @returns The fresh cached value, or `undefined` when absent or expired.
+     */
+    peek(key) {
+        const entry = this.cache.get(key);
+        if (entry && Date.now() < entry.expiresAt) {
+            this.stats.hits++;
+            this.emitEvent("hit", key);
+            return entry.value;
+        }
+        return undefined;
+    }
     /**
      * Delete a specific key from the cache
      *