@imbingox/acex 0.4.0-beta.15 → 0.4.0-beta.16

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @imbingox/acex
 
+## 0.4.0-beta.16
+
+### Minor Changes
+
+- bdaf9ea: 订单生命周期增加 confirmed-missing 收尾与 pending claim TTL：`OrderStatus` 新增 `unknown` 终态，open 订单在 reconcile 单笔回查连续确认不存在后会移入 closed；`CreateClientOptions.order` 新增 `missingOrderEvictionThreshold` 与 `pendingClaimTtlMs`，用于配置幽灵 open 订单驱逐阈值和 `createOrder` timeout claim 回查 TTL。
+
 ## 0.4.0-beta.15
 
 ### Minor Changes

package/docs/api.md

@@ -442,7 +442,7 @@ interface OrderManager {
 
 ### 7.3 本地缓存与查询
 
-- OrderManager 内部按 open / closed 分层缓存订单。**closed（filled / canceled / rejected / expired）订单按 symbol 各保留最近 N 个**，`N = CreateClientOptions.order.maxClosedOrdersPerSymbol`（默认 500，非正或非整数回退默认），超限按 FIFO 裁剪最旧；**open 订单不受此上限限制**。`getOpenOrders()` 查询复杂度与历史终态订单数量无关。
+- OrderManager 内部按 open / closed 分层缓存订单。**closed（filled / canceled / rejected / expired / unknown）订单按 symbol 各保留最近 N 个**，`N = CreateClientOptions.order.maxClosedOrdersPerSymbol`（默认 500，非正或非整数回退默认），超限按 FIFO 裁剪最旧；**open 订单不受此上限限制**。`getOpenOrders()` 查询复杂度与历史终态订单数量无关。
 - `getOrder(input)` 需带 `orderId` 或 `clientOrderId`（否则返回 `undefined`），`symbol` 可选：
   - **精确查单推荐传 `symbol + orderId`**（O(1) 精确索引、唯一命中）。
   - 仅 `clientOrderId` 查询可命中 open 与未被裁剪的 closed；当 `clientOrderId` 唯一（你自定义的或 SDK 生成的 `acex-*`）时可精确命中，但同一 `clientOrderId` 命中多笔时返回**最新一笔**（精确定位历史某一笔请用 `symbol + orderId`）。
@@ -450,7 +450,7 @@ interface OrderManager {
   - 同时给 `orderId` 与 `clientOrderId` 时，两者都匹配才命中。
   - 已超出保留上限被裁剪的 closed 订单将查不到（返回 `undefined`）。
 
-Order 事件用于消费订单状态变化和 open orders 快照校准。Binance private reconcile 会先用 `/papi/v1/um/openOrders` 校验当前 open set；本地 open order 从 open set 消失时，SDK 会优先查询单笔订单终态并发布 `order.filled` / `order.canceled` 等事件。若 Binance retention / not found 导致无法证明终态，SDK 不会合成 filled/canceled，而是保留原 snapshot 并把 order status 标记为 `degraded`，下一轮继续尝试。
+Order 事件用于消费订单状态变化和 open orders 快照校准。Binance private reconcile 会先用 `/papi/v1/um/openOrders` 校验当前 open set；本地 open order 从 open set 消失时，SDK 会优先查询单笔订单终态并发布 `order.filled` / `order.canceled` 等事件。若单笔查询连续确认订单不存在（默认 3 次，`CreateClientOptions.order.missingOrderEvictionThreshold` 可配置），SDK 会把该订单终态化为 `status: "unknown"`、移出 open 缓存并发布一次 runtime error；网络/超时/限流等 transport 错误不会计入该阈值。`createOrder()` 超时保留的 pending claim 会在 reconcile 周期里按 `CreateClientOptions.order.pendingClaimTtlMs`（默认 90s）过期回查：查到订单则正常入库，确认不存在则清理 claim 并发布 runtime error；无 `fetchOrder` 能力的 venue 会保守保留 claim。
 
 ```ts
 for await (const event of client.order.events.updates({
@@ -499,7 +499,8 @@ type OrderStatus =
   | "filled"
   | "canceled"
   | "rejected"
-  | "expired";
+  | "expired"
+  | "unknown";
 
 type PrivateRuntimeReason =
   | "credentials_missing"
@@ -597,6 +598,8 @@ interface CreateClientOptions {
   };
   order?: {
     maxClosedOrdersPerSymbol?: number;
+    missingOrderEvictionThreshold?: number;
+    pendingClaimTtlMs?: number;
   };
 }
 

package/package.json

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

package/src/client/context.ts

@@ -73,6 +73,13 @@ export interface PrivateSubscriptionState {
   lastReadyAt?: number;
 }
 
+export interface ExpiredPendingOrderClaim {
+  venueClientOrderId: string;
+  localOrderId: string;
+  symbol: string;
+  claimedAt: number;
+}
+
 export interface PrivateAccountDataConsumer {
   onPrivateAccountPending(accountId: string, venue: Venue): void;
   onPrivateAccountBootstrap(
@@ -119,7 +126,22 @@ export interface PrivateOrderDataConsumer {
     update: RawOrderUpdate,
     options?: { requestStartedAt?: number; preserveStatus?: boolean },
   ): void;
+  onPrivateOrderConfirmedMissing(
+    accountId: string,
+    venue: Venue,
+    order: OrderSnapshot,
+  ): void;
   getPrivateOpenOrders(accountId: string): OrderSnapshot[];
+  getExpiredPrivateOrderClaims(
+    accountId: string,
+    now: number,
+    ttlMs: number,
+  ): ExpiredPendingOrderClaim[];
+  onPrivateOrderClaimNotFound(
+    accountId: string,
+    venue: Venue,
+    claim: ExpiredPendingOrderClaim,
+  ): void;
   onPrivateOrderStreamState(
     accountId: string,
     venue: Venue,

package/src/client/private-subscription-coordinator.ts

@@ -12,12 +12,14 @@ import {
 import { isTransportError } from "../internal/http-client.ts";
 import type {
   AccountRuntimeOptions,
+  OrderRuntimeOptions,
   OrderSnapshot,
   PrivateRuntimeReason,
   Venue,
 } from "../types/index.ts";
 import type {
   ClientContext,
+  ExpiredPendingOrderClaim,
   PrivateAccountDataConsumer,
   PrivateOrderDataConsumer,
   RegisteredAccountRecord,
@@ -50,6 +52,7 @@ const DEFAULT_LISTEN_KEY_KEEPALIVE_MS = 30 * 60 * 1_000;
 const DEFAULT_PRIVATE_STREAM_STALE_AFTER_MS = 65 * 60_000;
 const DEFAULT_BINANCE_RISK_POLL_INTERVAL_MS = 5_000;
 const DEFAULT_BINANCE_PRIVATE_RECONCILE_INTERVAL_MS = 60_000;
+const DEFAULT_PENDING_CLAIM_TTL_MS = 90_000;
 const MAX_ORDER_TERMINAL_BACKFILLS_PER_RECONCILE = 20;
 const MAX_ORDER_TERMINAL_BACKFILL_CONCURRENCY = 4;
 
@@ -94,6 +97,7 @@ export class PrivateSubscriptionCoordinator {
   private readonly binancePrivateStreamStaleAfterMs: number;
   private readonly binanceRiskPollIntervalMs: number;
   private readonly binancePrivateReconcileIntervalMs: number | undefined;
+  private readonly pendingClaimTtlMs: number;
   private readonly records = new Map<string, PrivateSubscriptionRecord>();
 
   constructor(
@@ -102,6 +106,7 @@ export class PrivateSubscriptionCoordinator {
     accountConsumer: PrivateAccountDataConsumer,
     orderConsumer: PrivateOrderDataConsumer,
     options: AccountRuntimeOptions = {},
+    orderOptions: OrderRuntimeOptions = {},
   ) {
     this.context = context;
     this.adapters = new Map(
@@ -130,6 +135,10 @@ export class PrivateSubscriptionCoordinator {
       options.binance?.privateReconcileIntervalMs,
       DEFAULT_BINANCE_PRIVATE_RECONCILE_INTERVAL_MS,
     );
+    this.pendingClaimTtlMs = normalizePositiveInterval(
+      orderOptions.pendingClaimTtlMs,
+      DEFAULT_PENDING_CLAIM_TTL_MS,
+    );
   }
 
   async subscribeAccountFeed(accountId: string): Promise<void> {
@@ -940,6 +949,12 @@ export class PrivateSubscriptionCoordinator {
         orderGeneration,
         disappeared,
       );
+      await this.reconcileExpiredPendingOrderClaims(
+        record,
+        account,
+        generation,
+        orderGeneration,
+      );
     } catch (error) {
       if (
         !this.shouldContinueOrderBootstrap(record, generation, orderGeneration)
@@ -1054,11 +1069,104 @@ export class PrivateSubscriptionCoordinator {
       }
 
       if (!update) {
-        this.handleOrderReconcileError(
-          record,
-          new Error(
-            `Failed to backfill disappeared ${record.venue} order terminal state`,
-          ),
+        this.orderConsumer.onPrivateOrderConfirmedMissing(
+          record.accountId,
+          record.venue,
+          order,
+        );
+        return;
+      }
+
+      this.orderConsumer.onPrivateOrderUpdate(
+        record.accountId,
+        record.venue,
+        update,
+        {
+          requestStartedAt,
+        },
+      );
+    } catch (error) {
+      if (
+        !this.shouldContinueOrderBootstrap(record, generation, orderGeneration)
+      ) {
+        return;
+      }
+
+      this.handleOrderReconcileError(record, error);
+    }
+  }
+
+  private async reconcileExpiredPendingOrderClaims(
+    record: PrivateSubscriptionRecord,
+    account: RegisteredAccountRecord,
+    generation: number,
+    orderGeneration: number,
+  ): Promise<void> {
+    const adapter = this.getAdapter(record.venue);
+    if (
+      !this.shouldContinueOrderBootstrap(record, generation, orderGeneration)
+    ) {
+      return;
+    }
+
+    if (!adapter.fetchOrder) {
+      // Pending createOrder claims can only be retired after the venue confirms
+      // the clientOrderId is absent. Adapters without fetchOrder keep claims.
+      return;
+    }
+
+    const expiredClaims = this.orderConsumer.getExpiredPrivateOrderClaims(
+      record.accountId,
+      this.context.now(),
+      this.pendingClaimTtlMs,
+    );
+    for (const claim of expiredClaims) {
+      await this.reconcileExpiredPendingOrderClaim(
+        record,
+        account,
+        generation,
+        orderGeneration,
+        claim,
+      );
+    }
+  }
+
+  private async reconcileExpiredPendingOrderClaim(
+    record: PrivateSubscriptionRecord,
+    account: RegisteredAccountRecord,
+    generation: number,
+    orderGeneration: number,
+    claim: ExpiredPendingOrderClaim,
+  ): Promise<void> {
+    const adapter = this.getAdapter(record.venue);
+    if (
+      !adapter.fetchOrder ||
+      !this.shouldContinueOrderBootstrap(record, generation, orderGeneration)
+    ) {
+      return;
+    }
+
+    const requestStartedAt = this.context.now();
+    try {
+      const update = await adapter.fetchOrder(
+        account.credentials ?? {},
+        {
+          symbol: claim.symbol,
+          clientOrderId: claim.venueClientOrderId,
+        },
+        { ...account.options, accountId: account.accountId },
+      );
+      if (
+        !this.shouldContinueOrderBootstrap(record, generation, orderGeneration)
+      ) {
+        return;
+      }
+
+      if (!update) {
+        this.orderConsumer.onPrivateOrderClaimNotFound(
+          record.accountId,
+          record.venue,
+          claim,
         );
         return;
       }

package/src/client/runtime.ts

@@ -143,6 +143,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
       this.accountManager as PrivateAccountDataConsumer,
       this.orderManager as PrivateOrderDataConsumer,
       options.account,
+      options.order,
     );
 
     this.market = this.marketManager;

package/src/managers/order/data-status.ts

@@ -1,6 +1,7 @@
 import type { OrderDataStatus, Venue } from "../../types/index.ts";
 
 export const DEFAULT_MAX_CLOSED_ORDERS_PER_SYMBOL = 500;
+export const DEFAULT_MISSING_ORDER_EVICTION_THRESHOLD = 3;
 
 export function cloneOrderStatus(status: OrderDataStatus): OrderDataStatus {
   return { ...status };
@@ -28,6 +29,14 @@ export function normalizeMaxClosedOrdersPerSymbol(
     : DEFAULT_MAX_CLOSED_ORDERS_PER_SYMBOL;
 }
 
+export function normalizeMissingOrderEvictionThreshold(
+  value: number | undefined,
+): number {
+  return value !== undefined && Number.isInteger(value) && value > 0
+    ? value
+    : DEFAULT_MISSING_ORDER_EVICTION_THRESHOLD;
+}
+
 export function successfulStatus(
   status: OrderDataStatus,
   options: {

package/src/managers/order/model.ts

@@ -15,6 +15,7 @@ export interface OrderRecord {
   orderIdOnlyIndex: Map<string, Set<string>>;
   clientOrderIdIndex: Map<string, Set<string>>;
   pendingClientOrderIdIndex: Map<string, PendingOrderClaim>;
+  missingOrderConfirmations: Map<string, number>;
   status: OrderDataStatus;
 }
 
@@ -29,8 +30,10 @@ export interface OrderLocation {
 export interface PendingOrderClaim {
   localOrderId: string;
   symbol: string;
+  claimedAt: number;
 }
 
 export interface OrderManagerOptions {
   maxClosedOrdersPerSymbol?: number;
+  missingOrderEvictionThreshold?: number;
 }

package/src/managers/order/snapshot.ts

@@ -78,6 +78,7 @@ export function orderPriority(status: OrderSnapshot["status"]): number {
     case "expired":
       return 4;
     case "rejected":
+    case "unknown":
       return 3;
     case "partially_filled":
       return 2;

package/src/managers/order-manager.ts

@@ -5,6 +5,7 @@ import type {
 import type {
   AccountAwareManager,
   ClientContext,
+  ExpiredPendingOrderClaim,
   HealthReporter,
   ManagerLifecycle,
   PrivateOrderDataConsumer,
@@ -43,6 +44,7 @@ import {
   cloneOrderStatus,
   createOrderDataStatus,
   normalizeMaxClosedOrdersPerSymbol,
+  normalizeMissingOrderEvictionThreshold,
   successfulStatus,
 } from "./order/data-status.ts";
 import {
@@ -61,6 +63,7 @@ import { createSnapshot, isOpenOrder } from "./order/snapshot.ts";
 import {
   getAllSnapshots,
   getExistingSnapshot,
+  getExistingSnapshotLocation,
   getLocalOrderIdForVenueOrderId,
   getLocationByLocalOrderId,
   getOpenOrderSnapshots,
@@ -96,6 +99,7 @@ export class OrderManagerImpl
 
   private readonly context: ClientContext;
   private readonly maxClosedOrdersPerSymbol: number;
+  private readonly missingOrderEvictionThreshold: number;
   private readonly orderBus = new AsyncEventBus<OrderEvent>();
   private readonly orderStatusBus =
     new AsyncEventBus<OrderStatusChangedEvent>();
@@ -107,6 +111,9 @@ export class OrderManagerImpl
     this.maxClosedOrdersPerSymbol = normalizeMaxClosedOrdersPerSymbol(
       options.maxClosedOrdersPerSymbol,
     );
+    this.missingOrderEvictionThreshold = normalizeMissingOrderEvictionThreshold(
+      options.missingOrderEvictionThreshold,
+    );
 
     this.events = {
       status: (filter) =>
@@ -494,6 +501,9 @@ export class OrderManagerImpl
         openSetKeys.add(lookupKey);
       }
       const current = getExistingSnapshot(record, update);
+      if (current) {
+        this.clearMissingOrderConfirmationsForUpdate(record, current);
+      }
       const nextSnapshot = this.applyUpdateToRecord(
         record,
         accountId,
@@ -565,6 +575,36 @@ export class OrderManagerImpl
     return this.getOpenOrders(accountId);
   }
 
+  getExpiredPrivateOrderClaims(
+    accountId: string,
+    now: number,
+    ttlMs: number,
+  ): ExpiredPendingOrderClaim[] {
+    const record = this.records.get(accountId);
+    if (!record || ttlMs <= 0) {
+      return [];
+    }
+
+    const expired: ExpiredPendingOrderClaim[] = [];
+    for (const [
+      venueClientOrderId,
+      claim,
+    ] of record.pendingClientOrderIdIndex) {
+      if (now - claim.claimedAt < ttlMs) {
+        continue;
+      }
+
+      expired.push({
+        venueClientOrderId,
+        localOrderId: claim.localOrderId,
+        symbol: claim.symbol,
+        claimedAt: claim.claimedAt,
+      });
+    }
+
+    return expired;
+  }
+
   onPrivateOrderUpdate(
     accountId: string,
     venue: Venue,
@@ -590,32 +630,129 @@ export class OrderManagerImpl
       return;
     }
 
-    const eventType =
-      snapshot.status === "filled"
-        ? "order.filled"
-        : snapshot.status === "rejected"
-          ? "order.rejected"
-          : snapshot.status === "canceled" || snapshot.status === "expired"
-            ? "order.canceled"
-            : "order.updated";
+    this.publishOrderEvent(accountId, venue, snapshot);
 
-    this.orderBus.publish({
-      type: eventType,
+    record.status = successfulStatus(record.status, {
+      preserveStatus: options.preserveStatus,
+      lastReceivedAt: snapshot.receivedAt,
+      lastReadyAt: snapshot.updatedAt,
+    });
+    this.publishStatus(record);
+  }
+
+  onPrivateOrderConfirmedMissing(
+    accountId: string,
+    venue: Venue,
+    order: OrderSnapshot,
+  ): void {
+    const record = this.getOrCreateRecord(accountId, venue);
+    if (!record.subscribed) {
+      return;
+    }
+
+    const location = getExistingSnapshotLocation(record, order);
+    if (!location || location.table !== "open") {
+      return;
+    }
+
+    const current = getSnapshotAtLocation(record, location);
+    if (!current || !isOpenOrder(current)) {
+      return;
+    }
+
+    const confirmations =
+      (record.missingOrderConfirmations.get(location.localOrderId) ?? 0) + 1;
+    if (confirmations < this.missingOrderEvictionThreshold) {
+      record.missingOrderConfirmations.set(
+        location.localOrderId,
+        confirmations,
+      );
+      return;
+    }
+
+    const receivedAt = this.context.now();
+    const snapshot = createSnapshot(
       accountId,
       venue,
-      symbol: snapshot.symbol,
-      snapshot,
-      ts: this.context.now(),
-    });
+      {
+        orderId: current.orderId,
+        clientOrderId: current.clientOrderId,
+        symbol: current.symbol,
+        side: current.side,
+        type: current.type,
+        status: "unknown",
+        price: current.price,
+        triggerPrice: current.triggerPrice,
+        amount: current.amount,
+        filled: current.filled,
+        remaining: current.remaining,
+        reduceOnly: current.reduceOnly,
+        positionSide: current.positionSide,
+        avgFillPrice: current.avgFillPrice,
+        receivedAt,
+      },
+      current,
+    );
 
+    if (
+      !this.writeSnapshot(record, location.localOrderId, snapshot, location)
+    ) {
+      return;
+    }
+
+    this.context.publishRuntimeError(
+      "order",
+      new Error(
+        `Evicted ${venue} open order after ${confirmations} confirmed missing checks`,
+      ),
+      {
+        accountId,
+        venue,
+        symbol: current.symbol,
+      },
+    );
+    this.publishOrderEvent(accountId, venue, snapshot);
     record.status = successfulStatus(record.status, {
-      preserveStatus: options.preserveStatus,
       lastReceivedAt: snapshot.receivedAt,
       lastReadyAt: snapshot.updatedAt,
     });
     this.publishStatus(record);
   }
 
+  onPrivateOrderClaimNotFound(
+    accountId: string,
+    venue: Venue,
+    claim: ExpiredPendingOrderClaim,
+  ): void {
+    const record = this.records.get(accountId);
+    if (!record) {
+      return;
+    }
+
+    const pending = record.pendingClientOrderIdIndex.get(
+      claim.venueClientOrderId,
+    );
+    if (
+      pending?.localOrderId !== claim.localOrderId ||
+      pending.symbol !== claim.symbol
+    ) {
+      return;
+    }
+
+    record.pendingClientOrderIdIndex.delete(claim.venueClientOrderId);
+    this.context.publishRuntimeError(
+      "order",
+      new Error(
+        `createOrder timed out and the order was not found on the venue: ${claim.venueClientOrderId}`,
+      ),
+      {
+        accountId,
+        venue,
+        symbol: claim.symbol,
+      },
+    );
+  }
+
   onPrivateOrderStreamState(
     accountId: string,
     venue: Venue,
@@ -670,6 +807,7 @@ export class OrderManagerImpl
       orderIdOnlyIndex: new Map(),
       clientOrderIdIndex: new Map(),
       pendingClientOrderIdIndex: new Map(),
+      missingOrderConfirmations: new Map(),
       status: createOrderDataStatus(accountId, venue, "inactive"),
     };
 
@@ -718,9 +856,51 @@ export class OrderManagerImpl
 
     this.warnSystemClientOrderIdOnlyClaim(record, snapshot);
     this.warnProvisionalTerminalOrder(record, snapshot);
+    this.clearMissingOrderConfirmations(record, localOrderId);
     return true;
   }
 
+  private clearMissingOrderConfirmations(
+    record: OrderRecord,
+    localOrderId: string,
+  ): void {
+    record.missingOrderConfirmations.delete(localOrderId);
+  }
+
+  private clearMissingOrderConfirmationsForUpdate(
+    record: OrderRecord,
+    update: { symbol: string; orderId?: string; clientOrderId?: string },
+  ): void {
+    const location = getExistingSnapshotLocation(record, update);
+    if (location) {
+      this.clearMissingOrderConfirmations(record, location.localOrderId);
+    }
+  }
+
+  private publishOrderEvent(
+    accountId: string,
+    venue: Venue,
+    snapshot: OrderSnapshot,
+  ): void {
+    const eventType =
+      snapshot.status === "filled"
+        ? "order.filled"
+        : snapshot.status === "rejected"
+          ? "order.rejected"
+          : isOpenOrder(snapshot)
+            ? "order.updated"
+            : "order.canceled";
+
+    this.orderBus.publish({
+      type: eventType,
+      accountId,
+      venue,
+      symbol: snapshot.symbol,
+      snapshot,
+      ts: this.context.now(),
+    });
+  }
+
   private warnDroppedUnkeyedTerminalOrder(
     record: OrderRecord,
     snapshot: OrderSnapshot,
@@ -800,6 +980,9 @@ export class OrderManagerImpl
     options: { requestStartedAt?: number; preserveStatus?: boolean } = {},
   ): OrderSnapshot | undefined {
     const resolution = this.resolveLocalOrderIdForUpdate(record, update);
+    if (resolution.localOrderId) {
+      this.clearMissingOrderConfirmations(record, resolution.localOrderId);
+    }
     const localOrderId = resolution.localOrderId ?? this.generateLocalOrderId();
     const previousLocation = getLocationByLocalOrderId(record, localOrderId);
     const previous = previousLocation
@@ -874,6 +1057,7 @@ export class OrderManagerImpl
     record.pendingClientOrderIdIndex.set(venueClientOrderId, {
       localOrderId,
       symbol,
+      claimedAt: this.context.now(),
     });
   }
 
@@ -955,6 +1139,9 @@ export class OrderManagerImpl
       update,
       options.localOrderId,
     );
+    if (resolution.localOrderId) {
+      this.clearMissingOrderConfirmations(record, resolution.localOrderId);
+    }
     const localOrderId = resolution.localOrderId ?? this.generateLocalOrderId();
     const previousLocation = getLocationByLocalOrderId(record, localOrderId);
     const previous = previousLocation

package/src/types/order.ts

@@ -34,7 +34,8 @@ export type OrderStatus =
   | "filled"
   | "canceled"
   | "rejected"
-  | "expired";
+  | "expired"
+  | "unknown";
 
 export type CreateOrderType = "limit" | "market";
 

package/src/types/shared.ts

@@ -107,6 +107,8 @@ export interface AccountRuntimeOptions {
 
 export interface OrderRuntimeOptions {
   maxClosedOrdersPerSymbol?: number;
+  missingOrderEvictionThreshold?: number;
+  pendingClaimTtlMs?: number;
 }
 
 export interface CreateClientOptions {