@imbingox/acex 0.4.0-beta.10 → 0.4.0-beta.11

package/docs/api.md

@@ -430,6 +430,7 @@ interface OrderManager {
 
 - `createOrder()` 支持 `limit` / `market`
 - `limit` 可传 `postOnly: true`，Binance PAPI UM 映射为 `timeInForce=GTX`
+- 未传 `clientOrderId` 时，`createOrder()` 由 SDK 生成合规 client id（`acex-` 前缀，≤32）并作为 Binance `newClientOrderId` 发送，返回 snapshot 的 `clientOrderId` 即该值；自带 `clientOrderId` 超长或含非法字符会抛 `ORDER_INPUT_INVALID`
 - `cancelOrder()` 必须传 `orderId` 或 `clientOrderId`
 - `cancelAllOrders()` 必须传 `symbol`，不支持账户级全撤
 - hedge mode 下必须显式传 `positionSide: "long" | "short"`
@@ -442,7 +443,9 @@ interface OrderManager {
 
 - OrderManager 内部按 open / closed 分层缓存订单。**closed（filled / canceled / rejected / expired）订单按 symbol 各保留最近 N 个**，`N = CreateClientOptions.order.maxClosedOrdersPerSymbol`（默认 500，非正或非整数回退默认），超限按 FIFO 裁剪最旧；**open 订单不受此上限限制**。`getOpenOrders()` 查询复杂度与历史终态订单数量无关。
 - `getOrder(input)` 需带 `orderId` 或 `clientOrderId`（否则返回 `undefined`），`symbol` 可选：
-  - 仅 `clientOrderId` 查询可命中 open 与未被裁剪的 closed；同一 `clientOrderId` 命中多笔时返回**最新一笔**（精确定位历史某一笔请用 `orderId`）。
+  - **精确查单推荐传 `symbol + orderId`**（O(1) 精确索引、唯一命中）。
+  - 仅 `clientOrderId` 查询可命中 open 与未被裁剪的 closed；当 `clientOrderId` 唯一（你自定义的或 SDK 生成的 `acex-*`）时可精确命中，但同一 `clientOrderId` 命中多笔时返回**最新一笔**（精确定位历史某一笔请用 `symbol + orderId`）。
+  - 仅传 `orderId`（不带 `symbol`）时，跨 symbol 同 `orderId` 可能多命中，返回最新一笔；ADL / 系统单会共享 `clientOrderId`（如 `adl_autoclose`），必须用 `symbol + orderId` 精确定位。
   - 同时给 `orderId` 与 `clientOrderId` 时，两者都匹配才命中。
   - 已超出保留上限被裁剪的 closed 订单将查不到（返回 `undefined`）。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.4.0-beta.10",
+  "version": "0.4.0-beta.11",
   "description": "Multi-exchange trading SDK for market data, account, and order management",
   "repository": {
     "type": "git",

package/src/managers/order-manager.ts

@@ -19,6 +19,7 @@ import {
 import { AsyncEventBus } from "../internal/async-event-bus.ts";
 import { toCanonical } from "../internal/decimal.ts";
 import { matchesOrderFilter } from "../internal/filters.ts";
+import { isTransportError } from "../internal/http-client.ts";
 import {
   canDeleteMissingFromSnapshot,
   shouldApplyWatermarkedUpdate,
@@ -46,9 +47,11 @@ interface OrderRecord {
   subscribed: boolean;
   openOrders: Map<string, Map<string, OrderSnapshot>>;
   closedOrders: Map<string, Map<string, OrderSnapshot>>;
-  orderIdIndex: Map<string, Map<string, OrderLocation>>;
-  orderIdOnlyIndex: Map<string, Set<OrderLocation>>;
-  clientOrderIdIndex: Map<string, Set<OrderLocation>>;
+  localOrderLocations: Map<string, OrderLocation>;
+  orderIdIndex: Map<string, Map<string, string>>;
+  orderIdOnlyIndex: Map<string, Set<string>>;
+  clientOrderIdIndex: Map<string, Set<string>>;
+  pendingClientOrderIdIndex: Map<string, PendingOrderClaim>;
   status: OrderDataStatus;
 }
 
@@ -57,7 +60,12 @@ type OrderTable = "open" | "closed";
 interface OrderLocation {
   table: OrderTable;
   symbol: string;
-  key: string;
+  localOrderId: string;
+}
+
+interface PendingOrderClaim {
+  localOrderId: string;
+  symbol: string;
 }
 
 interface OrderManagerOptions {
@@ -65,6 +73,14 @@ interface OrderManagerOptions {
 }
 
 const DEFAULT_MAX_CLOSED_ORDERS_PER_SYMBOL = 500;
+const SDK_CLIENT_ORDER_ID_PREFIX = "acex-";
+const VENUE_CLIENT_ORDER_ID_PATTERN = /^[.A-Z:/a-z0-9_-]{1,32}$/;
+
+const SYSTEM_CLIENT_ORDER_ID_PATTERNS = [
+  /^adl_autoclose$/,
+  /^autoclose-/,
+  /^settlement_autoclose-/,
+];
 
 function cloneOrderStatus(status: OrderDataStatus): OrderDataStatus {
   return { ...status };
@@ -76,38 +92,24 @@ function normalizeMaxClosedOrdersPerSymbol(value: number | undefined): number {
     : DEFAULT_MAX_CLOSED_ORDERS_PER_SYMBOL;
 }
 
-function getOrderLookupKey(input: {
+function getOrderLookupKeys(input: {
   symbol: string;
   orderId?: string;
   clientOrderId?: string;
-}): string | undefined {
+}): string[] {
+  const keys: string[] = [];
   if (input.orderId) {
-    return `symbol:${input.symbol}:order:${input.orderId}`;
+    keys.push(`symbol:${input.symbol}:order:${input.orderId}`);
   }
 
   if (input.clientOrderId) {
-    return `symbol:${input.symbol}:client:${input.clientOrderId}`;
+    keys.push(`symbol:${input.symbol}:client:${input.clientOrderId}`);
   }
 
-  return undefined;
+  return keys;
 }
 
-function getOrderKey(input: {
-  orderId?: string;
-  clientOrderId?: string;
-}): string | undefined {
-  if (input.orderId) {
-    return `order:${input.orderId}`;
-  }
-
-  if (input.clientOrderId) {
-    return `client:${input.clientOrderId}`;
-  }
-
-  return undefined;
-}
-
-function shouldMatchOrderIdentity(
+function shouldMatchOrderQuery(
   candidate: OrderSnapshot,
   input: { symbol?: string; orderId?: string; clientOrderId?: string },
 ): boolean {
@@ -115,10 +117,15 @@ function shouldMatchOrderIdentity(
     return false;
   }
 
-  return Boolean(
-    (input.orderId && candidate.orderId === input.orderId) ||
-      (input.clientOrderId && candidate.clientOrderId === input.clientOrderId),
-  );
+  if (input.orderId && candidate.orderId !== input.orderId) {
+    return false;
+  }
+
+  if (input.clientOrderId && candidate.clientOrderId !== input.clientOrderId) {
+    return false;
+  }
+
+  return Boolean(input.orderId || input.clientOrderId);
 }
 
 function shouldMatchStoredOrderIdentity(
@@ -133,9 +140,12 @@ function shouldMatchStoredOrderIdentity(
     return candidate.orderId === input.orderId;
   }
 
-  // clientOrderId 只作"尚未拿到 orderId 的订单"的临时身份:已带 orderId 的候选
-  // (含 clientOrderId 复用后躺在 closed 的旧订单)不得被 cid-only 更新归并,否则会
-  // carry-forward 旧 orderId、污染 closed。orderId 后填充时 candidate 仍无 orderId,照常匹配。
+  // clientOrderId is only a temporary identity for an order that does not yet
+  // have an orderId. A candidate that already carries an orderId (including an
+  // old order sitting in closed that reused this clientOrderId) must not be
+  // merged by a cid-only update; otherwise the stale orderId would be
+  // carried forward and pollute closed. When the orderId is later filled in,
+  // the candidate still lacks an orderId and matches normally.
   return Boolean(
     input.clientOrderId &&
       candidate.clientOrderId === input.clientOrderId &&
@@ -211,6 +221,7 @@ export class OrderManagerImpl
   private readonly orderStatusBus =
     new AsyncEventBus<OrderStatusChangedEvent>();
   private readonly records = new Map<string, OrderRecord>();
+  private localOrderSequence = 0;
 
   constructor(context: ClientContext, options: OrderManagerOptions = {}) {
     this.context = context;
@@ -291,11 +302,45 @@ export class OrderManagerImpl
     const account = this.context.getRegisteredAccount(input.accountId);
     this.context.ensurePrivateCredentials(input.accountId);
     this.validateCreateOrderInput(input, account.venue);
+    const record = this.getOrCreateRecord(input.accountId, account.venue);
+    const localOrderId = this.generateLocalOrderId({
+      record,
+      avoidOpenClientOrderId: input.clientOrderId === undefined,
+    });
+    const venueClientOrderId = input.clientOrderId ?? localOrderId;
+    this.addPendingClientOrderClaim(
+      record,
+      input.symbol,
+      venueClientOrderId,
+      localOrderId,
+    );
 
     try {
-      const update = await this.context.createOrder(input);
-      return this.applyCommandUpdate(input.accountId, account.venue, update);
+      const commandInput: CreateOrderInput = {
+        ...input,
+        clientOrderId: venueClientOrderId,
+      };
+      const update = await this.context.createOrder(commandInput);
+      const snapshot = this.applyCommandUpdate(
+        input.accountId,
+        account.venue,
+        update,
+        { localOrderId },
+      );
+      this.clearPendingClientOrderClaim(
+        record,
+        venueClientOrderId,
+        localOrderId,
+      );
+      return snapshot;
     } catch (error) {
+      if (!this.shouldRetainPendingClaimAfterCreateError(error)) {
+        this.clearPendingClientOrderClaim(
+          record,
+          venueClientOrderId,
+          localOrderId,
+        );
+      }
       throw this.wrapCommandError(
         "ORDER_CREATE_FAILED",
         `Failed to create order for ${input.accountId}: ${input.symbol}`,
@@ -365,13 +410,13 @@ export class OrderManagerImpl
     }
 
     if (input.symbol && input.orderId) {
-      const location = this.getOrderIdLocation(
+      const localOrderId = this.getLocalOrderIdForVenueOrderId(
         record,
         input.symbol,
         input.orderId,
       );
-      const snapshot = location
-        ? this.getSnapshotAtLocation(record, location)
+      const snapshot = localOrderId
+        ? this.getSnapshotByLocalOrderId(record, localOrderId)
         : undefined;
       if (!snapshot) {
         return undefined;
@@ -389,17 +434,8 @@ export class OrderManagerImpl
 
     if (input.orderId) {
       return this.selectLatestSnapshot(
-        this.getSnapshotsForOrderId(record, input.orderId).filter(
-          (snapshot) =>
-            shouldMatchOrderIdentity(snapshot, {
-              symbol: input.symbol,
-              orderId: input.orderId,
-            }) &&
-            (!input.clientOrderId ||
-              shouldMatchOrderIdentity(snapshot, {
-                symbol: input.symbol,
-                clientOrderId: input.clientOrderId,
-              })),
+        this.getSnapshotsForOrderId(record, input.orderId).filter((snapshot) =>
+          shouldMatchOrderQuery(snapshot, input),
         ),
       );
     }
@@ -407,11 +443,7 @@ export class OrderManagerImpl
     if (input.clientOrderId) {
       return this.selectLatestSnapshot(
         this.getSnapshotsForClientOrderId(record, input.clientOrderId).filter(
-          (snapshot) =>
-            shouldMatchOrderIdentity(snapshot, {
-              symbol: input.symbol,
-              clientOrderId: input.clientOrderId,
-            }),
+          (snapshot) => shouldMatchOrderQuery(snapshot, input),
         ),
       );
     }
@@ -529,8 +561,7 @@ export class OrderManagerImpl
 
     const openSetKeys = new Set<string>();
     for (const update of snapshot.orders) {
-      const lookupKey = getOrderLookupKey(update);
-      if (lookupKey) {
+      for (const lookupKey of getOrderLookupKeys(update)) {
         openSetKeys.add(lookupKey);
       }
       const current = this.getExistingSnapshot(record, update);
@@ -545,13 +576,11 @@ export class OrderManagerImpl
         },
       );
       if (nextSnapshot) {
-        const nextLookupKey = getOrderLookupKey(nextSnapshot);
-        if (nextLookupKey) {
+        for (const nextLookupKey of getOrderLookupKeys(nextSnapshot)) {
           openSetKeys.add(nextLookupKey);
         }
       } else if (current) {
-        const currentLookupKey = getOrderLookupKey(current);
-        if (currentLookupKey) {
+        for (const currentLookupKey of getOrderLookupKeys(current)) {
           openSetKeys.add(currentLookupKey);
         }
       }
@@ -562,8 +591,11 @@ export class OrderManagerImpl
         return false;
       }
 
-      const lookupKey = getOrderLookupKey(order);
-      if (!lookupKey || openSetKeys.has(lookupKey)) {
+      const lookupKeys = getOrderLookupKeys(order);
+      if (
+        lookupKeys.length === 0 ||
+        lookupKeys.some((lookupKey) => openSetKeys.has(lookupKey))
+      ) {
         return false;
       }
 
@@ -704,9 +736,11 @@ export class OrderManagerImpl
       subscribed: false,
       openOrders: new Map(),
       closedOrders: new Map(),
+      localOrderLocations: new Map(),
       orderIdIndex: new Map(),
       orderIdOnlyIndex: new Map(),
       clientOrderIdIndex: new Map(),
+      pendingClientOrderIdIndex: new Map(),
       status: this.createStatus(accountId, venue, "inactive"),
     };
 
@@ -740,91 +774,125 @@ export class OrderManagerImpl
     record: OrderRecord,
     update: { symbol: string; orderId?: string; clientOrderId?: string },
   ): OrderLocation | undefined {
+    const resolution = this.resolveLocalOrderIdForUpdate(record, update);
+    return resolution.localOrderId
+      ? record.localOrderLocations.get(resolution.localOrderId)
+      : undefined;
+  }
+
+  private resolveLocalOrderIdForUpdate(
+    record: OrderRecord,
+    update: { symbol: string; orderId?: string; clientOrderId?: string },
+    preferredLocalOrderId?: string,
+  ): {
+    localOrderId?: string;
+    source?: "exact" | "pending" | "provisional" | "preferred";
+  } {
     if (update.orderId) {
-      const location = this.getOrderIdLocation(
+      const exact = this.getLocalOrderIdForVenueOrderId(
         record,
         update.symbol,
         update.orderId,
       );
-      const snapshot = location
-        ? this.getSnapshotAtLocation(record, location)
-        : undefined;
-      if (snapshot && shouldMatchStoredOrderIdentity(snapshot, update)) {
-        return location;
+      if (exact) {
+        return { localOrderId: exact, source: "exact" };
       }
     }
 
-    if (!update.clientOrderId) {
-      return undefined;
+    if (preferredLocalOrderId) {
+      return { localOrderId: preferredLocalOrderId, source: "preferred" };
     }
 
-    for (const location of record.clientOrderIdIndex.get(
-      update.clientOrderId,
-    ) ?? []) {
-      const snapshot = this.getSnapshotAtLocation(record, location);
-      if (snapshot && shouldMatchStoredOrderIdentity(snapshot, update)) {
-        return location;
+    if (update.clientOrderId) {
+      const pending = record.pendingClientOrderIdIndex.get(
+        update.clientOrderId,
+      );
+      if (pending?.symbol === update.symbol) {
+        return { localOrderId: pending.localOrderId, source: "pending" };
       }
     }
 
-    return undefined;
+    if (
+      update.clientOrderId &&
+      !this.isSystemClientOrderId(update.clientOrderId)
+    ) {
+      for (const localOrderId of record.clientOrderIdIndex.get(
+        update.clientOrderId,
+      ) ?? []) {
+        const snapshot = this.getSnapshotByLocalOrderId(record, localOrderId);
+        if (snapshot && shouldMatchStoredOrderIdentity(snapshot, update)) {
+          return { localOrderId, source: "provisional" };
+        }
+      }
+    }
+
+    return {};
   }
 
   private setSnapshot(
     record: OrderRecord,
+    localOrderId: string,
     snapshot: OrderSnapshot,
-    previous?: OrderSnapshot,
+    previousLocation?: OrderLocation,
   ): OrderLocation | undefined {
-    const existing = previous ?? this.getExistingSnapshot(record, snapshot);
-    const previousLocation = existing
-      ? this.getSnapshotLocation(existing)
-      : undefined;
+    if (!snapshot.orderId && !snapshot.clientOrderId) {
+      this.warnDroppedUnkeyedTerminalOrder(record, snapshot);
+      return undefined;
+    }
 
-    if (previousLocation) {
-      return this.moveSnapshot(record, previousLocation, snapshot);
+    const currentLocation =
+      previousLocation ?? record.localOrderLocations.get(localOrderId);
+    if (currentLocation) {
+      return this.moveSnapshot(record, currentLocation, localOrderId, snapshot);
     }
 
-    return this.insertSnapshot(record, snapshot);
+    return this.insertSnapshot(record, localOrderId, snapshot);
   }
 
   private insertSnapshot(
     record: OrderRecord,
+    localOrderId: string,
     snapshot: OrderSnapshot,
   ): OrderLocation | undefined {
-    const location = this.getSnapshotLocation(snapshot);
-    if (!location) {
-      this.warnDroppedUnkeyedTerminalOrder(record, snapshot);
-      return undefined;
+    const existingLocation = record.localOrderLocations.get(localOrderId);
+    if (existingLocation) {
+      this.deleteSnapshot(record, existingLocation);
     }
 
-    this.deleteSnapshot(record, location);
+    const location: OrderLocation = {
+      table: isOpenOrder(snapshot) ? "open" : "closed",
+      symbol: snapshot.symbol,
+      localOrderId,
+    };
 
     const table = this.getOrderTable(record, location.table);
     const symbolOrders = this.getOrCreateSymbolOrders(table, location.symbol);
-    symbolOrders.set(location.key, snapshot);
-    this.trimClosedOrdersForSymbol(record, location);
+    symbolOrders.set(localOrderId, snapshot);
+    record.localOrderLocations.set(localOrderId, location);
 
     if (snapshot.orderId) {
       const symbolIndex = this.getOrCreateOrderIdSymbolIndex(
         record,
         snapshot.symbol,
       );
-      symbolIndex.set(snapshot.orderId, location);
-      this.addLocationToSetIndex(
+      symbolIndex.set(snapshot.orderId, localOrderId);
+      this.addLocalOrderIdToSetIndex(
         record.orderIdOnlyIndex,
         snapshot.orderId,
-        location,
+        localOrderId,
       );
     }
 
     if (snapshot.clientOrderId) {
-      this.addLocationToSetIndex(
+      this.addLocalOrderIdToSetIndex(
         record.clientOrderIdIndex,
         snapshot.clientOrderId,
-        location,
+        localOrderId,
       );
     }
 
+    this.trimClosedOrdersForSymbol(record, location);
+    this.warnSystemClientOrderIdOnlyClaim(record, snapshot);
     this.warnProvisionalTerminalOrder(record, snapshot);
     return location;
   }
@@ -840,34 +908,35 @@ export class OrderManagerImpl
 
     const table = this.getOrderTable(record, location.table);
     const symbolOrders = table.get(location.symbol);
-    symbolOrders?.delete(location.key);
+    symbolOrders?.delete(location.localOrderId);
     if (symbolOrders?.size === 0) {
       table.delete(location.symbol);
     }
+    record.localOrderLocations.delete(location.localOrderId);
 
     if (snapshot.orderId) {
       const symbolIndex = record.orderIdIndex.get(location.symbol);
       if (
         symbolIndex?.get(snapshot.orderId) &&
-        this.locationsEqual(symbolIndex.get(snapshot.orderId), location)
+        symbolIndex.get(snapshot.orderId) === location.localOrderId
       ) {
         symbolIndex.delete(snapshot.orderId);
       }
       if (symbolIndex?.size === 0) {
         record.orderIdIndex.delete(location.symbol);
       }
-      this.removeLocationFromSetIndex(
+      this.removeLocalOrderIdFromSetIndex(
         record.orderIdOnlyIndex,
         snapshot.orderId,
-        location,
+        location.localOrderId,
       );
     }
 
     if (snapshot.clientOrderId) {
-      this.removeLocationFromSetIndex(
+      this.removeLocalOrderIdFromSetIndex(
         record.clientOrderIdIndex,
         snapshot.clientOrderId,
-        location,
+        location.localOrderId,
       );
     }
 
@@ -877,10 +946,11 @@ export class OrderManagerImpl
   private moveSnapshot(
     record: OrderRecord,
     previousLocation: OrderLocation,
+    localOrderId: string,
     snapshot: OrderSnapshot,
   ): OrderLocation | undefined {
     this.deleteSnapshot(record, previousLocation);
-    return this.insertSnapshot(record, snapshot);
+    return this.insertSnapshot(record, localOrderId, snapshot);
   }
 
   private trimClosedOrdersForSymbol(
@@ -910,40 +980,50 @@ export class OrderManagerImpl
         this.deleteSnapshot(record, {
           table: "closed",
           symbol: location.symbol,
-          key: next.value,
+          localOrderId: next.value,
         });
       }
       symbolOrders = record.closedOrders.get(location.symbol);
     }
   }
 
-  private getSnapshotLocation(
+  private warnDroppedUnkeyedTerminalOrder(
+    record: OrderRecord,
     snapshot: OrderSnapshot,
-  ): OrderLocation | undefined {
-    const key = getOrderKey(snapshot);
-    if (!key) {
-      return undefined;
+  ): void {
+    if (isOpenOrder(snapshot)) {
+      return;
     }
 
-    return {
-      table: isOpenOrder(snapshot) ? "open" : "closed",
-      symbol: snapshot.symbol,
-      key,
-    };
+    this.context.publishRuntimeError(
+      "order",
+      new Error(
+        "Dropped terminal order update without orderId or clientOrderId",
+      ),
+      {
+        accountId: record.accountId,
+        venue: record.venue,
+        symbol: snapshot.symbol,
+      },
+    );
   }
 
-  private warnDroppedUnkeyedTerminalOrder(
+  private warnSystemClientOrderIdOnlyClaim(
     record: OrderRecord,
     snapshot: OrderSnapshot,
   ): void {
-    if (isOpenOrder(snapshot)) {
+    if (
+      snapshot.orderId ||
+      !snapshot.clientOrderId ||
+      !this.isSystemClientOrderId(snapshot.clientOrderId)
+    ) {
       return;
     }
 
     this.context.publishRuntimeError(
       "order",
       new Error(
-        "Dropped terminal order update without orderId or clientOrderId",
+        "Received system clientOrderId without orderId; cid-only claim is unstable",
       ),
       {
         accountId: record.accountId,
@@ -957,8 +1037,10 @@ export class OrderManagerImpl
     record: OrderRecord,
     snapshot: OrderSnapshot,
   ): void {
-    // 终态单缺 orderId 但有 clientOrderId: 用 client key provisional 存储并告警。
-    // adapter 契约要求终态带 orderId(见 adapter-contract.md);仅 cid 无法保证稳定唯一主键。
+    // Terminal order missing orderId but carrying clientOrderId: stored under a
+    // provisional client key and warned. The adapter contract requires terminal
+    // updates to carry orderId (see adapter-contract.md); clientOrderId alone
+    // cannot guarantee a stable unique primary key.
     if (snapshot.orderId || isOpenOrder(snapshot) || !snapshot.clientOrderId) {
       return;
     }
@@ -982,7 +1064,15 @@ export class OrderManagerImpl
   ): OrderSnapshot | undefined {
     return this.getOrderTable(record, location.table)
       .get(location.symbol)
-      ?.get(location.key);
+      ?.get(location.localOrderId);
+  }
+
+  private getSnapshotByLocalOrderId(
+    record: OrderRecord,
+    localOrderId: string,
+  ): OrderSnapshot | undefined {
+    const location = record.localOrderLocations.get(localOrderId);
+    return location ? this.getSnapshotAtLocation(record, location) : undefined;
   }
 
   private getOrderTable(
@@ -1009,22 +1099,22 @@ export class OrderManagerImpl
   private getOrCreateOrderIdSymbolIndex(
     record: OrderRecord,
     symbol: string,
-  ): Map<string, OrderLocation> {
+  ): Map<string, string> {
     const existing = record.orderIdIndex.get(symbol);
     if (existing) {
       return existing;
     }
 
-    const created = new Map<string, OrderLocation>();
+    const created = new Map<string, string>();
     record.orderIdIndex.set(symbol, created);
     return created;
   }
 
-  private getOrderIdLocation(
+  private getLocalOrderIdForVenueOrderId(
     record: OrderRecord,
     symbol: string,
     orderId: string,
-  ): OrderLocation | undefined {
+  ): string | undefined {
     return record.orderIdIndex.get(symbol)?.get(orderId);
   }
 
@@ -1032,7 +1122,7 @@ export class OrderManagerImpl
     record: OrderRecord,
     orderId: string,
   ): OrderSnapshot[] {
-    return this.getSnapshotsForLocations(
+    return this.getSnapshotsForLocalOrderIds(
       record,
       record.orderIdOnlyIndex.get(orderId),
     );
@@ -1042,23 +1132,23 @@ export class OrderManagerImpl
     record: OrderRecord,
     clientOrderId: string,
   ): OrderSnapshot[] {
-    return this.getSnapshotsForLocations(
+    return this.getSnapshotsForLocalOrderIds(
       record,
       record.clientOrderIdIndex.get(clientOrderId),
     );
   }
 
-  private getSnapshotsForLocations(
+  private getSnapshotsForLocalOrderIds(
     record: OrderRecord,
-    locations?: Iterable<OrderLocation>,
+    localOrderIds?: Iterable<string>,
   ): OrderSnapshot[] {
-    if (!locations) {
+    if (!localOrderIds) {
       return [];
     }
 
     const snapshots: OrderSnapshot[] = [];
-    for (const location of locations) {
-      const snapshot = this.getSnapshotAtLocation(record, location);
+    for (const localOrderId of localOrderIds) {
+      const snapshot = this.getSnapshotByLocalOrderId(record, localOrderId);
       if (snapshot) {
         snapshots.push(snapshot);
       }
@@ -1107,56 +1197,39 @@ export class OrderManagerImpl
     return size;
   }
 
-  private addLocationToSetIndex(
-    index: Map<string, Set<OrderLocation>>,
+  private addLocalOrderIdToSetIndex(
+    index: Map<string, Set<string>>,
     key: string,
-    location: OrderLocation,
+    localOrderId: string,
   ): void {
-    this.removeLocationFromSetIndex(index, key, location);
+    this.removeLocalOrderIdFromSetIndex(index, key, localOrderId);
 
-    const locations = index.get(key);
-    if (locations) {
-      locations.add(location);
+    const localOrderIds = index.get(key);
+    if (localOrderIds) {
+      localOrderIds.add(localOrderId);
       return;
     }
 
-    index.set(key, new Set([location]));
+    index.set(key, new Set([localOrderId]));
   }
 
-  private removeLocationFromSetIndex(
-    index: Map<string, Set<OrderLocation>>,
+  private removeLocalOrderIdFromSetIndex(
+    index: Map<string, Set<string>>,
     key: string,
-    location: OrderLocation,
+    localOrderId: string,
   ): void {
-    const locations = index.get(key);
-    if (!locations) {
+    const localOrderIds = index.get(key);
+    if (!localOrderIds) {
       return;
     }
 
-    for (const candidate of locations) {
-      if (this.locationsEqual(candidate, location)) {
-        locations.delete(candidate);
-        break;
-      }
-    }
+    localOrderIds.delete(localOrderId);
 
-    if (locations.size === 0) {
+    if (localOrderIds.size === 0) {
       index.delete(key);
     }
   }
 
-  private locationsEqual(
-    left: OrderLocation | undefined,
-    right: OrderLocation,
-  ): boolean {
-    return Boolean(
-      left &&
-        left.table === right.table &&
-        left.symbol === right.symbol &&
-        left.key === right.key,
-    );
-  }
-
   private selectLatestSnapshot(
     snapshots: OrderSnapshot[],
   ): OrderSnapshot | undefined {
@@ -1170,15 +1243,18 @@ export class OrderManagerImpl
       const snapshotOpen = isOpenOrder(snapshot);
       const latestOpen = isOpenOrder(latest);
       if (snapshotOpen !== latestOpen) {
-        // open 候选绝对优先:当前活跃订单优于历史终态(clientOrderId 复用时旧单已 closed)
+        // Open candidate has absolute priority: current active order takes
+        // precedence over historical terminal state (when clientOrderId is
+        // reused, the old order is already closed).
         if (snapshotOpen) {
           latest = snapshot;
         }
         continue;
       }
 
-      // 同为 open 或同为 closed: 取 updatedAt 最新。
-      // 不能用 seq —— seq 是单订单版本号,跨订单(如复用 cid 的不同订单)不可比。
+      // Both open or both closed: take the latest by updatedAt.
+      // seq must not be used -- seq is a per-order version number and is not
+      // comparable across orders (e.g. different orders that reuse a cid).
       if (snapshot.updatedAt > latest.updatedAt) {
         latest = snapshot;
       }
@@ -1194,7 +1270,12 @@ export class OrderManagerImpl
     update: RawOrderUpdate,
     options: { requestStartedAt?: number; preserveStatus?: boolean } = {},
   ): OrderSnapshot | undefined {
-    const previous = this.getExistingSnapshot(record, update);
+    const resolution = this.resolveLocalOrderIdForUpdate(record, update);
+    const localOrderId = resolution.localOrderId ?? this.generateLocalOrderId();
+    const previousLocation = record.localOrderLocations.get(localOrderId);
+    const previous = previousLocation
+      ? this.getSnapshotAtLocation(record, previousLocation)
+      : undefined;
     if (
       !shouldApplyWatermarkedUpdate(previous, update, {
         requestStartedAt: options.requestStartedAt,
@@ -1205,7 +1286,21 @@ export class OrderManagerImpl
     }
 
     const snapshot = this.createSnapshot(accountId, venue, update, previous);
-    return this.setSnapshot(record, snapshot, previous) ? snapshot : undefined;
+    const location = this.setSnapshot(
+      record,
+      localOrderId,
+      snapshot,
+      previousLocation,
+    );
+    if (location && resolution.source === "pending" && update.clientOrderId) {
+      this.clearPendingClientOrderClaim(
+        record,
+        update.clientOrderId,
+        localOrderId,
+      );
+    }
+
+    return location ? snapshot : undefined;
   }
 
   private createSnapshot(
@@ -1291,6 +1386,78 @@ export class OrderManagerImpl
     this.context.publishHealthEvent(event);
   }
 
+  private generateLocalOrderId(options?: {
+    record?: OrderRecord;
+    avoidOpenClientOrderId?: boolean;
+  }): string {
+    while (true) {
+      const candidate = `${SDK_CLIENT_ORDER_ID_PREFIX}${this.context.now().toString(36)}-${(this.localOrderSequence++).toString(36)}`;
+      if (
+        (options?.record &&
+          options.avoidOpenClientOrderId &&
+          this.isVenueClientOrderIdInUseForOpenOrder(
+            options.record,
+            candidate,
+          )) ||
+        options?.record?.pendingClientOrderIdIndex.has(candidate) ||
+        !VENUE_CLIENT_ORDER_ID_PATTERN.test(candidate)
+      ) {
+        continue;
+      }
+
+      return candidate;
+    }
+  }
+
+  private isVenueClientOrderIdInUseForOpenOrder(
+    record: OrderRecord,
+    venueClientOrderId: string,
+  ): boolean {
+    for (const localOrderId of record.clientOrderIdIndex.get(
+      venueClientOrderId,
+    ) ?? []) {
+      const location = record.localOrderLocations.get(localOrderId);
+      if (location?.table === "open") {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  private addPendingClientOrderClaim(
+    record: OrderRecord,
+    symbol: string,
+    venueClientOrderId: string,
+    localOrderId: string,
+  ): void {
+    record.pendingClientOrderIdIndex.set(venueClientOrderId, {
+      localOrderId,
+      symbol,
+    });
+  }
+
+  private clearPendingClientOrderClaim(
+    record: OrderRecord,
+    venueClientOrderId: string,
+    localOrderId: string,
+  ): void {
+    const pending = record.pendingClientOrderIdIndex.get(venueClientOrderId);
+    if (pending?.localOrderId === localOrderId) {
+      record.pendingClientOrderIdIndex.delete(venueClientOrderId);
+    }
+  }
+
+  private shouldRetainPendingClaimAfterCreateError(error: unknown): boolean {
+    return isTransportError(error) && error.kind === "timeout";
+  }
+
+  private isSystemClientOrderId(clientOrderId: string): boolean {
+    return SYSTEM_CLIENT_ORDER_ID_PATTERNS.some((pattern) =>
+      pattern.test(clientOrderId),
+    );
+  }
+
   private validateCreateOrderInput(
     input: CreateOrderInput,
     venue: Venue,
@@ -1306,6 +1473,21 @@ export class OrderManagerImpl
         },
       );
     }
+
+    if (
+      input.clientOrderId !== undefined &&
+      !VENUE_CLIENT_ORDER_ID_PATTERN.test(input.clientOrderId)
+    ) {
+      throw this.createError(
+        "ORDER_INPUT_INVALID",
+        `clientOrderId must be 1-32 Binance-safe characters: ${input.accountId}`,
+        {
+          accountId: input.accountId,
+          venue,
+          symbol: input.symbol,
+        },
+      );
+    }
   }
 
   private validateCancelOrderInput(
@@ -1331,11 +1513,21 @@ export class OrderManagerImpl
     accountId: string,
     venue: Venue,
     update: RawOrderUpdate,
+    options: { localOrderId?: string } = {},
   ): OrderSnapshot {
     const record = this.getOrCreateRecord(accountId, venue);
-    const previous = this.getExistingSnapshot(record, update);
+    const resolution = this.resolveLocalOrderIdForUpdate(
+      record,
+      update,
+      options.localOrderId,
+    );
+    const localOrderId = resolution.localOrderId ?? this.generateLocalOrderId();
+    const previousLocation = record.localOrderLocations.get(localOrderId);
+    const previous = previousLocation
+      ? this.getSnapshotAtLocation(record, previousLocation)
+      : undefined;
     const snapshot = this.createSnapshot(accountId, venue, update, previous);
-    this.setSnapshot(record, snapshot, previous);
+    this.setSnapshot(record, localOrderId, snapshot, previousLocation);
     return snapshot;
   }