@huskly/ibkr-client 0.14.0 → 0.15.0

package/dist/ibkr/ibkrClient.js

@@ -74,6 +74,7 @@ const IBKR_WORKING_STATUSES = new Set([
     "SUBMITTED",
     "PENDING_CANCEL",
 ]);
+const RECOVERY_TERMINAL_ORDER_FILTERS = ["filled", "cancelled", "inactive"];
 const KNOWN_ORDER_WARNING_IDS = new Set(["o163"]);
 /** Extract the canonical OSI symbol embedded in an IBKR option description. */
 function extractOsiPositionSymbol(contractDescription) {
@@ -100,6 +101,17 @@ function isHeadersLike(input) {
         input !== null &&
         typeof input.get === "function");
 }
+function isIbkrTrade(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return false;
+    const record = input;
+    return ((record["account"] === undefined || typeof record["account"] === "string") &&
+        (record["accountCode"] === undefined || typeof record["accountCode"] === "string") &&
+        (record["order_ref"] === undefined || typeof record["order_ref"] === "string") &&
+        (record["order_id"] === undefined ||
+            typeof record["order_id"] === "string" ||
+            typeof record["order_id"] === "number"));
+}
 function headerToString(value) {
     if (value === undefined || value === null)
         return undefined;
@@ -372,47 +384,121 @@ export class IbkrClient {
         this.validateOrderGraph(request);
         if (input.accountId !== request.accountId)
             throw new Error("Graph recovery account does not match request");
+        if (input.rootClientOrderId !== undefined &&
+            input.rootClientOrderId !== request.rootClientOrderId) {
+            throw new Error("Root client order ID does not match the requested graph");
+        }
+        if (input.orderId !== undefined && !input.orderId.trim()) {
+            throw new Error("An exact broker order ID is required for graph recovery");
+        }
         await this.prepareBrokerageAccount(input.accountId);
         const response = await this.req({
             path: "iserver/account/orders",
             params: { force: true, accountId: input.accountId },
         });
-        const accountOrders = (response.orders ?? []).filter((order) => this.orderBelongsToAccount(order, input.accountId));
-        const byMemberId = new Map();
+        const flattenedActiveSnapshot = this.flattenCompleteOrderSnapshot(response);
+        const activeSnapshotIncomplete = flattenedActiveSnapshot === null;
+        const invalidActiveAccountEvidence = flattenedActiveSnapshot?.some(({ order }) => !this.orderHasExactAccount(order, input.accountId)) ?? false;
+        const invalidNestedActiveEvidence = flattenedActiveSnapshot?.some(({ order, nestedParent }) => nestedParent !== null &&
+            !this.recoveryGraphOrderMayBeAttached(request, order) &&
+            this.recoveryGraphOrderIsAttached(request, nestedParent)) ?? false;
+        const accountOrders = (flattenedActiveSnapshot ?? [])
+            .map(({ order }) => order)
+            .filter((order) => this.orderHasExactAccount(order, input.accountId));
+        const activeMatchesByMember = new Map();
+        const observedCandidates = activeSnapshotIncomplete || invalidActiveAccountEvidence || invalidNestedActiveEvidence
+            ? [response]
+            : [];
+        observedCandidates.push(...accountOrders.filter((order) => this.recoveryGraphOrderMayBeAttached(request, order)));
         for (const node of request.nodes) {
-            const matches = accountOrders.filter((order) => this.liveOrderMatchesGraphNode(request, node, order));
-            const [match] = matches;
-            if (matches.length === 1 && match !== undefined)
-                byMemberId.set(node.memberId, match);
+            const matches = accountOrders.filter((order) => this.terminalOrderTicketIsValid(order) &&
+                this.orderHasValidRecoveryStatus(order) &&
+                this.recoveryOrderMatchesGraphNode(request, node, order));
+            activeMatchesByMember.set(node.memberId, matches);
         }
-        const candidates = [...byMemberId.values()];
-        const linkedOrders = accountOrders.filter((order) => (order.cOID ?? order.order_ref) === request.rootClientOrderId ||
-            String(order.parentId ?? "") === request.rootClientOrderId);
-        const candidateSet = new Set(candidates);
-        if (input.orderId !== undefined &&
-            !candidates.some((order) => String(order.order_id ?? order.orderId) === input.orderId)) {
-            throw new Error(`Broker order ${input.orderId} is not a member of the requested graph`);
+        const selected = new Map();
+        const usedOrderIds = new Set();
+        for (const node of request.nodes) {
+            const matches = activeMatchesByMember.get(node.memberId) ?? [];
+            const [match] = matches;
+            if (matches.length !== 1 || match === undefined)
+                continue;
+            const orderId = this.recoveryOrderId(match);
+            if (orderId === undefined)
+                continue;
+            if (usedOrderIds.has(orderId))
+                continue;
+            usedOrderIds.add(orderId);
+            selected.set(node.memberId, match);
+        }
+        const unresolved = request.nodes.filter((node) => !selected.has(node.memberId));
+        const terminalEvidence = await this.findRecoveryGraphTerminalCandidates(input.accountId, request, input.orderId);
+        this.reconcileSelectedGraphMembers(request, selected, terminalEvidence);
+        if (unresolved.length > 0) {
+            const assignments = this.assignRecoveryGraphCandidates(unresolved, terminalEvidence.byNode, usedOrderIds);
+            for (const node of unresolved) {
+                const order = assignments.get(node.memberId);
+                if (order === undefined)
+                    continue;
+                selected.set(node.memberId, order);
+                const orderId = this.recoveryOrderId(order);
+                if (orderId !== undefined)
+                    usedOrderIds.add(orderId);
+                observedCandidates.push(order);
+            }
         }
-        if (input.rootClientOrderId !== undefined &&
-            input.rootClientOrderId !== request.rootClientOrderId) {
-            throw new Error("Root client order ID does not match the requested graph");
+        observedCandidates.push(...terminalEvidence.observedResponses);
+        if (terminalEvidence.invalidAttachedEvidence) {
+            observedCandidates.push({ reason: "Invalid or conflicting terminal broker evidence" });
         }
+        const selectedCandidates = [...selected.values()];
+        const requestedOrderIdMissing = input.orderId !== undefined &&
+            !selectedCandidates.some((order) => this.recoveryOrderId(order) === input.orderId);
         const members = request.nodes.map((node) => {
-            const order = byMemberId.get(node.memberId);
+            const order = selected.get(node.memberId);
             return this.graphMemberEvidence(request, node, order);
         });
         const ids = members.flatMap(({ orderId }) => (orderId === null ? [] : [orderId]));
-        const brokerParentsMatch = request.nodes.every((node) => {
-            if (node.parentMemberId === undefined)
-                return true;
-            return (byMemberId.get(node.memberId) !== undefined &&
-                String(byMemberId.get(node.memberId)?.parentId ?? "") === request.rootClientOrderId);
-        });
-        if (candidates.length !== request.nodes.length ||
-            linkedOrders.length !== request.nodes.length ||
-            linkedOrders.some((order) => !candidateSet.has(order)) ||
-            new Set(ids).size !== request.nodes.length ||
-            !brokerParentsMatch) {
+        const hasDistinctOrderIds = new Set(ids).size === request.nodes.length;
+        const linkedOrderIds = new Set();
+        let linkedOrderMissingBrokerId = false;
+        for (const order of accountOrders) {
+            if (!this.recoveryGraphOrderMayBeAttached(request, order))
+                continue;
+            if (!this.recoveryGraphOrderIsAttached(request, order)) {
+                linkedOrderMissingBrokerId = true;
+                continue;
+            }
+            const orderId = this.recoveryOrderId(order);
+            if (orderId === undefined) {
+                linkedOrderMissingBrokerId = true;
+                continue;
+            }
+            linkedOrderIds.add(orderId);
+        }
+        for (const order of terminalEvidence.linkedOrders) {
+            const orderId = this.recoveryOrderId(order);
+            if (orderId === undefined) {
+                linkedOrderMissingBrokerId = true;
+                continue;
+            }
+            linkedOrderIds.add(orderId);
+        }
+        const selectedOrderIds = new Set(selectedCandidates.flatMap((order) => {
+            const orderId = this.recoveryOrderId(order);
+            return orderId === undefined ? [] : [orderId];
+        }));
+        if (selected.size !== request.nodes.length ||
+            !hasDistinctOrderIds ||
+            linkedOrderMissingBrokerId ||
+            [...linkedOrderIds].some((orderId) => !selectedOrderIds.has(orderId)) ||
+            requestedOrderIdMissing ||
+            activeSnapshotIncomplete ||
+            invalidActiveAccountEvidence ||
+            invalidNestedActiveEvidence ||
+            terminalEvidence.invalidAttachedEvidence ||
+            terminalEvidence.terminalSnapshotLookupFailed ||
+            members.some(({ status }) => status === "UNKNOWN" || status === "WARNING_PENDING")) {
             return {
                 state: "recovery_required",
                 rootClientOrderId: request.rootClientOrderId,
@@ -422,7 +508,7 @@ export class IbkrClient {
                 ],
                 warnings: [],
                 errors: [],
-                unrecognizedResponses: [],
+                unrecognizedResponses: observedCandidates,
             };
         }
         return {
@@ -432,6 +518,362 @@ export class IbkrClient {
             warnings: [],
         };
     }
+    reconcileSelectedGraphMembers(request, selected, terminalEvidence) {
+        for (const node of request.nodes) {
+            const selectedOrder = selected.get(node.memberId);
+            const selectedOrderId = selectedOrder === undefined ? undefined : this.recoveryOrderId(selectedOrder);
+            if (selectedOrderId === undefined)
+                continue;
+            const terminalMatches = new Map();
+            for (const order of terminalEvidence.byNode.get(node.memberId) ?? []) {
+                const orderId = this.recoveryOrderId(order);
+                if (orderId === selectedOrderId)
+                    terminalMatches.set(orderId, order);
+            }
+            const terminalLinked = terminalMatches.size > 0 ||
+                terminalEvidence.linkedOrders.some((order) => this.recoveryOrderId(order) === selectedOrderId && this.isTerminalRecoveryOrder(order));
+            if (!terminalLinked)
+                continue;
+            if (terminalMatches.size !== 1) {
+                terminalEvidence.invalidAttachedEvidence = true;
+                continue;
+            }
+            const [terminalOrder] = terminalMatches.values();
+            if (terminalOrder !== undefined)
+                selected.set(node.memberId, terminalOrder);
+        }
+    }
+    isTerminalRecoveryOrder(order) {
+        const status = this.canonicalIbkrOrderStatus(order.order_status ?? order.orderStatus ?? order.status);
+        return (status === "FILLED" ||
+            status === "CANCELLED" ||
+            status === "INACTIVE" ||
+            status === "REJECTED");
+    }
+    async findRecoveryGraphTerminalCandidates(accountId, request, knownOrderId) {
+        const byNode = new Map();
+        for (const node of request.nodes)
+            byNode.set(node.memberId, []);
+        const linkedOrders = [];
+        const observedResponses = [];
+        let invalidAttachedEvidence = false;
+        let terminalSnapshotLookupFailed = false;
+        const candidateOrderIds = new Set();
+        if (knownOrderId !== undefined)
+            candidateOrderIds.add(knownOrderId);
+        const terminalOrdersById = new Map();
+        for (const filter of RECOVERY_TERMINAL_ORDER_FILTERS) {
+            try {
+                const response = await this.req({
+                    path: "iserver/account/orders",
+                    params: { force: true, accountId, filters: filter },
+                });
+                const flattenedSnapshot = this.flattenCompleteOrderSnapshot(response);
+                if (flattenedSnapshot === null) {
+                    terminalSnapshotLookupFailed = true;
+                    observedResponses.push({ source: "terminal_order_snapshot", filter, response });
+                    continue;
+                }
+                for (const { order, nestedParent } of flattenedSnapshot) {
+                    if (!this.recoveryGraphOrderMayBeAttached(request, order)) {
+                        if (nestedParent === null ||
+                            !this.recoveryGraphOrderIsAttached(request, nestedParent)) {
+                            continue;
+                        }
+                        observedResponses.push(order);
+                        linkedOrders.push(order);
+                        invalidAttachedEvidence = true;
+                        continue;
+                    }
+                    observedResponses.push(order);
+                    if (!this.recoveryGraphOrderIsAttached(request, order)) {
+                        linkedOrders.push(order);
+                        invalidAttachedEvidence = true;
+                        continue;
+                    }
+                    if (!this.orderHasExactAccount(order, accountId)) {
+                        invalidAttachedEvidence = true;
+                        continue;
+                    }
+                    if (!this.terminalOrderTicketIsValid(order) || !this.orderHasValidRecoveryStatus(order)) {
+                        linkedOrders.push(order);
+                        invalidAttachedEvidence = true;
+                        continue;
+                    }
+                    const orderId = this.recoveryOrderId(order);
+                    if (orderId === undefined) {
+                        linkedOrders.push(order);
+                        invalidAttachedEvidence = true;
+                        continue;
+                    }
+                    const previousOrder = terminalOrdersById.get(orderId);
+                    if (previousOrder !== undefined &&
+                        (this.terminalOrderTicketConflicts(previousOrder, order) ||
+                            this.recoveryGraphAttachmentKey(request, previousOrder) !==
+                                this.recoveryGraphAttachmentKey(request, order))) {
+                        invalidAttachedEvidence = true;
+                        linkedOrders.push(order);
+                        continue;
+                    }
+                    terminalOrdersById.set(orderId, order);
+                    linkedOrders.push(order);
+                    candidateOrderIds.add(orderId);
+                }
+            }
+            catch (error) {
+                terminalSnapshotLookupFailed = true;
+                observedResponses.push({
+                    source: "terminal_order_snapshot",
+                    filter,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        const tradeEvidenceById = new Map();
+        try {
+            const response = await this.req({
+                path: "iserver/account/trades",
+                params: { days: 7 },
+            });
+            if (Array.isArray(response)) {
+                for (const rawTrade of response) {
+                    if (typeof rawTrade !== "object" || rawTrade === null || Array.isArray(rawTrade))
+                        continue;
+                    const tradeRecord = rawTrade;
+                    const orderRef = this.trimmedString(tradeRecord["order_ref"]);
+                    const parentRef = this.recoveryOrderId({
+                        order_id: tradeRecord["parent_order_ref"],
+                        orderId: tradeRecord["parentOrderRef"],
+                    });
+                    if (orderRef !== request.rootClientOrderId && parentRef !== request.rootClientOrderId) {
+                        continue;
+                    }
+                    const accounts = [tradeRecord["account"], tradeRecord["accountCode"]].filter((value) => value !== undefined);
+                    if (accounts.length > 0 &&
+                        accounts.every((value) => typeof value === "string" && value !== accountId)) {
+                        continue;
+                    }
+                    if (accounts.length === 0 ||
+                        accounts.some((value) => typeof value !== "string" || value !== accountId) ||
+                        !isIbkrTrade(rawTrade)) {
+                        observedResponses.push(rawTrade);
+                        invalidAttachedEvidence = true;
+                        continue;
+                    }
+                    const orderId = this.recoveryOrderId(rawTrade);
+                    if (orderId === undefined) {
+                        observedResponses.push(rawTrade);
+                        invalidAttachedEvidence = true;
+                        continue;
+                    }
+                    candidateOrderIds.add(orderId);
+                    tradeEvidenceById.set(orderId, {
+                        ...rawTrade,
+                        account: accountId,
+                        order_id: orderId,
+                    });
+                }
+            }
+        }
+        catch {
+            // Exact broker IDs and terminal order snapshots remain usable when trade history is unavailable.
+        }
+        for (const orderId of candidateOrderIds) {
+            const terminalOrder = terminalOrdersById.get(orderId);
+            try {
+                const order = await this.req({
+                    path: `iserver/account/order/status/${encodeURIComponent(orderId)}`,
+                });
+                observedResponses.push(order);
+                if (!this.orderMatchesExactRecoveryIdentity(order, accountId, orderId)) {
+                    invalidAttachedEvidence = true;
+                    continue;
+                }
+                if (!this.orderHasValidRecoveryStatus(order)) {
+                    invalidAttachedEvidence = true;
+                    terminalOrdersById.delete(orderId);
+                    continue;
+                }
+                if (!this.terminalOrderTicketIsValid(order)) {
+                    invalidAttachedEvidence = true;
+                    terminalOrdersById.delete(orderId);
+                    continue;
+                }
+                if (terminalOrder !== undefined &&
+                    this.terminalOrderTicketConflicts(terminalOrder, order)) {
+                    invalidAttachedEvidence = true;
+                    terminalOrdersById.delete(orderId);
+                    continue;
+                }
+                if (terminalOrder !== undefined &&
+                    this.recoveryGraphAttachmentKey(request, terminalOrder) !==
+                        this.recoveryGraphAttachmentKey(request, order)) {
+                    invalidAttachedEvidence = true;
+                    terminalOrdersById.delete(orderId);
+                    continue;
+                }
+                if (!this.recoveryGraphOrderIsAttached(request, order)) {
+                    invalidAttachedEvidence = true;
+                    terminalOrdersById.delete(orderId);
+                    continue;
+                }
+                const resolvedOrder = terminalOrder === undefined ? order : { ...terminalOrder, ...order };
+                terminalOrdersById.set(orderId, resolvedOrder);
+                if (terminalOrder === undefined)
+                    linkedOrders.push(resolvedOrder);
+            }
+            catch (error) {
+                observedResponses.push({
+                    source: "terminal_order_status",
+                    orderId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                if (terminalOrder === undefined) {
+                    const tradeEvidence = tradeEvidenceById.get(orderId);
+                    if (tradeEvidence !== undefined) {
+                        linkedOrders.push(tradeEvidence);
+                        observedResponses.push(tradeEvidence);
+                    }
+                    continue;
+                }
+            }
+            const resolvedOrder = terminalOrdersById.get(orderId) ?? terminalOrder;
+            if (resolvedOrder === undefined)
+                continue;
+            if (!this.orderHasExactAccount(resolvedOrder, accountId)) {
+                invalidAttachedEvidence = true;
+                continue;
+            }
+            for (const node of request.nodes) {
+                if (this.terminalOrderMatchesGraphNode(request, node, resolvedOrder)) {
+                    const existing = byNode.get(node.memberId);
+                    if (existing !== undefined)
+                        existing.push(resolvedOrder);
+                }
+            }
+        }
+        return {
+            byNode,
+            linkedOrders,
+            observedResponses,
+            invalidAttachedEvidence,
+            terminalSnapshotLookupFailed,
+        };
+    }
+    recoveryGraphOrderIsAttached(request, order) {
+        return this.recoveryGraphAttachmentKey(request, order) !== null;
+    }
+    recoveryGraphOrderMayBeAttached(request, order) {
+        return [
+            order.cOID,
+            order.order_ref,
+            order.parentId,
+            order.parent_id,
+            order.parentClientOrderId,
+            order.parent_order_ref,
+        ].some((value) => (typeof value === "string" || typeof value === "number") &&
+            String(value).trim() === request.rootClientOrderId);
+    }
+    recoveryGraphAttachmentKey(request, order) {
+        const parentIdentity = this.consistentStringAliases(order.parentId, order.parent_id, order.parentClientOrderId, order.parent_order_ref);
+        const clientIdentity = this.consistentStringAliases(order.cOID, order.order_ref);
+        if (!parentIdentity.valid || !clientIdentity.valid)
+            return null;
+        const parentId = parentIdentity.value ?? "";
+        if (parentId === request.rootClientOrderId)
+            return "child";
+        const clientOrderId = clientIdentity.value;
+        if (clientOrderId === request.rootClientOrderId && parentId === "")
+            return "root";
+        return null;
+    }
+    terminalOrderTicketConflicts(first, second) {
+        const firstTicket = this.terminalOrderTicketFingerprint(first);
+        const secondTicket = this.terminalOrderTicketFingerprint(second);
+        return Object.keys(firstTicket).some((field) => field in secondTicket && firstTicket[field] !== secondTicket[field]);
+    }
+    terminalOrderTicketIsValid(order) {
+        return !Object.values(this.terminalOrderTicketFingerprint(order)).includes("__MALFORMED_TERMINAL_TICKET_FIELD__");
+    }
+    terminalOrderTicketFingerprint(order) {
+        const ticket = {};
+        const malformed = "__MALFORMED_TERMINAL_TICKET_FIELD__";
+        const addAliases = (field, values, normalize) => {
+            const provided = values.filter((value) => value !== undefined);
+            if (provided.length === 0)
+                return;
+            const normalized = provided.map(normalize);
+            const [first] = normalized;
+            ticket[field] =
+                first !== undefined && normalized.every((value) => value === first) ? first : malformed;
+        };
+        const normalizeNumber = (value) => {
+            if (typeof value === "number" && Number.isFinite(value)) {
+                return String(value);
+            }
+            if (typeof value === "string" && value.trim() !== "") {
+                const numeric = Number(value);
+                return Number.isFinite(numeric) ? String(numeric) : undefined;
+            }
+            return undefined;
+        };
+        addAliases("conid", [order.conid], normalizeNumber);
+        if (order.conidex !== undefined) {
+            ticket["conidex"] =
+                typeof order.conidex === "string"
+                    ? JSON.stringify(this.parseComboLegs(order.conidex))
+                    : malformed;
+        }
+        addAliases("orderType", [order.order_type, order.orderType], (value) => typeof value === "string" ? this.normalizeOrderType(value) : undefined);
+        addAliases("side", [order.side], (value) => typeof value === "string" ? this.normalizeOrderSide(value) : undefined);
+        addAliases("quantity", [order.total_size, order.totalSize, order.size], normalizeNumber);
+        addAliases("price", [order.limitPrice, order.limit_price, order.stopPrice, order.price], normalizeNumber);
+        addAliases("tif", [order.tif, order.timeInForce], (value) => typeof value === "string" ? value.toUpperCase() : undefined);
+        addAliases("outsideRTH", [order.outsideRTH, order.outside_rth], (value) => typeof value === "boolean" ? value : undefined);
+        return ticket;
+    }
+    orderHasExactAccount(order, accountId) {
+        const accounts = [order.account, order.acct];
+        const provided = accounts.filter((account) => account !== undefined);
+        return (provided.length > 0 &&
+            provided.every((account) => typeof account === "string" && account === accountId));
+    }
+    orderMatchesExactRecoveryIdentity(order, accountId, orderId) {
+        return this.orderHasExactAccount(order, accountId) && this.recoveryOrderId(order) === orderId;
+    }
+    orderHasValidRecoveryStatus(order) {
+        const provided = [order.order_status, order.orderStatus, order.status].filter((status) => status !== undefined);
+        if (provided.length === 0)
+            return true;
+        const normalized = provided.map((status) => this.canonicalIbkrOrderStatus(status));
+        const [first] = normalized;
+        return first !== undefined && normalized.every((status) => status === first);
+    }
+    assignRecoveryGraphCandidates(unresolvedNodes, terminalCandidates, usedOrderIds) {
+        const assignments = new Map();
+        const uniqueCandidates = new Map();
+        for (const node of unresolvedNodes) {
+            const candidates = terminalCandidates.get(node.memberId) ?? [];
+            if (candidates.length !== 1)
+                continue;
+            const order = candidates[0];
+            if (order === undefined)
+                continue;
+            const orderId = this.recoveryOrderId(order);
+            if (orderId === undefined || usedOrderIds.has(orderId))
+                continue;
+            const owners = uniqueCandidates.get(orderId) ?? [];
+            owners.push({ node, order });
+            uniqueCandidates.set(orderId, owners);
+        }
+        for (const owners of uniqueCandidates.values()) {
+            const owner = owners[0];
+            if (owners.length !== 1 || owner === undefined)
+                continue;
+            assignments.set(owner.node.memberId, owner.order);
+        }
+        return assignments;
+    }
     async acknowledgeOrderWarning(input) {
         if (!input.replyId.trim())
             throw new Error("An exact warning reply ID is required");
@@ -468,12 +910,12 @@ export class IbkrClient {
         const order = await this.req({
             path: `iserver/account/order/status/${encodeURIComponent(orderId)}`,
         });
-        if (String(order.order_id ?? order.orderId ?? "") !== orderId) {
-            throw new Error(`IBKR response does not match the requested order ${orderId}`);
-        }
-        if ((order.account ?? order.acct) !== accountId) {
+        if (!this.orderHasExactAccount(order, accountId)) {
             throw new Error(`IBKR order ${orderId} does not belong to the requested account`);
         }
+        if (this.recoveryOrderId(order) !== orderId) {
+            throw new Error(`IBKR response does not match the requested order ${orderId}`);
+        }
         const lifecycle = this.normalizeDerivativeOrderLifecycle(accountId, orderId, order);
         if (lifecycle.status === "UNKNOWN") {
             throw new Error(`IBKR order ${orderId} returned an unrecognized status`);
@@ -515,10 +957,10 @@ export class IbkrClient {
             path: "iserver/account/orders",
             params: { force: true, accountId },
         });
-        if (response.snapshot !== true || !Array.isArray(response.orders)) {
+        const flattened = this.flattenCompleteOrderSnapshot(response);
+        if (flattened === null) {
             throw new Error("IBKR active-order snapshot is incomplete");
         }
-        const flattened = this.flattenActiveOrders(response.orders);
         const invalidAccountEvidence = flattened.find(({ order }) => {
             const returnedAccounts = [order.account, order.acct];
             const providedAccounts = returnedAccounts.filter((value) => value !== undefined);
@@ -942,13 +1384,17 @@ export class IbkrClient {
         };
     }
     liveOrderMatchesGraphNode(request, node, order) {
+        const parentIdentity = this.consistentStringAliases(order.parentId, order.parent_id, order.parentClientOrderId, order.parent_order_ref);
+        if (!parentIdentity.valid)
+            return false;
         if (node.parentMemberId === undefined) {
-            if ((order.cOID ?? order.order_ref) !== request.rootClientOrderId)
+            const clientIdentity = this.consistentStringAliases(order.cOID, order.order_ref);
+            if (!clientIdentity.valid || clientIdentity.value !== request.rootClientOrderId)
                 return false;
-            if (String(order.parentId ?? "").trim() !== "")
+            if (parentIdentity.value !== undefined)
                 return false;
         }
-        else if (String(order.parentId ?? "") !== request.rootClientOrderId)
+        else if (parentIdentity.value !== request.rootClientOrderId)
             return false;
         if ("legs" in node) {
             const liveLegs = this.parseComboLegs(order.conidex);
@@ -958,6 +1404,7 @@ export class IbkrClient {
             const price = this.firstNumber(order.limitPrice, order.limit_price, order.price);
             const expectedPrice = node.priceEffect === "CREDIT" ? -node.limit : node.limit;
             const outsideRth = order.outsideRTH ?? order.outside_rth;
+            const tif = order.tif ?? order.timeInForce;
             return (liveLegs.length === node.legs.length &&
                 node.legs.every((leg, index) => {
                     const liveLeg = liveLegs[index];
@@ -967,7 +1414,7 @@ export class IbkrClient {
                 side === "BUY" &&
                 quantity === node.quantity &&
                 price === expectedPrice &&
-                (order.tif === undefined || order.tif.toUpperCase() === node.tif) &&
+                (tif === undefined || tif.toUpperCase() === node.tif) &&
                 (outsideRth === undefined || outsideRth === (node.session === "OVERNIGHT")));
         }
         const orderType = this.normalizeOrderType(order.order_type ?? order.orderType);
@@ -981,14 +1428,39 @@ export class IbkrClient {
                 : undefined;
         const expectedPrice = node.orderType === "LMT" ? node.limit : node.orderType === "STP" ? node.stopPrice : undefined;
         const outsideRth = order.outsideRTH ?? order.outside_rth;
+        const tif = order.tif ?? order.timeInForce;
         return (order.conid === node.contract.conid &&
             orderType === expectedOrderType &&
             side === node.side &&
             quantity === node.quantity &&
             price === expectedPrice &&
-            (order.tif === undefined || order.tif.toUpperCase() === node.tif) &&
+            (tif === undefined || tif.toUpperCase() === node.tif) &&
             (outsideRth === undefined || outsideRth === (node.session === "OVERNIGHT")));
     }
+    recoveryOrderMatchesGraphNode(request, node, order) {
+        try {
+            return this.liveOrderMatchesGraphNode(request, node, order);
+        }
+        catch {
+            return false;
+        }
+    }
+    terminalOrderMatchesGraphNode(request, node, order) {
+        try {
+            const tif = order.tif ?? order.timeInForce;
+            const outsideRth = order.outsideRTH ?? order.outside_rth;
+            const status = order.order_status ?? order.orderStatus ?? order.status;
+            if (typeof tif !== "string" ||
+                typeof outsideRth !== "boolean" ||
+                typeof status !== "string") {
+                return false;
+            }
+            return this.recoveryOrderMatchesGraphNode(request, node, order);
+        }
+        catch {
+            return false;
+        }
+    }
     validateSingleOrder(request) {
         this.validateSingleOrderFields(request);
         const identityFields = request;
@@ -1486,11 +1958,42 @@ export class IbkrClient {
             updatedAt: this.parseOrderTime(order)?.toISOString() ?? null,
         };
     }
-    flattenActiveOrders(orders, nestedParent = null) {
-        return orders.flatMap((order) => {
-            const children = [...new Set([...(order.childOrders ?? []), ...(order.children ?? [])])];
-            return [{ order, nestedParent }, ...this.flattenActiveOrders(children, order)];
-        });
+    flattenCompleteOrderSnapshot(response) {
+        if (typeof response !== "object" || response === null || Array.isArray(response))
+            return null;
+        const record = response;
+        if (record["snapshot"] !== true || !Array.isArray(record["orders"]))
+            return null;
+        const flattened = [];
+        const visiting = new Set();
+        const visit = (orders, nestedParent) => {
+            for (const rawOrder of orders) {
+                if (typeof rawOrder !== "object" || rawOrder === null || Array.isArray(rawOrder))
+                    return false;
+                if (visiting.has(rawOrder))
+                    return false;
+                visiting.add(rawOrder);
+                const orderRecord = rawOrder;
+                const childCollections = [orderRecord["childOrders"], orderRecord["children"]];
+                if (childCollections.some((children) => children !== undefined && !Array.isArray(children))) {
+                    return false;
+                }
+                const order = rawOrder;
+                flattened.push({ order, nestedParent });
+                const children = new Set();
+                for (const collection of childCollections) {
+                    if (Array.isArray(collection)) {
+                        for (const child of collection)
+                            children.add(child);
+                    }
+                }
+                if (!visit([...children], order))
+                    return false;
+                visiting.delete(rawOrder);
+            }
+            return true;
+        };
+        return visit(record["orders"], null) ? flattened : null;
     }
     normalizeActiveDerivativeOrder(accountId, order, nestedParent) {
         const uncertainty = [];
@@ -1694,8 +2197,39 @@ export class IbkrClient {
         const parsed = new Date(`${year}-${month}-${day}T${hour}:${minute}:${second}Z`);
         return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
     }
+    recoveryOrderId(order) {
+        const identity = this.consistentScalarAliases(order.order_id, order.orderId);
+        return identity.valid ? identity.value : undefined;
+    }
+    consistentScalarAliases(...aliases) {
+        const provided = aliases.filter((alias) => alias !== undefined);
+        if (provided.length === 0)
+            return { valid: true, value: undefined };
+        const normalized = provided.map((alias) => {
+            if (typeof alias !== "string" && typeof alias !== "number")
+                return undefined;
+            const value = String(alias).trim();
+            return value.length === 0 ? undefined : value;
+        });
+        const [first] = normalized;
+        if (first === undefined || normalized.some((value) => value !== first)) {
+            return { valid: false, value: undefined };
+        }
+        return { valid: true, value: first };
+    }
+    consistentStringAliases(...aliases) {
+        const provided = aliases.filter((alias) => alias !== undefined);
+        if (provided.length === 0)
+            return { valid: true, value: undefined };
+        const normalized = provided.map((alias) => typeof alias === "string" && alias.trim() !== "" ? alias.trim() : undefined);
+        const [first] = normalized;
+        if (first === undefined || normalized.some((value) => value !== first)) {
+            return { valid: false, value: undefined };
+        }
+        return { valid: true, value: first };
+    }
     trimmedString(value) {
-        if (value === undefined)
+        if (typeof value !== "string")
             return null;
         const trimmed = value.trim();
         return trimmed.length === 0 ? null : trimmed;
@@ -1875,8 +2409,10 @@ export class IbkrClient {
         return "UNKNOWN";
     }
     canonicalIbkrOrderStatus(value) {
+        if (typeof value !== "string")
+            return undefined;
         return value
-            ?.replace(/([a-z])([A-Z])/g, "$1_$2")
+            .replace(/([a-z])([A-Z])/g, "$1_$2")
             .replace(/\s+/g, "_")
             .toUpperCase();
     }