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

package/src/managers/order-manager.ts

@@ -1,5 +1,8 @@
 import BigNumber from "bignumber.js";
-import type { RawOrderUpdate } from "../adapters/types.ts";
+import type {
+  RawOpenOrdersSnapshot,
+  RawOrderUpdate,
+} from "../adapters/types.ts";
 import type {
   AccountAwareManager,
   ClientContext,
@@ -8,10 +11,19 @@ import type {
   PrivateOrderDataConsumer,
   PrivateSubscriptionState,
 } from "../client/context.ts";
-import { AcexError } from "../errors.ts";
+import {
+  AcexError,
+  buildAcexErrorDetails,
+  formatAcexErrorMessage,
+} from "../errors.ts";
 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,
+} from "../internal/watermark.ts";
 import type {
   CancelAllOrdersInput,
   CancelOrderInput,
@@ -33,27 +45,164 @@ interface OrderRecord {
   accountId: string;
   venue: Venue;
   subscribed: boolean;
-  snapshots: Map<string, OrderSnapshot>;
+  openOrders: Map<string, Map<string, OrderSnapshot>>;
+  closedOrders: Map<string, Map<string, OrderSnapshot>>;
+  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;
 }
 
+type OrderTable = "open" | "closed";
+
+interface OrderLocation {
+  table: OrderTable;
+  symbol: string;
+  localOrderId: string;
+}
+
+interface PendingOrderClaim {
+  localOrderId: string;
+  symbol: string;
+}
+
+interface OrderManagerOptions {
+  maxClosedOrdersPerSymbol?: number;
+}
+
+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 };
 }
 
-function getOrderLookupKey(input: {
+function normalizeMaxClosedOrdersPerSymbol(value: number | undefined): number {
+  return value !== undefined && Number.isInteger(value) && value > 0
+    ? value
+    : DEFAULT_MAX_CLOSED_ORDERS_PER_SYMBOL;
+}
+
+function getOrderLookupKeys(input: {
+  symbol: string;
   orderId?: string;
   clientOrderId?: string;
-}): string | undefined {
+}): string[] {
+  const keys: string[] = [];
   if (input.orderId) {
-    return `order:${input.orderId}`;
+    keys.push(`symbol:${input.symbol}:order:${input.orderId}`);
   }
 
   if (input.clientOrderId) {
-    return `client:${input.clientOrderId}`;
+    keys.push(`symbol:${input.symbol}:client:${input.clientOrderId}`);
   }
 
-  return undefined;
+  return keys;
+}
+
+function shouldMatchOrderQuery(
+  candidate: OrderSnapshot,
+  input: { symbol?: string; orderId?: string; clientOrderId?: string },
+): boolean {
+  if (input.symbol && candidate.symbol !== input.symbol) {
+    return false;
+  }
+
+  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(
+  candidate: OrderSnapshot,
+  input: { symbol: string; orderId?: string; clientOrderId?: string },
+): boolean {
+  if (candidate.symbol !== input.symbol) {
+    return false;
+  }
+
+  if (candidate.orderId && input.orderId) {
+    return candidate.orderId === input.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 &&
+      !candidate.orderId,
+  );
+}
+
+function successfulStatus(
+  status: OrderDataStatus,
+  options: {
+    ready?: boolean;
+    lastReceivedAt?: number;
+    lastReadyAt?: number;
+    preserveStatus?: boolean;
+  },
+): OrderDataStatus {
+  const preservesStreamState =
+    options.preserveStatus &&
+    (status.runtimeStatus === "reconnecting" ||
+      status.reason === "ws_disconnected" ||
+      status.reason === "heartbeat_timeout");
+  const ready = options.ready ?? true;
+
+  return {
+    ...status,
+    activity: "active",
+    ready,
+    runtimeStatus: preservesStreamState ? status.runtimeStatus : "healthy",
+    reason: preservesStreamState ? status.reason : undefined,
+    lastReceivedAt: options.lastReceivedAt ?? status.lastReceivedAt,
+    lastReadyAt: ready
+      ? (options.lastReadyAt ??
+        (options.preserveStatus ? status.lastReadyAt : undefined) ??
+        Date.now())
+      : status.lastReadyAt,
+    inactiveSince: undefined,
+  };
+}
+
+function isOpenOrder(snapshot: OrderSnapshot): boolean {
+  return snapshot.status === "open" || snapshot.status === "partially_filled";
+}
+
+function orderPriority(status: OrderSnapshot["status"]): number {
+  switch (status) {
+    case "filled":
+      return 5;
+    case "canceled":
+    case "expired":
+      return 4;
+    case "rejected":
+      return 3;
+    case "partially_filled":
+      return 2;
+    case "open":
+      return 1;
+  }
 }
 
 export class OrderManagerImpl
@@ -67,13 +216,18 @@ export class OrderManagerImpl
   readonly events: OrderEventStreams;
 
   private readonly context: ClientContext;
+  private readonly maxClosedOrdersPerSymbol: number;
   private readonly orderBus = new AsyncEventBus<OrderEvent>();
   private readonly orderStatusBus =
     new AsyncEventBus<OrderStatusChangedEvent>();
   private readonly records = new Map<string, OrderRecord>();
+  private localOrderSequence = 0;
 
-  constructor(context: ClientContext) {
+  constructor(context: ClientContext, options: OrderManagerOptions = {}) {
     this.context = context;
+    this.maxClosedOrdersPerSymbol = normalizeMaxClosedOrdersPerSymbol(
+      options.maxClosedOrdersPerSymbol,
+    );
 
     this.events = {
       status: (filter) =>
@@ -102,7 +256,10 @@ export class OrderManagerImpl
   async subscribeOrders(input: SubscribeOrdersInput): Promise<void> {
     this.context.assertStarted();
     const account = this.context.getRegisteredAccount(input.accountId);
-    if (account.venue === "juplend") {
+    if (
+      this.context.getPrivateOrderCapabilities(account.venue)?.updates ===
+      "unsupported"
+    ) {
       throw this.createError(
         "VENUE_NOT_SUPPORTED",
         `Venue does not support private order subscriptions: ${account.venue}`,
@@ -145,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}`,
@@ -218,17 +409,43 @@ export class OrderManagerImpl
       return undefined;
     }
 
-    for (const snapshot of record.snapshots.values()) {
-      if (input.orderId && snapshot.orderId === input.orderId) {
-        return snapshot;
+    if (input.symbol && input.orderId) {
+      const localOrderId = this.getLocalOrderIdForVenueOrderId(
+        record,
+        input.symbol,
+        input.orderId,
+      );
+      const snapshot = localOrderId
+        ? this.getSnapshotByLocalOrderId(record, localOrderId)
+        : undefined;
+      if (!snapshot) {
+        return undefined;
       }
 
       if (
         input.clientOrderId &&
-        snapshot.clientOrderId === input.clientOrderId
+        snapshot.clientOrderId !== input.clientOrderId
       ) {
-        return snapshot;
+        return undefined;
       }
+
+      return snapshot;
+    }
+
+    if (input.orderId) {
+      return this.selectLatestSnapshot(
+        this.getSnapshotsForOrderId(record, input.orderId).filter((snapshot) =>
+          shouldMatchOrderQuery(snapshot, input),
+        ),
+      );
+    }
+
+    if (input.clientOrderId) {
+      return this.selectLatestSnapshot(
+        this.getSnapshotsForClientOrderId(record, input.clientOrderId).filter(
+          (snapshot) => shouldMatchOrderQuery(snapshot, input),
+        ),
+      );
     }
 
     return undefined;
@@ -240,15 +457,11 @@ export class OrderManagerImpl
       return [];
     }
 
-    return [...record.snapshots.values()].filter((snapshot) => {
-      if (symbol && snapshot.symbol !== symbol) {
-        return false;
-      }
+    if (symbol) {
+      return [...(record.openOrders.get(symbol)?.values() ?? [])];
+    }
 
-      return (
-        snapshot.status === "open" || snapshot.status === "partially_filled"
-      );
-    });
+    return this.getOpenOrderSnapshots(record);
   }
 
   getOrderStatus(accountId: string): OrderDataStatus | undefined {
@@ -316,7 +529,7 @@ export class OrderManagerImpl
 
     record.status = {
       ...this.createStatus(accountId, venue, "active"),
-      ready: record.snapshots.size > 0,
+      ready: this.getSnapshotCount(record) > 0,
       runtimeStatus: "bootstrap_pending",
       reason: undefined,
       lastReceivedAt: record.status.lastReceivedAt,
@@ -329,40 +542,82 @@ export class OrderManagerImpl
   onPrivateOrderBootstrap(
     accountId: string,
     venue: Venue,
-    snapshots: RawOrderUpdate[],
-  ): void {
+    snapshot: RawOpenOrdersSnapshot,
+    options: { requestStartedAt: number; preserveStatus?: boolean },
+  ): OrderSnapshot[] {
+    return this.onPrivateOrderReconcile(accountId, venue, snapshot, options);
+  }
+
+  onPrivateOrderReconcile(
+    accountId: string,
+    venue: Venue,
+    snapshot: RawOpenOrdersSnapshot,
+    options: { requestStartedAt: number; preserveStatus?: boolean },
+  ): OrderSnapshot[] {
     const record = this.getOrCreateRecord(accountId, venue);
     if (!record.subscribed) {
-      return;
+      return [];
     }
 
-    const nextSnapshots = new Map<string, OrderSnapshot>();
-    for (const update of snapshots) {
-      const snapshot = this.createSnapshot(
+    const openSetKeys = new Set<string>();
+    for (const update of snapshot.orders) {
+      for (const lookupKey of getOrderLookupKeys(update)) {
+        openSetKeys.add(lookupKey);
+      }
+      const current = this.getExistingSnapshot(record, update);
+      const nextSnapshot = this.applyUpdateToRecord(
+        record,
         accountId,
         venue,
         update,
-        this.getExistingSnapshot(record, update),
+        {
+          requestStartedAt: options.requestStartedAt,
+          preserveStatus: true,
+        },
       );
-      this.setSnapshot(nextSnapshots, snapshot);
+      if (nextSnapshot) {
+        for (const nextLookupKey of getOrderLookupKeys(nextSnapshot)) {
+          openSetKeys.add(nextLookupKey);
+        }
+      } else if (current) {
+        for (const currentLookupKey of getOrderLookupKeys(current)) {
+          openSetKeys.add(currentLookupKey);
+        }
+      }
     }
 
-    record.snapshots = nextSnapshots;
-    const orderedSnapshots = [...record.snapshots.values()];
-    const latestTs = orderedSnapshots.reduce(
-      (max, snapshot) => Math.max(max, snapshot.updatedAt),
-      0,
+    const disappeared = this.getOpenOrderSnapshots(record).filter((order) => {
+      if (!isOpenOrder(order)) {
+        return false;
+      }
+
+      const lookupKeys = getOrderLookupKeys(order);
+      if (
+        lookupKeys.length === 0 ||
+        lookupKeys.some((lookupKey) => openSetKeys.has(lookupKey))
+      ) {
+        return false;
+      }
+
+      return canDeleteMissingFromSnapshot(order, {
+        requestStartedAt: options.requestStartedAt,
+        snapshotExchangeTs: snapshot.snapshotExchangeTs,
+      });
+    });
+
+    const orderedSnapshots = this.getAllSnapshots(record);
+    const latestTs = Math.max(
+      snapshot.snapshotReceivedAt,
+      orderedSnapshots.reduce(
+        (max, order) => Math.max(max, order.updatedAt),
+        0,
+      ),
     );
-    record.status = {
-      ...record.status,
-      activity: "active",
-      ready: true,
-      runtimeStatus: "healthy",
-      reason: undefined,
+    record.status = successfulStatus(record.status, {
+      preserveStatus: options.preserveStatus,
       lastReceivedAt: latestTs || record.status.lastReceivedAt,
       lastReadyAt: latestTs || this.context.now(),
-      inactiveSince: undefined,
-    };
+    });
 
     const event: OrderSnapshotReplacedEvent = {
       type: "order.snapshot_replaced",
@@ -374,21 +629,37 @@ export class OrderManagerImpl
 
     this.orderBus.publish(event);
     this.publishStatus(record);
+    return disappeared;
+  }
+
+  getPrivateOpenOrders(accountId: string): OrderSnapshot[] {
+    return this.getOpenOrders(accountId);
   }
 
   onPrivateOrderUpdate(
     accountId: string,
     venue: Venue,
     update: RawOrderUpdate,
+    options: { requestStartedAt?: number; preserveStatus?: boolean } = {},
   ): void {
     const record = this.getOrCreateRecord(accountId, venue);
     if (!record.subscribed) {
       return;
     }
 
-    const previous = this.getExistingSnapshot(record, update);
-    const snapshot = this.createSnapshot(accountId, venue, update, previous);
-    this.setSnapshot(record.snapshots, snapshot);
+    const snapshot = this.applyUpdateToRecord(
+      record,
+      accountId,
+      venue,
+      update,
+      {
+        requestStartedAt: options.requestStartedAt,
+        preserveStatus: options.preserveStatus,
+      },
+    );
+    if (!snapshot) {
+      return;
+    }
 
     const eventType =
       snapshot.status === "filled"
@@ -408,16 +679,11 @@ export class OrderManagerImpl
       ts: this.context.now(),
     });
 
-    record.status = {
-      ...record.status,
-      activity: "active",
-      ready: true,
-      runtimeStatus: "healthy",
-      reason: undefined,
+    record.status = successfulStatus(record.status, {
+      preserveStatus: options.preserveStatus,
       lastReceivedAt: snapshot.receivedAt,
       lastReadyAt: snapshot.updatedAt,
-      inactiveSince: undefined,
-    };
+    });
     this.publishStatus(record);
   }
 
@@ -468,7 +734,13 @@ export class OrderManagerImpl
       accountId,
       venue,
       subscribed: false,
-      snapshots: new Map(),
+      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"),
     };
 
@@ -492,38 +764,545 @@ export class OrderManagerImpl
 
   private getExistingSnapshot(
     record: OrderRecord,
-    update: { orderId?: string; clientOrderId?: string },
+    update: { symbol: string; orderId?: string; clientOrderId?: string },
   ): OrderSnapshot | undefined {
-    for (const snapshot of record.snapshots.values()) {
-      if (update.orderId && snapshot.orderId === update.orderId) {
-        return snapshot;
+    const location = this.getExistingSnapshotLocation(record, update);
+    return location ? this.getSnapshotAtLocation(record, location) : undefined;
+  }
+
+  private getExistingSnapshotLocation(
+    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 exact = this.getLocalOrderIdForVenueOrderId(
+        record,
+        update.symbol,
+        update.orderId,
+      );
+      if (exact) {
+        return { localOrderId: exact, source: "exact" };
       }
+    }
 
+    if (preferredLocalOrderId) {
+      return { localOrderId: preferredLocalOrderId, source: "preferred" };
+    }
+
+    if (update.clientOrderId) {
+      const pending = record.pendingClientOrderIdIndex.get(
+        update.clientOrderId,
+      );
+      if (pending?.symbol === update.symbol) {
+        return { localOrderId: pending.localOrderId, source: "pending" };
+      }
+    }
+
+    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,
+    previousLocation?: OrderLocation,
+  ): OrderLocation | undefined {
+    if (!snapshot.orderId && !snapshot.clientOrderId) {
+      this.warnDroppedUnkeyedTerminalOrder(record, snapshot);
+      return undefined;
+    }
+
+    const currentLocation =
+      previousLocation ?? record.localOrderLocations.get(localOrderId);
+    if (currentLocation) {
+      return this.moveSnapshot(record, currentLocation, localOrderId, snapshot);
+    }
+
+    return this.insertSnapshot(record, localOrderId, snapshot);
+  }
+
+  private insertSnapshot(
+    record: OrderRecord,
+    localOrderId: string,
+    snapshot: OrderSnapshot,
+  ): OrderLocation | undefined {
+    const existingLocation = record.localOrderLocations.get(localOrderId);
+    if (existingLocation) {
+      this.deleteSnapshot(record, existingLocation);
+    }
+
+    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(localOrderId, snapshot);
+    record.localOrderLocations.set(localOrderId, location);
+
+    if (snapshot.orderId) {
+      const symbolIndex = this.getOrCreateOrderIdSymbolIndex(
+        record,
+        snapshot.symbol,
+      );
+      symbolIndex.set(snapshot.orderId, localOrderId);
+      this.addLocalOrderIdToSetIndex(
+        record.orderIdOnlyIndex,
+        snapshot.orderId,
+        localOrderId,
+      );
+    }
+
+    if (snapshot.clientOrderId) {
+      this.addLocalOrderIdToSetIndex(
+        record.clientOrderIdIndex,
+        snapshot.clientOrderId,
+        localOrderId,
+      );
+    }
+
+    this.trimClosedOrdersForSymbol(record, location);
+    this.warnSystemClientOrderIdOnlyClaim(record, snapshot);
+    this.warnProvisionalTerminalOrder(record, snapshot);
+    return location;
+  }
+
+  private deleteSnapshot(
+    record: OrderRecord,
+    location: OrderLocation,
+  ): OrderSnapshot | undefined {
+    const snapshot = this.getSnapshotAtLocation(record, location);
+    if (!snapshot) {
+      return undefined;
+    }
+
+    const table = this.getOrderTable(record, location.table);
+    const symbolOrders = table.get(location.symbol);
+    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 (
-        update.clientOrderId &&
-        snapshot.clientOrderId === update.clientOrderId
+        symbolIndex?.get(snapshot.orderId) &&
+        symbolIndex.get(snapshot.orderId) === location.localOrderId
       ) {
-        return snapshot;
+        symbolIndex.delete(snapshot.orderId);
+      }
+      if (symbolIndex?.size === 0) {
+        record.orderIdIndex.delete(location.symbol);
       }
+      this.removeLocalOrderIdFromSetIndex(
+        record.orderIdOnlyIndex,
+        snapshot.orderId,
+        location.localOrderId,
+      );
     }
 
-    return undefined;
+    if (snapshot.clientOrderId) {
+      this.removeLocalOrderIdFromSetIndex(
+        record.clientOrderIdIndex,
+        snapshot.clientOrderId,
+        location.localOrderId,
+      );
+    }
+
+    return snapshot;
   }
 
-  private setSnapshot(
-    snapshots: Map<string, OrderSnapshot>,
+  private moveSnapshot(
+    record: OrderRecord,
+    previousLocation: OrderLocation,
+    localOrderId: string,
     snapshot: OrderSnapshot,
+  ): OrderLocation | undefined {
+    this.deleteSnapshot(record, previousLocation);
+    return this.insertSnapshot(record, localOrderId, snapshot);
+  }
+
+  private trimClosedOrdersForSymbol(
+    record: OrderRecord,
+    location: OrderLocation,
   ): void {
-    const lookupKey =
-      getOrderLookupKey(snapshot) ??
-      getOrderLookupKey({
-        clientOrderId: snapshot.clientOrderId,
-      });
-    if (lookupKey) {
-      snapshots.set(lookupKey, snapshot);
+    if (location.table !== "closed") {
+      return;
+    }
+
+    let symbolOrders = record.closedOrders.get(location.symbol);
+    if (!symbolOrders || symbolOrders.size <= this.maxClosedOrdersPerSymbol) {
+      return;
+    }
+
+    const trimBatchSize = Math.max(
+      1,
+      Math.floor(this.maxClosedOrdersPerSymbol / 10),
+    );
+    while (symbolOrders && symbolOrders.size > this.maxClosedOrdersPerSymbol) {
+      const keys = symbolOrders.keys();
+      for (let deleted = 0; deleted < trimBatchSize; deleted += 1) {
+        const next = keys.next();
+        if (next.done) {
+          break;
+        }
+        this.deleteSnapshot(record, {
+          table: "closed",
+          symbol: location.symbol,
+          localOrderId: next.value,
+        });
+      }
+      symbolOrders = record.closedOrders.get(location.symbol);
     }
   }
 
+  private warnDroppedUnkeyedTerminalOrder(
+    record: OrderRecord,
+    snapshot: OrderSnapshot,
+  ): void {
+    if (isOpenOrder(snapshot)) {
+      return;
+    }
+
+    this.context.publishRuntimeError(
+      "order",
+      new Error(
+        "Dropped terminal order update without orderId or clientOrderId",
+      ),
+      {
+        accountId: record.accountId,
+        venue: record.venue,
+        symbol: snapshot.symbol,
+      },
+    );
+  }
+
+  private warnSystemClientOrderIdOnlyClaim(
+    record: OrderRecord,
+    snapshot: OrderSnapshot,
+  ): void {
+    if (
+      snapshot.orderId ||
+      !snapshot.clientOrderId ||
+      !this.isSystemClientOrderId(snapshot.clientOrderId)
+    ) {
+      return;
+    }
+
+    this.context.publishRuntimeError(
+      "order",
+      new Error(
+        "Received system clientOrderId without orderId; cid-only claim is unstable",
+      ),
+      {
+        accountId: record.accountId,
+        venue: record.venue,
+        symbol: snapshot.symbol,
+      },
+    );
+  }
+
+  private warnProvisionalTerminalOrder(
+    record: OrderRecord,
+    snapshot: OrderSnapshot,
+  ): void {
+    // 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;
+    }
+
+    this.context.publishRuntimeError(
+      "order",
+      new Error(
+        "Stored terminal order without orderId using provisional clientOrderId key",
+      ),
+      {
+        accountId: record.accountId,
+        venue: record.venue,
+        symbol: snapshot.symbol,
+      },
+    );
+  }
+
+  private getSnapshotAtLocation(
+    record: OrderRecord,
+    location: OrderLocation,
+  ): OrderSnapshot | undefined {
+    return this.getOrderTable(record, location.table)
+      .get(location.symbol)
+      ?.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(
+    record: OrderRecord,
+    table: OrderTable,
+  ): Map<string, Map<string, OrderSnapshot>> {
+    return table === "open" ? record.openOrders : record.closedOrders;
+  }
+
+  private getOrCreateSymbolOrders(
+    table: Map<string, Map<string, OrderSnapshot>>,
+    symbol: string,
+  ): Map<string, OrderSnapshot> {
+    const existing = table.get(symbol);
+    if (existing) {
+      return existing;
+    }
+
+    const created = new Map<string, OrderSnapshot>();
+    table.set(symbol, created);
+    return created;
+  }
+
+  private getOrCreateOrderIdSymbolIndex(
+    record: OrderRecord,
+    symbol: string,
+  ): Map<string, string> {
+    const existing = record.orderIdIndex.get(symbol);
+    if (existing) {
+      return existing;
+    }
+
+    const created = new Map<string, string>();
+    record.orderIdIndex.set(symbol, created);
+    return created;
+  }
+
+  private getLocalOrderIdForVenueOrderId(
+    record: OrderRecord,
+    symbol: string,
+    orderId: string,
+  ): string | undefined {
+    return record.orderIdIndex.get(symbol)?.get(orderId);
+  }
+
+  private getSnapshotsForOrderId(
+    record: OrderRecord,
+    orderId: string,
+  ): OrderSnapshot[] {
+    return this.getSnapshotsForLocalOrderIds(
+      record,
+      record.orderIdOnlyIndex.get(orderId),
+    );
+  }
+
+  private getSnapshotsForClientOrderId(
+    record: OrderRecord,
+    clientOrderId: string,
+  ): OrderSnapshot[] {
+    return this.getSnapshotsForLocalOrderIds(
+      record,
+      record.clientOrderIdIndex.get(clientOrderId),
+    );
+  }
+
+  private getSnapshotsForLocalOrderIds(
+    record: OrderRecord,
+    localOrderIds?: Iterable<string>,
+  ): OrderSnapshot[] {
+    if (!localOrderIds) {
+      return [];
+    }
+
+    const snapshots: OrderSnapshot[] = [];
+    for (const localOrderId of localOrderIds) {
+      const snapshot = this.getSnapshotByLocalOrderId(record, localOrderId);
+      if (snapshot) {
+        snapshots.push(snapshot);
+      }
+    }
+
+    return snapshots;
+  }
+
+  private getOpenOrderSnapshots(record: OrderRecord): OrderSnapshot[] {
+    return this.getSnapshotsInTable(record.openOrders);
+  }
+
+  private getAllSnapshots(record: OrderRecord): OrderSnapshot[] {
+    return [
+      ...this.getSnapshotsInTable(record.openOrders),
+      ...this.getSnapshotsInTable(record.closedOrders),
+    ];
+  }
+
+  private getSnapshotsInTable(
+    table: Map<string, Map<string, OrderSnapshot>>,
+  ): OrderSnapshot[] {
+    const snapshots: OrderSnapshot[] = [];
+    for (const symbolOrders of table.values()) {
+      snapshots.push(...symbolOrders.values());
+    }
+
+    return snapshots;
+  }
+
+  private getSnapshotCount(record: OrderRecord): number {
+    return (
+      this.getSnapshotCountInTable(record.openOrders) +
+      this.getSnapshotCountInTable(record.closedOrders)
+    );
+  }
+
+  private getSnapshotCountInTable(
+    table: Map<string, Map<string, OrderSnapshot>>,
+  ): number {
+    let size = 0;
+    for (const symbolOrders of table.values()) {
+      size += symbolOrders.size;
+    }
+
+    return size;
+  }
+
+  private addLocalOrderIdToSetIndex(
+    index: Map<string, Set<string>>,
+    key: string,
+    localOrderId: string,
+  ): void {
+    this.removeLocalOrderIdFromSetIndex(index, key, localOrderId);
+
+    const localOrderIds = index.get(key);
+    if (localOrderIds) {
+      localOrderIds.add(localOrderId);
+      return;
+    }
+
+    index.set(key, new Set([localOrderId]));
+  }
+
+  private removeLocalOrderIdFromSetIndex(
+    index: Map<string, Set<string>>,
+    key: string,
+    localOrderId: string,
+  ): void {
+    const localOrderIds = index.get(key);
+    if (!localOrderIds) {
+      return;
+    }
+
+    localOrderIds.delete(localOrderId);
+
+    if (localOrderIds.size === 0) {
+      index.delete(key);
+    }
+  }
+
+  private selectLatestSnapshot(
+    snapshots: OrderSnapshot[],
+  ): OrderSnapshot | undefined {
+    let latest: OrderSnapshot | undefined;
+    for (const snapshot of snapshots) {
+      if (!latest) {
+        latest = snapshot;
+        continue;
+      }
+
+      const snapshotOpen = isOpenOrder(snapshot);
+      const latestOpen = isOpenOrder(latest);
+      if (snapshotOpen !== latestOpen) {
+        // 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;
+      }
+
+      // 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;
+      }
+    }
+
+    return latest;
+  }
+
+  private applyUpdateToRecord(
+    record: OrderRecord,
+    accountId: string,
+    venue: Venue,
+    update: RawOrderUpdate,
+    options: { requestStartedAt?: number; preserveStatus?: boolean } = {},
+  ): OrderSnapshot | undefined {
+    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,
+        source: options.requestStartedAt === undefined ? "stream" : "rest",
+      })
+    ) {
+      return undefined;
+    }
+
+    const snapshot = this.createSnapshot(accountId, venue, update, previous);
+    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(
     accountId: string,
     venue: Venue,
@@ -531,7 +1310,13 @@ export class OrderManagerImpl
     previous?: OrderSnapshot,
   ): OrderSnapshot {
     const amount = new BigNumber(input.amount);
-    const filled = new BigNumber(input.filled);
+    const rawFilled = new BigNumber(input.filled);
+    const filled =
+      previous &&
+      input.exchangeTs !== undefined &&
+      previous.exchangeTs === input.exchangeTs
+        ? BigNumber.maximum(rawFilled, previous.filled)
+        : rawFilled;
     const remaining =
       input.remaining === undefined
         ? amount.minus(filled)
@@ -540,12 +1325,12 @@ export class OrderManagerImpl
     return {
       accountId,
       venue,
-      orderId: input.orderId,
-      clientOrderId: input.clientOrderId,
+      orderId: input.orderId ?? previous?.orderId,
+      clientOrderId: input.clientOrderId ?? previous?.clientOrderId,
       symbol: input.symbol,
       side: input.side,
       type: input.type,
-      status: input.status,
+      status: this.mergeOrderStatus(input, previous),
       price:
         input.price === undefined ? previous?.price : toCanonical(input.price),
       triggerPrice:
@@ -568,6 +1353,26 @@ export class OrderManagerImpl
     };
   }
 
+  private mergeOrderStatus(
+    input: RawOrderUpdate,
+    previous?: OrderSnapshot,
+  ): OrderSnapshot["status"] {
+    if (!previous) {
+      return input.status;
+    }
+
+    if (
+      input.exchangeTs !== undefined &&
+      previous.exchangeTs !== undefined &&
+      input.exchangeTs === previous.exchangeTs &&
+      orderPriority(input.status) < orderPriority(previous.status)
+    ) {
+      return previous.status;
+    }
+
+    return input.status;
+  }
+
   private publishStatus(record: OrderRecord): void {
     const event: OrderStatusChangedEvent = {
       type: "order.status_changed",
@@ -581,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,
@@ -596,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(
@@ -621,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.snapshots, snapshot);
+    this.setSnapshot(record, localOrderId, snapshot, previousLocation);
     return snapshot;
   }
 
@@ -653,7 +1555,8 @@ export class OrderManagerImpl
       symbol?: string;
     },
   ): AcexError {
-    const error = new AcexError(code, message);
+    const details = buildAcexErrorDetails(metadata);
+    const error = new AcexError(code, message, { details });
     this.context.publishRuntimeError("order", error, metadata);
     return error;
   }
@@ -680,6 +1583,10 @@ export class OrderManagerImpl
       error instanceof Error ? error : new Error(message),
       metadata,
     );
-    return new AcexError(code, message);
+    const details = buildAcexErrorDetails(metadata, error);
+    return new AcexError(code, formatAcexErrorMessage(message, details), {
+      cause: error,
+      details,
+    });
   }
 }